[Mesa-dev] [PATCH] docs: try to improve the Meson documentation

Fri Mar 8 06:42:33 UTC 2019

On 2019-03-08 at 03:42, Brian Paul <brianp at vmware.com> wrote:
> Add new Introduction and Advanced Usage sections.
> Spell out a few more details, like "ninja install".
> Improve the layout around example commands.
> Fix grammatical errors and tighten up the text.
> Explain the --prefix option.

Thanks! I left a couple comments below, but this is:
Reviewed-by: Eric Engestrom <eric at engestrom.ch>

> ---
>  docs/contents.html |   2 +-
>  docs/meson.html    | 138 +++++++++++++++++++++++++++++++++++++++--------------
>  2 files changed, 104 insertions(+), 36 deletions(-)
> 
> diff --git a/docs/contents.html b/docs/contents.html
> index 6364776..619ac3d 100644
> --- a/docs/contents.html
> +++ b/docs/contents.html
> @@ -42,8 +42,8 @@
>  <li><a href="download.html" target="_parent">Downloading / Unpacking</a>
>  <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>
> +    <li><a href="autoconf.html" target="_parent">Autoconf (deprecated)</a></li>
>    </ul>
>  </li>
>  <li><a href="precompiled.html" target="_parent">Precompiled Libraries</a>
> diff --git a/docs/meson.html b/docs/meson.html
> index f21479c..f9ae669 100644
> --- a/docs/meson.html
> +++ b/docs/meson.html
> @@ -17,65 +17,98 @@
>  <h1>Compilation and Installation using Meson</h1>
>  
>  <ul>
> +  <li><a href="#intro">Introduction</a></li>
>    <li><a href="#basic">Basic Usage</a></li>
> +  <li><a href="#advanced">Advanced Usage</a></li>
>    <li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li>
>  </ul>
>  
> -<h2 id="basic">1. Basic Usage</h2>
> +<h2 id="intro">1. Introduction</h2>
>  
> -<p><strong>The Meson build system is generally considered stable and ready
> -for production</strong></p>
> +<p>For general information about Meson see the
> +<a href="http://mesonbuild.com/">Meson website</a>.</p>
>  
> -<p>The meson build is tested on Linux, macOS, Cygwin and Haiku, 
> FreeBSD,
> +<p><strong>Mesa's Meson build system is generally considered stable 
> and ready
> +for production.</strong></p>
> +
> +<p>The Meson build of Mesa is tested on Linux, macOS, Cygwin and 
> Haiku, FreeBSD,
>  DragonflyBSD, NetBSD, and should work on OpenBSD.</p>
>  
> +<p>If Meson is not already installed on your system, you can typically
> +install it with your package installer.  For example:</p>
> +<pre>
> +sudo apt-get install meson   # Ubuntu
> +</pre>
> +or
> +<pre>
> +sudo dnf install meson   # Fedora
> +</pre>
> +
>  <p><strong>Mesa requires Meson >= 0.45.0 to build.</strong>
>  
>  Some older versions of meson do not check that they are too old and will error
>  out in odd ways.
>  </p>
>  
> +<p>You'll also need <a href="https://ninja-build.org/">Ninja</a>.
> +If it's not already installed, use apt-get or dnf to install
> +the <em>ninja-build</em> package.
> +</p>
> +
> +<h2 id="basic">2. Basic Usage</h2>
> +
>  <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 
> must
> -be enabled via the <code>--backend</code> switch, as ninja is the 
> default backend on all
> -operating systems. Meson only supports out-of-tree builds, and must be 
> passed a
> +be enabled via the <code>--backend</code> switch, as ninja is the 
> default
> +backend on all
> +operating systems.
> +</p>
> +
> +<p>
> +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.
> +"build" here.
>  </p>
>  
> +<p>Basic configuration is done with:</p>
> +
>  <pre>
> -    meson build/
> +meson build/
>  </pre>
>  
>  <p>
> -To see a description of your options you can run <code>meson configure</code>
> -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.
> +This will create the build directory.
> +If any dependencies are missing, you can install them, or try to remove
> +the dependency with a Meson configuration option (see below).
> +</p>
> +
> +<p>
> +To review the options which Meson chose, run:
>  </p>
> +<pre>
> +meson configure build/
> +</pre>
>  
>  <p>
> -Meson does not currently support listing options before configure a build
> -directory, but this feature is being discussed upstream.
> +Meson does not currently support listing configuration options before
> +running "meson build/" but this feature is being discussed upstream.
>  For now, we have a <code>bin/meson-options.py</code> script that prints
>  the options for you.
>  If that script doesn't work for some reason, you can always look in the
>  <code>meson_options.txt</code> file at the root of the project.
>  </p>
>  
> -<pre>
> -    meson configure build/
> -</pre>
> -
>  <p>
> -With additional arguments <code>meson configure</code> is used to change
> -options on already configured build directory. All options passed to this
> -command are in the form <code>-D "command"="value"</code>.
> +With additional arguments <code>meson configure</code> can be used to change
> +options for a previously configured build directory.
> +All options passed to this command are in the form
> +<code>-D "command"="value"</code>.

