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

Wed Oct 18 18:08:59 UTC 2017

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.

Signed-off-by: Dylan Baker <dylanx.c.baker at intel.com>
---
 docs/contents.html |   1 +
 docs/meson.html    | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 127 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..9f933382965
--- /dev/null
+++ b/docs/meson.html
@@ -0,0 +1,126 @@
+<!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 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
+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" with no
+arguments. This will show your meson global arguments and project arguments,
+along with their defaults and your local settings.
+</p>
+
+<pre>
+    meson configure build/
+</pre>
+
+<p>
+With 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".
+</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
+the project. 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, 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 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 any of these variables.
+</p>
+
+<pre>
+    CC=clang CXX=clang++ meson build-clang
+    ninja -C build-clang
+
+    touch meson.build
+    ninja -C build-clang clean
+    CFLAGS=-Wno-typedef-redefinition ninja -C build-clang
+</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 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 (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>
-- 
2.14.2

