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

Tue Oct 17 19:21:10 UTC 2017

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. The meson Visual
+Studio® backend is only available on Microsoft® Windows®, 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". 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).
+</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.
+
+<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.
+</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.
+<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

