<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>Compilation and Installation using Meson</title>
+ <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>
+ The Mesa 3D Graphics Library
</div>
<iframe src="contents.html"></iframe>
<div class="content">
-<h1>Compilation and Installation using Meson</h1>
+<h1>Compilation and Installation Using Meson</h1>
-<h2 id="basic">1. Basic Usage</h2>
+<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>
-<p><strong>The Meson build system is generally considered stable and ready
-for production</strong></p>
+<h2 id="intro">1. Introduction</h2>
-<p>The meson build is tested on on Linux, macOS, Cygwin and Haiku, it should
-work on FreeBSD, DragonflyBSD, NetBSD, and OpenBSD.</p>
+<p>For general information about Meson see the
+<a href="https://mesonbuild.com/">Meson website</a>.</p>
-<p><strong>Mesa requires Meson >= 0.44.1 to build.</strong>
+<p><strong>Mesa's Meson build system is generally considered stable and ready
+for production.</strong></p>
+
+<p><strong>Mesa requires Meson >= 0.46.0 to build.</strong>
+
+<p>The Meson build of Mesa is tested on Linux, macOS, Windows, Cygwin, Haiku, FreeBSD,
+DragonflyBSD, NetBSD, and should work on OpenBSD.</p>
+
+<h4>Unix-like OSes</h4>
+
+<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>
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>
+
+<h4>Windows</h4>
+
+<p>
+You will need to install python3 and meson as a module using pip. This is
+because we use python for generating code, and rely on external modules
+(mako). You also need pkg-config (a hard dependency of meson), flex, and bison.
+
+The easiest way to install everything you need is with <a
+href="https://chocolatey.org/">chocolatey</a>.
+</p>
+<pre>
+ choco install python3 winflexbison pkgconfiglite
+</pre>
+<p>You can even use chocolatey to install mingw and ninja (ninja can be used with MSVC as well)</p>
+<pre>
+ choco install ninja mingw
+</pre>
+<p>Then install meson using pip</p>
+<pre>
+ py -3 -m pip install meson mako
+</pre>
+
+You may need to add the python3 scripts directory to your path for meson.
+
+<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.
+It's recommended to create a
+<a href="https://mesonbuild.com/Using-multiple-build-directories.html">
+separate build directory</a> for each configuration you might want to use.
</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.
-
-Meson does not currently support listing options before configure a build
-directory, but this feature is being discussed upstream.
+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/
+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>.
+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
+<a href="https://gitlab.freedesktop.org/mesa/mesa/blob/master/meson_options.txt">
+meson_options.txt</a> file at the root of the project.
+</p>
+
+<p>
+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 "option"="value"</code>.
+For example:
</p>
<pre>
- meson configure build/ -Dprefix=/tmp/install -Dglx=true
+meson configure build/ -Dprefix=/tmp/install -Dglx=true
</pre>
+<p>
+Note that options taking lists (such as <code>platforms</code>) are
+<a href="https://mesonbuild.com/Build-options.html#using-build-options">a bit
+more complicated</a>, but the simplest form compatible with Mesa options
+is to use a comma to separate values (<code>-D platforms=drm,wayland</code>)
+and brackets to represent an empty list (<code>-D platforms=[]</code>).
+</p>
+
<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>
+Note: autotools automatically updated translation files (used by the DRI
+configuration tool) as part of the build process,
+Meson does not do this. Instead, you will need do this:
+</p>
+<pre>
+ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
</pre>
+<h4>Windows specific instructions</h4>
+
+<p>
+On windows you have a couple of choices for compilers. If you installed mingw
+with chocolatey and want to use ninja you should be able to open any shell
+and follow the instructions above. If you want to you MSVC, clang-cl, or ICL
+(the Intel Compiler), read on.
+</p>
+<p>
+Both ICL and MSVC come with shell environments, the easiest way to use meson
+with these it to open a shell. For clang-cl you will need to open an MSVC
+shell, and then override the compilers, either using a <a
+href="https://mesonbuild.com/Native-environments.html">native file</a>, or
+with the CC and CXX environment variables.
+</p>
<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
-changing the configuration, or create a new out of tree build directory for
-each configuration you want to build
-<a href="http://mesonbuild.com/Using-multiple-build-directories.html">as
-recommended in the documentation</a>
+All of these compilers are tested and work with ninja, but if you want visual
+studio integration or you just like msbuild, passing
+<code>--backend=vs</code> to meson will generate a visual studio solution. If
+you want to use ICL or clang-cl with the vsbackend you will need meson 0.52.0
+or greater. Older versions always use the microsoft compiler.
</p>
+<h2 id="advanced">3. Advanced Usage</h2>
+
<dl>
-<dt><code>Environment Variables</code></dt>
-<dd><p>Meson supports the standard CC and CXX environment variables for
-changing the default compiler, and CFLAGS, CXXFLAGS, and LDFLAGS for setting
-options to the compiler and linker.
+<dt>Installation Location</dt>
+<dd>
+<p>
+Meson default to installing libGL.so in your system's main lib/ directory
+and DRI drivers to a dri/ subdirectory.
+</p>
+<p>
+Developers will often want to install Mesa to a testing directory rather
+than the system library directory.
+This can be done with the --prefix option. For example:
+</p>
+<pre>
+meson --prefix="${PWD}/build/install" build/
+</pre>
+<p>
+will put the final libraries and drivers into the build/install/
+directory.
+Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to that location
+to run/test the driver.
+</p>
+<p>
+Meson also honors <code>DESTDIR</code> for installs.
+</p>
+</dd>
+
+<dt>Compiler Options</dt>
+<dd>
+<p>Meson supports the common CFLAGS, CXXFLAGS, etc. environment
+variables but their use is discouraged because of the many caveats
+in using them.
+</p>
+<p>Instead, it is recomended to use <code>-D${lang}_args</code> and
+<code>-D${lang}_link_args</code>. Among the benefits of these options
+is that they are guaranteed to persist across rebuilds and reconfigurations.
+</p>
+<p>
+This example sets -fmax-errors for compiling C sources and -DMAGIC=123
+for C++ sources:
+</p>
+<pre>
+meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123
+</pre>
+</dd>
+
+
+<dt>Compiler Specification</dt>
+<dd>
+<p>
+Meson supports the standard CC and CXX environment variables for
+changing the default compiler. Note that Meson does not allow
+changing the compilers in a configured builddir so you will need
+to create a new build dir for a different compiler.
+</p>
+<p>
+This is an example of specifying the clang compilers and cleaning
+the build directory before reconfiguring with an extra C option:
+</p>
+<pre>
+CC=clang CXX=clang++ meson build-clang
+ninja -C build-clang
+ninja -C build-clang clean
+meson configure build -Dc_args="-Wno-typedef-redefinition"
+ninja -C build-clang
+</pre>
+<p>
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>.
+<a href="https://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>.
+</p>
+</dd>
+
+<dt>LLVM</dt>
+<dd><p>Meson includes upstream logic to wrap llvm-config using its standard
+dependency interface.
+</p></dd>
-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-initialize 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 recommended when changing CFLAGS or CXXFLAGS. Meson will never
-change compiler in a configured build directory.
+<dd><p>
+As of meson 0.49.0 meson also has the concept of a
+<a href="https://mesonbuild.com/Native-environments.html">"native file"</a>,
+these files provide information about the native build environment (as opposed
+to a cross build environment). They are ini formatted and can override where to
+find llvm-config:
</p>
+custom-llvm.ini
<pre>
- CC=clang CXX=clang++ meson build-clang
- ninja -C build-clang
- ninja -C build-clang clean
- touch meson.build
- CFLAGS=-Wno-typedef-redefinition ninja -C build-clang
+ [binaries]
+ llvm-config = '/usr/local/bin/llvm/llvm-config'
</pre>
-<p>Meson also honors <code>DESTDIR</code> for installs</p>
+Then configure meson:
+
+<pre>
+ meson builddir/ --native-file custom-llvm.ini
+</pre>
</dd>
+<dd><p>
+Meson < 0.49 doesn't support native files, so to specify a custom
+<code>llvm-config</code> you need to modify your <code>$PATH</code> (or
+<code>%PATH%</code> on windows), which will be searched for
+<code>llvm-config</code>, <code>llvm-config<i>$version</i></code>,
+and <code>llvm-config-<i>$version</i></code>:
+</p>
+<pre>
+PATH=/path/to/folder/with/llvm-config:$PATH meson build
+</pre>
+</dd>
-<dt><code>LLVM</code></dt>
-<dd><p>Meson includes upstream logic to wrap llvm-config using it's standard
-dependency interface. It will search <code>$PATH</code> (or <code>%PATH%</code> on windows) for
-llvm-config, so using an LLVM from a non-standard path is as easy as
-<code>PATH=/path/with/llvm-config:$PATH meson build</code>.
-</p></dd>
-</dl>
+<dd><p>
+For selecting llvm-config for cross compiling a
+<a href="https://mesonbuild.com/Cross-compilation.html#defining-the-environment">"cross file"</a>
+should be used. It uses the same format as the native file above:
+</p>
+
+<p>cross-llvm.ini</p>
+<pre>
+ [binaries]
+ ...
+ llvm-config = '/usr/lib/llvm-config-32'
+</pre>
+
+<p>Then configure meson:</p>
+<pre>
+ meson builddir/ --cross-file cross-llvm.ini
+</pre>
+
+See the <a href="#cross-compilation">Cross Compilation</a> section for more information.
+</dd>
-<dl>
<dt><code>PKG_CONFIG_PATH</code></dt>
<dd><p>The
<code>pkg-config</code> utility is a hard requirement for configuring and
buildtype, which causes meson to inject no additional compiler arguments, only
those in the C/CXXFLAGS and those that mesa itself defines.</p>
</dd>
-</dl>
-<dl>
<dt><code>-Db_ndebug</code></dt>
<dd><p>This option controls assertions in meson projects. When set to <code>false</code>
(the default) assertions are enabled, when set to true they are disabled. This
</dd>
</dl>
+<h2 id="cross-compilation">4. Cross-compilation and 32-bit builds</h2>
+
+<p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports
+cross-compilation</a> by specifying a number of binary paths and
+settings in a file and passing this file to <code>meson</code> or
+<code>meson configure</code> with the <code>--cross-file</code>
+parameter.</p>
+
+<p>This file can live at any location, but you can use the bare filename
+(without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
+~/.local/share/meson/cross</p>
+
+<p>Below are a few example of cross files, but keep in mind that you
+will likely have to alter them for your system.</p>
+
+<p>
+Those running on ArchLinux can use the AUR-maintained packages for some
+of those, as they'll have the right values for your system:
+</p>
+<ul>
+ <li><a href="https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu">meson-cross-x86-linux-gnu</a></li>
+ <li><a href="https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu">meson-cross-aarch64-linux-gnu</a></li>
+</ul>
+
+<p>
+32-bit build on x86 linux:
+</p>
+<pre>
+[binaries]
+c = '/usr/bin/gcc'
+cpp = '/usr/bin/g++'
+ar = '/usr/bin/gcc-ar'
+strip = '/usr/bin/strip'
+pkgconfig = '/usr/bin/pkg-config-32'
+llvm-config = '/usr/bin/llvm-config32'
+
+[properties]
+c_args = ['-m32']
+c_link_args = ['-m32']
+cpp_args = ['-m32']
+cpp_link_args = ['-m32']
+
+[host_machine]
+system = 'linux'
+cpu_family = 'x86'
+cpu = 'i686'
+endian = 'little'
+</pre>
+
+<p>
+64-bit build on ARM linux:
+</p>
+<pre>
+[binaries]
+c = '/usr/bin/aarch64-linux-gnu-gcc'
+cpp = '/usr/bin/aarch64-linux-gnu-g++'
+ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
+strip = '/usr/bin/aarch64-linux-gnu-strip'
+pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
+exe_wrapper = '/usr/bin/qemu-aarch64-static'
+
+[host_machine]
+system = 'linux'
+cpu_family = 'aarch64'
+cpu = 'aarch64'
+endian = 'little'
+</pre>
+
+<p>
+64-bit build on x86 windows:
+</p>
+<pre>
+[binaries]
+c = '/usr/bin/x86_64-w64-mingw32-gcc'
+cpp = '/usr/bin/x86_64-w64-mingw32-g++'
+ar = '/usr/bin/x86_64-w64-mingw32-ar'
+strip = '/usr/bin/x86_64-w64-mingw32-strip'
+pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
+exe_wrapper = 'wine'
+
+[host_machine]
+system = 'windows'
+cpu_family = 'x86_64'
+cpu = 'i686'
+endian = 'little'
+</pre>
+
</div>
</body>
</html>
projects / mesa.git / blobdiff