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

Fri Mar 8 16:33:57 UTC 2019

Eric Engestrom <eric at engestrom.ch> writes:

> 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?

Not needed.  meson actually gets this right, unlike autotools.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 832 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20190308/6697e09f/attachment.sig>