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

Wed Oct 18 10:32:14 UTC 2017

On 17 October 2017 at 20:21, Dylan Baker <dylan at pnwbakers.com> wrote:
> Signed-off-by: Dylan Baker <dylanx.c.baker at intel.com>
> ---
>
> I'm sending this out now so that others can look at it, review it, and reference
> it, but this should not end up in the 17.3 release, as the meson build for mesa
> will not be ready to go into the 17.3 release.
>
>  docs/contents.html |  1 +
>  docs/meson.html    | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 100 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..f45a62c9da4
> --- /dev/null
> +++ b/docs/meson.html
> @@ -0,0 +1,99 @@
> +<!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>
> +The meson program is used to configure the source directory and generates
> +either a ninja build file, or visual studio build files.

s/The meson Visual Studio® backend is only available on Microsoft®
Windows®, and/The latter

> 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". This will
> +show your meson project configuration options as well as your local
> +configuration options. One meson option to be aware of is that meson's default
> +build type is "debug" (-O0 -g on gcc/clang).

Is `meson configure' only for viewing or can it be used to amend existing setup?
Hunk says the former, follow-up reply to Nicolai implies the latter.

> +</p>
> +
> +<pre>
> +    meson configure build
> +</pre>
> +
> +Once you're run meson successfully you can use your configured backend to build
> +the project, for Linux/*BSD and macOS that will be ninja. If you're unfamiliar
> +with ninja, it automatically detects your CPU's and sets it's jobs
> +appropriately. The -C option allows us to point ninja at the build directory
> +without changing into it.
Pretty sure one can lookup ninja if they need to ;-)  I'd slim down
the lot to something like:

Once you've run meson successfully you can use your configured backend to build
the project. In case of ninja, the -C option should point at the build
directory.

> +
> +<pre>
> +    ninja -C build
> +</pre>
> +
> +<p>
> +This 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 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 GCC, Clang, and MSVC as first
> +class compilers. There is some support for the Intel ICC compiler. No other
> +C/C++ compilers are currently supported.
The list will be outdated state too often, so I'd swap it with a link
to Meson's docs.

Meson supports various compilers see $link_to_meson_documentation

> +</dd>
> +
> +<dt><code>PKG_CONFIG_PATH</code></dt>
> +<dd><p>The
> +<code>pkg-config</code> utility is a hard requirement for configuring and
> +building mesa. 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 initial meson step than to meson configure. These options are passed as
> +--option=foo to meson, but -Doption=foo to meson configure. Project defined
> +options are always passed as -Doption=foo.
It took me a few reads to parse this one. Some formatting suggestions.

Oddities of meson:
 - Some options are different when passed to <code>meson</code> vs
<code>meson configure</code>.
Namely: the former tends to use ..... while the latter ...
// XXX: Worth adding a table and/or link to the Meson docs?
<strong>Note:</strong> Project defined options ....

> +<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 (if the user
> +hasn't already set them via the CFLAGS/CXXFLAGS) and macros to aid in
> +debugging the Mesa libraries.</p>
> +
> +<p>Note that in meson this defaults to "debug", and  not setting it to
> +"release" will yield non-optimal performance and binary size</p>
Ouch, can we change that?

Thanks
Emil