[Mesa-dev] [PATCH] docs: add documentation for building with meson

Wed Nov 8 19:05:24 UTC 2017

On 11/08/2017 10:59 AM, Ian Romanick wrote:
> Is there a way to get a list of options before having any success?  I
> want to disable using LLVM, but I can't get the list of options to do so
> because I don't have libelf (required for LLVM... which I don't want):
> 
> Dependency libelf found: NO
> 
> Meson encountered an error in file meson.build, line 628, column 2:
> C library 'elf' not found

I guess the answer is 'less meson-options.txt'. :)  Should probably
document that for us n00bs.

> On 11/07/2017 09:28 AM, Dylan Baker wrote:
>> v2: - Add information about CC, CXX, CFLAGS, and CXXFLAGS (Nicolai)
>>     - Add message at top that meson for mesa is still a work in progress
>>     - Add trailing "/" to directories (Eric E.)
>>     - Fix a number of spelling/grammar/style suggestions from Eric E.
>>     - Make a number of changes as suggested by Emil.
>> v3: - Fix order of commands in example (Eric E.)
>>     - Add documentation for overriding LLVM version (Eric E.)
>> v4: - Rebase on master
>>     - update default buildtype
>>     - add note about b_ndebug
>>     - Clarify meson configure a bit
>>
>> Signed-off-by: Dylan Baker <dylanx.c.baker at intel.com>
>> Reviewed-by: Eric Engestrom <eric at engestrom.ch> (v3)
>> ---
>>  docs/contents.html |   1 +
>>  docs/meson.html    | 151 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 152 insertions(+)
>>  create mode 100644 docs/meson.html
>>
>> diff --git a/docs/contents.html b/docs/contents.html
>> index d5455421091..9a86019e2f6 100644
>> --- a/docs/contents.html
>> +++ b/docs/contents.html
>> @@ -43,6 +43,7 @@
>>  <li><a href="install.html" target="_parent">Compiling / Installing</a>
>>    <ul>
>>      <li><a href="autoconf.html" target="_parent">Autoconf</a></li>
>> +    <li><a href="meson.html" target="_parent">Meson</a></li>
>>    </ul>
>>  </li>
>>  <li><a href="precompiled.html" target="_parent">Precompiled Libraries</a>
>> diff --git a/docs/meson.html b/docs/meson.html
>> new file mode 100644
>> index 00000000000..ee505b1d5ee
>> --- /dev/null
>> +++ b/docs/meson.html
>> @@ -0,0 +1,151 @@
>> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
>> +<html lang="en">
>> +<head>
>> +  <meta http-equiv="content-type" content="text/html; charset=utf-8">
>> +  <title>Compilation and Installation using Meson</title>
>> +  <link rel="stylesheet" type="text/css" href="mesa.css">
>> +</head>
>> +<body>
>> +
>> +<div class="header">
>> +  <h1>The Mesa 3D Graphics Library</h1>
>> +</div>
>> +
>> +<iframe src="contents.html"></iframe>
>> +<div class="content">
>> +
>> +<h1>Compilation and Installation using Meson</h1>
>> +
>> +<h2 id="basic">1. Basic Usage</h2>
>> +
>> +<p><strong>The Meson build system for Mesa is still under active development,
>> +and should not be used in production environments.</strong></p>
>> +
>> +<p>The meson build is currently only tested on linux, and is known to not work
>> +on macOS, Windows, and haiku. This will be fixed.</p>
>> +
>> +<p>
>> +The meson program is used to configure the source directory and generates
>> +either a ninja build file, or Visual Studio® build files. The latter, and must
>> +be enabled via the --backend switch, as ninja is always the default. Meson only
>> +supports out-of-tree builds, and must be passed a directory to put built and
>> +generated sources into. We'll call that directory "build" for examples.
>> +</p>
>> +
>> +<pre>
>> +    meson build/
>> +</pre>
>> +
>> +<p>
>> +To see a description of your options you can run "meson configure" along with a
>> +build directory to view the selected options for. This will show your meson
>> +global arguments and project arguments, along with their defaults and your
>> +local settings.
>> +</p>
>> +
>> +<pre>
>> +    meson configure build/
>> +</pre>
>> +
>> +<p>
>> +With additional arguments "meson configure" is used to change options on
>> +already configured build directory. All options passed to this command are in
>> +the form -D"command"="value".
>> +</p>
>> +
>> +<pre>
>> +    meson configure build/ -Dprefix=/tmp/install -Dglx=true
>> +</pre>
>> +
>> +<p>
>> +Once you've run meson successfully you can use your configured backend to build
>> +the project. With ninja, the -C option can be be used to point at a directory
>> +to build.
>> +</p>
>> +
>> +<pre>
>> +    ninja -C build/
>> +</pre>
>> +
>> +<p>
>> +Without arguments, it will produce libGL.so and/or several other libraries
>> +depending on the options you have chosen. Later, if you want to rebuild for a
>> +different configuration, you should run <code>ninja clean</code> before
>> +rebuilding, or create a new out of tree build directory (meson supports an
>> +unlimited number of them) for each configuration you want to build.
>> +</p>
>> +
>> +<dt><code>CC, CFLAGS, CXX, CXXFLAGS</code></dt>
>> +<dd><p>These environment variables
>> +control the C and C++ compilers used during the build. The default compilers
>> +depends on your operating system. Meson supports most of the popular compilers,
>> +a complete list is available
>> +<a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>.
>> +
>> +These arguments are consumed and stored by meson when it is initialized or
>> +re-initialized. Therefore passing them to meson configure will not do anything,
>> +and passing them to ninja will only do something if ninja decides to
>> +re-initialze meson, for example, if a meson.build file has been changed.
>> +Changing these variables will not cause all targets to be rebuilt, so running
>> +ninja clean is recomended when changing CFLAGS or CXXFLAGS. meson will never
>> +change compiler in a configured build directory.
>> +</p>
>> +
>> +<pre>
>> +    CC=clang CXX=clang++ meson build-clang
>> +    ninja -C build-clang
>> +    ninja -C build-clang clean
>> +    touch meson.build
>> +    CFLAGS=-Wno-typedef-redefinition ninja -C build-clang
>> +</pre>
>> +</dd>
>> +
>> +<dt><code>LLVM</code></dt>
>> +<dd><p>Meson includes upstream logic to wrap llvm-config using it's standard
>> +dependncy interface. It will search $PATH (or %PATH% on windows) for
>> +llvm-config, so using an LLVM from a non-standard path is as easy as
>> +<code>PATH=/path/with/llvm-config:$PATH meson build</code>.
>> +</p></dd>
>> +</dl>
>> +
>> +<dt><code>PKG_CONFIG_PATH</code></dt>
>> +<dd><p>The
>> +<code>pkg-config</code> utility is a hard requirement for configuring and
>> +building Mesa on Linux and *BSD. It is used to search for external libraries
>> +on the system. This environment variable is used to control the search
>> +path for <code>pkg-config</code>. For instance, setting
>> +<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for
>> +package metadata in <code>/usr/X11R6</code> before the standard
>> +directories.</p>
>> +</dd>
>> +</dl>
>> +
>> +<p>
>> +One of the oddities of meson is that some options are different when passed to
>> +the <code>meson</code> than to <code>meson configure</code>. These options are
>> +passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson
>> +configure</code>. Mesa defined options are always passed as -Doption=foo.
>> +<p>
>> +
>> +<p>For those coming from autotools be aware of the following:</p>
>> +
>> +<dl>
>> +<dt><code>--buildtype/-Dbuildtype</code></dt>
>> +<dd><p>This option will set the compiler debug/optimisation levels to aid
>> +debugging the Mesa libraries.</p>
>> +
>> +<p>Note that in meson this defaults to "debugoptimized", and  not setting it to
>> +"release" will yield non-optimal performance and binary size.</p>
>> +
>> +<p> For those wishing to pass their own -O option, use the "plain" buildtype,
>> +which cuases meson to inject no additional compiler arguments, only those in
>> +the C/CXXFLAGS and those that mesa itself defines.</p>
>> +</dd>
>> +</dl>
>> +
>> +<dl>
>> +<dt><code>-Db_ndebug</code></dt>
>> +<dd><p>This option controls assertions in meson projects. When set to false
>> +(the default) assertions are enabled, when set to true they are disabled.</p>
>> +</dd>
>> +</dl>
>>
> 
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev
> 