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

Wed Oct 18 19:47:05 UTC 2017

On Wednesday, 2017-10-18 17:29:20 +0000, Dylan Baker wrote:
> Quoting Eric Engestrom (2017-10-18 04:02:07)
> > On Tuesday, 2017-10-17 19:21:10 +0000, Dylan Baker 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.
> > 
> > Good point, but we could also merge it with a note at the top of the
> > page:
> > > Mesa has not yet been fully converted to use Meson. You should not use
> > > Meson for production builds yet.
> 
> Sure, that would work too.

Just realized I forgot to say, this is:
Reviewed-by: Eric Engestrom <eric at engestrom.ch>

> 
> > 
> > > 
> > >  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.
> > 
> > Suggestion: use `build/` with a trailing slash to make it explicit that
> > this is a directory, unlike make targets for instance.
> > 
> > > +</p>
> > > +
> > > +<pre>
> > > +    meson build
> > > +</pre>
> > > +
> > > +<p>
> > > +To see a description of your options you can run "meson configure". This will
> > 
> > s/This will/Without arguments, it will/
> > 
> > > +show your meson project configuration options as well as your local
> > > +configuration options.
> > 
> > + You can set any of these options by passing `-Doptionname=value`.
> > + Only the option passed in is affected, there is no need to specify
> > + already set options again.
> > 
> > Side note, I'm working on a TUI for meson, similar to cmake's `ccmake` :)
> > 
> > > +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
> > 
> > typo: "you've"
> > 
> > > +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
> > 
> > "detects your number of cores and set its number of 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
> > 
> > "configuration, you should run"
> > 
> > > +out of tree build directory, meson supports an unlimited number of them, for 
> > 
> > nit: use brackets here, instead of commas
> > 
> > > +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
> > 
> > s/mesa/Mesa/
> > 
> > > +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
> > >