I know you didn't write this bit, but can I suggest s/command/option/ ?

> +For example:
>  </p>
>  
>  <pre>
> -    meson configure build/ -Dprefix=/tmp/install -Dglx=true
> +meson configure build/ -Dprefix=/tmp/install -Dglx=true
>  </pre>
>  
>  <p>
> @@ -88,33 +121,68 @@ and brackets to represent an empty list (<code>-D 
> platforms=[]</code>).
>  
>  <p>
>  Once you've run the initial <code>meson</code> command 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.
> +your configured backend to build the project in your build directory:
> +</p>
> +
> +<pre>
> +ninja -C build/
> +</pre>
> +
> +<p>
> +The next step is to install the Mesa libraries, drivers, etc.
> +This also finishes up some final steps of the build process (such as creating
> +symbolic links for drivers).  To install:
>  </p>
>  
>  <pre>
> -    ninja -C build/
> +ninja -C build/ install
>  </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
> +Later, if you want to rebuild for a
>  different configuration, you should run <code>ninja clean</code> before

I'm not sure this is needed?

> -changing the configuration, or create a new out of tree build directory for
> +changing the configuration, or create a new build directory for
>  each configuration you want to build
>  <a href="http://mesonbuild.com/Using-multiple-build-directories.html">as
>  recommended in the documentation</a>
>  </p>
>  
>  <p>
> -Autotools automatically updates translation files as part of the build 
> process,
> -meson does not do this. Instead if you want translated drirc files you 
> will need 
> -to invoke non-default targets for ninja to update them:
> -<code>ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo</code>
> +Autotools automatically updates translation files (used by the DRI
> +configuration tool) as part of the build process,
> +Meson does not do this.  Instead, you will need do this:
>  </p>
> +<pre>
> +ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
> +</pre>
> +
> +<h2 id="advanced">3. Advanced Usage</h2>
>  
>  <dl>
> -<dt><code>Environment Variables</code></dt>
> +
> +<dt>Installation Location</dt>
> +<dd>
> +<p>
> +Meson default to installing libGL.so in your system's main lib/ directory
> +and DRI drivers to a dri/ subdirectory.
> +</p>
> +<p>
> +Developers will often want to install Mesa to a testing directory rather
> +than the system library directory.
> +This can be done with the --prefix option.  For example:
> +</p>
> +<code>
> +meson --prefix="${PWD}/build/install" build/
> +</code>
> +<p>
> +will put the final libraries and drivers into the build/install/
> +directory.
> +Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to that location
> +to run/test the driver.
> +</p>
> +</dd>
> +
> +<dt>Environment Variables</dt>
>  <dd><p>Meson supports the standard CC and CXX environment variables for
>  changing the default compiler. Meson does support CFLAGS, CXXFLAGS, etc. But
>  their use is discouraged because of the many caveats in using them. Instead it
> @@ -144,7 +212,7 @@ the popular compilers, a complete list is available
>  </dd>
>  
>  
> -<dt><code>LLVM</code></dt>
> +<dt>LLVM</dt>
>  <dd><p>Meson includes upstream logic to wrap llvm-config using its 
> standard
>  dependency interface.
>  </p></dd>
> @@ -246,7 +314,7 @@ is unrelated to the <code>buildtype</code>; setting 
> the latter to
>  </dd>
>  </dl>
>  
> -<h2 id="cross-compilation">2. Cross-compilation and 32-bit builds</h2>
> +<h2 id="cross-compilation">4. Cross-compilation and 32-bit builds</h2>
>  
>  <p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports
>  cross-compilation</a> by specifying a number of binary paths and
> -- 
> 1.8.5.6
> 
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev