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

[Brian Paul]

On Thu, Mar 7, 2019 at 11:51 PM Eric Engestrom <eric at engestrom.ch> wrote:

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

Done.



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

I don't know either.

-Brian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20190308/dd143d76/attachment-0001.html>