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

Wed Nov 8 18:56:06 UTC 2017

Quoting Eric Engestrom (2017-11-08 04:00:54)
> On Tuesday, 2017-11-07 09:28:35 -0800, 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
> 
> missing words in that last sentence
> 
> > +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
> 
> <code>meson configure</code>
> 
> same for the other commands in this page, as this is the way we show
> them in the rest of the docs
> 
> > +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.
> 
> + Meson does not currently support listing options before configuring
> + a build directory, but this feature is being discussed upstream.
> 
> (since the question came up a couple times already)
> 
> > +</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".
> 
> Doesn't matter to meson, but I'd put a space between `-D` and
> `"command"="value"` to make it more readable.
> 
> > +</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
> 
> "Once you've run the initial <code>meson</code> successfully"
> ("initial" being the important change)
> 
> > +the project.
> 
> + You probably don't need to ever run <code>meson</code> after that,
> + as running <code>ninja</code> (and other backends) automatically detects
> + changes and re-configures the project as needed. If you think some change
> + is not being detected correctly, you can always run
> + <code>ninja reconfigure</code> manually.
> 
> > 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,
> 
> before changing the configuration, I think?
> 
> Feels weird to give this advice though. One of the arguments for having
> your build out of tree is that your various build configurations don't
> interfere with each other, so let's just suggest
> "different config? different build dir"
> 
> > or create a new out of tree build directory (meson supports an
> > +unlimited number of them) for each configuration you want to build.
> 
> This "unlimited build dirs" sentence looks weird to me every time I read
> it. Why would there be a limit to the number of build dirs?
> Maybe saying something like "meson doesn't restrict you to a single
> build dir" would be clearer, but mentioning it at all still feels weird.
> 
> Maybe add a link to the meson doc on out of tree builds?
> http://mesonbuild.com/Using-multiple-build-directories.html
> 
> > +</p>
> > +
> > +<dt><code>CC, CFLAGS, CXX, CXXFLAGS</code></dt>
> 
> weird to list them, but if you do, might as well have LDFLAGS in the
> list :)
> 
> > +<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>
> 
> + and not setting it to "debug" might interfere with your ability to
> + debug Mesa, as some code & variables will be optimised out.
> 
> > +
> > +<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
> 
> "causes"
> 
> > +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>
> 
> + This is unrelated to the <code>buildtype</code>; setting the latter to
> + <code>release</code> will not turn off assertions, for instance.
> 
> > +</dd>
> > +</dl>
> > -- 
> > 2.15.0
> > 

All comments applied.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: signature
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20171108/0b49e8e2/attachment.sig>