blob: c3e4a558391296446388ea097e98a0884fd4fe30 [file] [log] [blame]
Dylan Bakerbc17ac52017-10-17 12:19:49 -07001<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html lang="en">
3<head>
4 <meta http-equiv="content-type" content="text/html; charset=utf-8">
Erik Faye-Lund6e0e5502019-05-06 13:13:11 +02005 <title>Compilation and Installation Using Meson</title>
Dylan Bakerbc17ac52017-10-17 12:19:49 -07006 <link rel="stylesheet" type="text/css" href="mesa.css">
7</head>
8<body>
9
10<div class="header">
Erik Faye-Lundecdab0d2019-05-06 13:26:47 +020011 The Mesa 3D Graphics Library
Dylan Bakerbc17ac52017-10-17 12:19:49 -070012</div>
13
14<iframe src="contents.html"></iframe>
15<div class="content">
16
Erik Faye-Lund6e0e5502019-05-06 13:13:11 +020017<h1>Compilation and Installation Using Meson</h1>
Dylan Bakerbc17ac52017-10-17 12:19:49 -070018
Eric Engestromb0319d02018-11-29 13:16:42 +000019<ul>
Brian Paul45c6da52019-03-07 20:39:49 -070020 <li><a href="#intro">Introduction</a></li>
Eric Engestromb0319d02018-11-29 13:16:42 +000021 <li><a href="#basic">Basic Usage</a></li>
Brian Paul45c6da52019-03-07 20:39:49 -070022 <li><a href="#advanced">Advanced Usage</a></li>
Eric Engestromb0319d02018-11-29 13:16:42 +000023 <li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li>
24</ul>
25
Brian Paul45c6da52019-03-07 20:39:49 -070026<h2 id="intro">1. Introduction</h2>
Dylan Bakerbc17ac52017-10-17 12:19:49 -070027
Brian Paul45c6da52019-03-07 20:39:49 -070028<p>For general information about Meson see the
29<a href="http://mesonbuild.com/">Meson website</a>.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -070030
Brian Paul45c6da52019-03-07 20:39:49 -070031<p><strong>Mesa's Meson build system is generally considered stable and ready
32for production.</strong></p>
33
34<p>The Meson build of Mesa is tested on Linux, macOS, Cygwin and Haiku, FreeBSD,
Dylan Baker1da60662018-09-18 09:01:45 -070035DragonflyBSD, NetBSD, and should work on OpenBSD.</p>
Dylan Baker2aad12b2018-03-01 11:32:56 -080036
Brian Paul45c6da52019-03-07 20:39:49 -070037<p>If Meson is not already installed on your system, you can typically
38install it with your package installer. For example:</p>
39<pre>
40sudo apt-get install meson # Ubuntu
41</pre>
42or
43<pre>
44sudo dnf install meson # Fedora
45</pre>
46
Eric Engestrom4bf7e7b2019-07-30 00:44:21 +010047<p><strong>Mesa requires Meson &gt;= 0.46.0 to build.</strong>
Dylan Baker2aad12b2018-03-01 11:32:56 -080048
49Some older versions of meson do not check that they are too old and will error
50out in odd ways.
51</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -070052
Brian Paul45c6da52019-03-07 20:39:49 -070053<p>You'll also need <a href="https://ninja-build.org/">Ninja</a>.
54If it's not already installed, use apt-get or dnf to install
55the <em>ninja-build</em> package.
56</p>
57
58<h2 id="basic">2. Basic Usage</h2>
59
Dylan Bakerbc17ac52017-10-17 12:19:49 -070060<p>
61The meson program is used to configure the source directory and generates
62either a ninja build file or Visual Studio® build files. The latter must
Brian Paul45c6da52019-03-07 20:39:49 -070063be enabled via the <code>--backend</code> switch, as ninja is the default
64backend on all
65operating systems.
Dylan Bakerbc17ac52017-10-17 12:19:49 -070066</p>
67
Brian Paul45c6da52019-03-07 20:39:49 -070068<p>
69Meson only supports out-of-tree builds, and must be passed a
70directory to put built and generated sources into. We'll call that directory
71"build" here.
72It's recommended to create a
73<a href="http://mesonbuild.com/Using-multiple-build-directories.html">
74separate build directory</a> for each configuration you might want to use.
75</p>
76
77
78
Brian Paul45c6da52019-03-07 20:39:49 -070079<p>Basic configuration is done with:</p>
80
Dylan Bakerbc17ac52017-10-17 12:19:49 -070081<pre>
Brian Paul45c6da52019-03-07 20:39:49 -070082meson build/
Dylan Bakerbc17ac52017-10-17 12:19:49 -070083</pre>
84
85<p>
Brian Paul45c6da52019-03-07 20:39:49 -070086This will create the build directory.
87If any dependencies are missing, you can install them, or try to remove
88the dependency with a Meson configuration option (see below).
Eric Engestromc4c5c902019-01-17 16:26:26 +000089</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -070090
Eric Engestromc4c5c902019-01-17 16:26:26 +000091<p>
Brian Paul45c6da52019-03-07 20:39:49 -070092To review the options which Meson chose, run:
93</p>
94<pre>
95meson configure build/
96</pre>
97
98<p>
99Meson does not currently support listing configuration options before
100running "meson build/" but this feature is being discussed upstream.
Eric Engestrom00be88a2019-01-17 18:04:42 +0000101For now, we have a <code>bin/meson-options.py</code> script that prints
102the options for you.
103If that script doesn't work for some reason, you can always look in the
Brian Paule547a1c2019-03-11 19:58:04 -0600104<a href="https://gitlab.freedesktop.org/mesa/mesa/blob/master/meson_options.txt">
105meson_options.txt</a> file at the root of the project.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700106</p>
107
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700108<p>
Brian Paul45c6da52019-03-07 20:39:49 -0700109With additional arguments <code>meson configure</code> can be used to change
110options for a previously configured build directory.
111All options passed to this command are in the form
112<code>-D "option"="value"</code>.
113For example:
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700114</p>
115
116<pre>
Brian Paul45c6da52019-03-07 20:39:49 -0700117meson configure build/ -Dprefix=/tmp/install -Dglx=true
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700118</pre>
119
120<p>
Eric Engestrom57fbc2a2018-05-14 16:39:42 +0100121Note that options taking lists (such as <code>platforms</code>) are
122<a href="http://mesonbuild.com/Build-options.html#using-build-options">a bit
123more complicated</a>, but the simplest form compatible with Mesa options
124is to use a comma to separate values (<code>-D platforms=drm,wayland</code>)
125and brackets to represent an empty list (<code>-D platforms=[]</code>).
126</p>
127
128<p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700129Once you've run the initial <code>meson</code> command successfully you can use
Brian Paul45c6da52019-03-07 20:39:49 -0700130your configured backend to build the project in your build directory:
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700131</p>
132
133<pre>
Brian Paul45c6da52019-03-07 20:39:49 -0700134ninja -C build/
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700135</pre>
136
137<p>
Brian Paul45c6da52019-03-07 20:39:49 -0700138The next step is to install the Mesa libraries, drivers, etc.
139This also finishes up some final steps of the build process (such as creating
140symbolic links for drivers). To install:
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700141</p>
142
Brian Paul45c6da52019-03-07 20:39:49 -0700143<pre>
144ninja -C build/ install
145</pre>
146
Dylan Bakera8004ef2018-10-22 19:33:08 -0700147<p>
Eric Engestrom88ed5f62019-04-24 13:19:51 +0100148Note: autotools automatically updated translation files (used by the DRI
Brian Paul45c6da52019-03-07 20:39:49 -0700149configuration tool) as part of the build process,
150Meson does not do this. Instead, you will need do this:
Dylan Bakera8004ef2018-10-22 19:33:08 -0700151</p>
Brian Paul45c6da52019-03-07 20:39:49 -0700152<pre>
153ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
154</pre>
155
156<h2 id="advanced">3. Advanced Usage</h2>
Dylan Bakera8004ef2018-10-22 19:33:08 -0700157
Eric Engestrom67c55072018-05-14 16:45:31 +0100158<dl>
Brian Paul45c6da52019-03-07 20:39:49 -0700159
160<dt>Installation Location</dt>
161<dd>
162<p>
163Meson default to installing libGL.so in your system's main lib/ directory
164and DRI drivers to a dri/ subdirectory.
165</p>
166<p>
167Developers will often want to install Mesa to a testing directory rather
168than the system library directory.
169This can be done with the --prefix option. For example:
170</p>
Brian Paul16fb82d2019-03-08 10:31:11 -0700171<pre>
Brian Paul45c6da52019-03-07 20:39:49 -0700172meson --prefix="${PWD}/build/install" build/
Brian Paul16fb82d2019-03-08 10:31:11 -0700173</pre>
Brian Paul45c6da52019-03-07 20:39:49 -0700174<p>
175will put the final libraries and drivers into the build/install/
176directory.
177Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to that location
178to run/test the driver.
179</p>
Brian Paul16fb82d2019-03-08 10:31:11 -0700180<p>
181Meson also honors <code>DESTDIR</code> for installs.
182</p>
Brian Paul45c6da52019-03-07 20:39:49 -0700183</dd>
184
Brian Paul16fb82d2019-03-08 10:31:11 -0700185<dt>Compiler Options</dt>
186<dd>
187<p>Meson supports the common CFLAGS, CXXFLAGS, etc. environment
188variables but their use is discouraged because of the many caveats
189in using them.
190</p>
191<p>Instead, it is recomended to use <code>-D${lang}_args</code> and
192<code>-D${lang}_link_args</code>. Among the benefits of these options
Dylan Baker0ff7eed2018-12-19 13:27:27 -0800193is that they are guaranteed to persist across rebuilds and reconfigurations.
Brian Paul16fb82d2019-03-08 10:31:11 -0700194</p>
Erik Faye-Lund8ef86c92019-04-18 16:13:44 +0200195<p>
Brian Paul16fb82d2019-03-08 10:31:11 -0700196This example sets -fmax-errors for compiling C sources and -DMAGIC=123
197for C++ sources:
198</p>
Brian Paul16fb82d2019-03-08 10:31:11 -0700199<pre>
200meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123
201</pre>
Brian Paul16fb82d2019-03-08 10:31:11 -0700202</dd>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700203
Brian Paul16fb82d2019-03-08 10:31:11 -0700204
205<dt>Compiler Specification</dt>
206<dd>
207<p>
208Meson supports the standard CC and CXX environment variables for
209changing the default compiler. Note that Meson does not allow
210changing the compilers in a configured builddir so you will need
Dylan Baker0ff7eed2018-12-19 13:27:27 -0800211to create a new build dir for a different compiler.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700212</p>
Brian Paul16fb82d2019-03-08 10:31:11 -0700213<p>
214This is an example of specifying the clang compilers and cleaning
215the build directory before reconfiguring with an extra C option:
216</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700217<pre>
Brian Paul16fb82d2019-03-08 10:31:11 -0700218CC=clang CXX=clang++ meson build-clang
219ninja -C build-clang
220ninja -C build-clang clean
221meson configure build -Dc_args="-Wno-typedef-redefinition"
222ninja -C build-clang
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700223</pre>
Dylan Bakere0829f92018-09-18 09:07:25 -0700224<p>
225The default compilers depends on your operating system. Meson supports most of
226the popular compilers, a complete list is available
227<a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>.
228</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700229</dd>
230
Brian Paul45c6da52019-03-07 20:39:49 -0700231<dt>LLVM</dt>
Dylan Bakerbe56f8a2018-09-18 09:09:47 -0700232<dd><p>Meson includes upstream logic to wrap llvm-config using its standard
Dylan Bakera57dbe62018-12-20 11:46:08 -0800233dependency interface.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700234</p></dd>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800235
236<dd><p>
237As of meson 0.49.0 meson also has the concept of a
238<a href="https://mesonbuild.com/Native-environments.html">"native file"</a>,
239these files provide information about the native build environment (as opposed
240to a cross build environment). They are ini formatted and can override where to
241find llvm-config:
Erik Faye-Lund0ea4ef22019-04-18 16:16:06 +0200242</p>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800243
244custom-llvm.ini
245<pre>
246 [binaries]
247 llvm-config = '/usr/local/bin/llvm/llvm-config'
248</pre>
249
250Then configure meson:
251
252<pre>
253 meson builddir/ --native-file custom-llvm.ini
254</pre>
Erik Faye-Lund0ea4ef22019-04-18 16:16:06 +0200255</dd>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800256
257<dd><p>
258For selecting llvm-config for cross compiling a
259<a href="https://mesonbuild.com/Cross-compilation.html#defining-the-environment">"cross file"</a>
260should be used. It uses the same format as the native file above:
Erik Faye-Lund767c5172019-04-18 16:27:26 +0200261</p>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800262
Erik Faye-Lund767c5172019-04-18 16:27:26 +0200263<p>cross-llvm.ini</p>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800264<pre>
265 [binaries]
266 ...
267 llvm-config = '/usr/lib/llvm-config-32'
268</pre>
269
Erik Faye-Lund767c5172019-04-18 16:27:26 +0200270<p>Then configure meson:</p>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800271<pre>
272 meson builddir/ --cross-file cross-llvm.ini
273</pre>
274
275See the <a href="#cross-compilation">Cross Compilation</a> section for more information.
Erik Faye-Lund767c5172019-04-18 16:27:26 +0200276</dd>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800277
278<dd><p>
279For older versions of meson <code>$PATH</code> (or <code>%PATH%</code> on
280windows) will be searched for llvm-config (and llvm-config$version and
281llvm-config-$version), you can override this environment variable to control
282the search: <code>PATH=/path/with/llvm-config:$PATH meson build</code>.
Erik Faye-Lund767c5172019-04-18 16:27:26 +0200283</p></dd>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700284
285<dt><code>PKG_CONFIG_PATH</code></dt>
286<dd><p>The
287<code>pkg-config</code> utility is a hard requirement for configuring and
Dylan Baker2aad12b2018-03-01 11:32:56 -0800288building Mesa on Unix-like systems. It is used to search for external libraries
289on the system. This environment variable is used to control the search path for
290<code>pkg-config</code>. For instance, setting
291<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package
292metadata in <code>/usr/X11R6</code> before the standard directories.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700293</dd>
294</dl>
295
296<p>
297One of the oddities of meson is that some options are different when passed to
298the <code>meson</code> than to <code>meson configure</code>. These options are
299passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson
300configure</code>. Mesa defined options are always passed as -Doption=foo.
Eric Engestrom67c55072018-05-14 16:45:31 +0100301</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700302
303<p>For those coming from autotools be aware of the following:</p>
304
305<dl>
306<dt><code>--buildtype/-Dbuildtype</code></dt>
307<dd><p>This option will set the compiler debug/optimisation levels to aid
308debugging the Mesa libraries.</p>
309
Eric Engestrom37d44e22018-05-14 16:47:57 +0100310<p>Note that in meson this defaults to <code>debugoptimized</code>, and
311not setting it to <code>release</code> will yield non-optimal
312performance and binary size. Not using <code>debug</code> may interfere
313with debugging as some code and validation will be optimized away.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700314</p>
315
Eric Engestrom37d44e22018-05-14 16:47:57 +0100316<p> For those wishing to pass their own optimization flags, use the <code>plain</code>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800317buildtype, which causes meson to inject no additional compiler arguments, only
318those in the C/CXXFLAGS and those that mesa itself defines.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700319</dd>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700320
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700321<dt><code>-Db_ndebug</code></dt>
Eric Engestrom37d44e22018-05-14 16:47:57 +0100322<dd><p>This option controls assertions in meson projects. When set to <code>false</code>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700323(the default) assertions are enabled, when set to true they are disabled. This
324is unrelated to the <code>buildtype</code>; setting the latter to
325<code>release</code> will not turn off assertions.
326</p>
327</dd>
328</dl>
Eric Engestrom67c55072018-05-14 16:45:31 +0100329
Brian Paul45c6da52019-03-07 20:39:49 -0700330<h2 id="cross-compilation">4. Cross-compilation and 32-bit builds</h2>
Eric Engestromb0319d02018-11-29 13:16:42 +0000331
332<p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports
333cross-compilation</a> by specifying a number of binary paths and
334settings in a file and passing this file to <code>meson</code> or
335<code>meson configure</code> with the <code>--cross-file</code>
336parameter.</p>
337
338<p>This file can live at any location, but you can use the bare filename
339(without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
340~/.local/share/meson/cross</p>
341
342<p>Below are a few example of cross files, but keep in mind that you
343will likely have to alter them for your system.</p>
344
345<p>
Eric Engestrom393a7562019-01-03 16:01:18 +0000346Those running on ArchLinux can use the AUR-maintained packages for some
347of those, as they'll have the right values for your system:
Erik Faye-Lund92917e82019-04-18 15:38:01 +0200348</p>
Eric Engestrom393a7562019-01-03 16:01:18 +0000349<ul>
350 <li><a href="https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu">meson-cross-x86-linux-gnu</a></li>
351 <li><a href="https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu">meson-cross-aarch64-linux-gnu</a></li>
352</ul>
Eric Engestrom393a7562019-01-03 16:01:18 +0000353
354<p>
Eric Engestromb0319d02018-11-29 13:16:42 +000035532-bit build on x86 linux:
Erik Faye-Lund41573d42019-04-18 16:12:08 +0200356</p>
Eric Engestromb0319d02018-11-29 13:16:42 +0000357<pre>
358[binaries]
359c = '/usr/bin/gcc'
360cpp = '/usr/bin/g++'
361ar = '/usr/bin/gcc-ar'
362strip = '/usr/bin/strip'
363pkgconfig = '/usr/bin/pkg-config-32'
364llvm-config = '/usr/bin/llvm-config32'
365
366[properties]
367c_args = ['-m32']
368c_link_args = ['-m32']
369cpp_args = ['-m32']
370cpp_link_args = ['-m32']
371
372[host_machine]
373system = 'linux'
374cpu_family = 'x86'
375cpu = 'i686'
376endian = 'little'
377</pre>
Eric Engestromb0319d02018-11-29 13:16:42 +0000378
379<p>
38064-bit build on ARM linux:
Erik Faye-Lund41573d42019-04-18 16:12:08 +0200381</p>
Eric Engestromb0319d02018-11-29 13:16:42 +0000382<pre>
383[binaries]
384c = '/usr/bin/aarch64-linux-gnu-gcc'
385cpp = '/usr/bin/aarch64-linux-gnu-g++'
Eric Engestrom8b363bc2019-01-03 15:44:42 +0000386ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
Eric Engestromb0319d02018-11-29 13:16:42 +0000387strip = '/usr/bin/aarch64-linux-gnu-strip'
388pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
389exe_wrapper = '/usr/bin/qemu-aarch64-static'
390
391[host_machine]
392system = 'linux'
Eric Engestrom8b363bc2019-01-03 15:44:42 +0000393cpu_family = 'aarch64'
Eric Engestromb0319d02018-11-29 13:16:42 +0000394cpu = 'aarch64'
395endian = 'little'
396</pre>
Eric Engestromb0319d02018-11-29 13:16:42 +0000397
398<p>
39964-bit build on x86 windows:
Erik Faye-Lund41573d42019-04-18 16:12:08 +0200400</p>
Eric Engestromb0319d02018-11-29 13:16:42 +0000401<pre>
402[binaries]
403c = '/usr/bin/x86_64-w64-mingw32-gcc'
404cpp = '/usr/bin/x86_64-w64-mingw32-g++'
405ar = '/usr/bin/x86_64-w64-mingw32-ar'
406strip = '/usr/bin/x86_64-w64-mingw32-strip'
407pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
408exe_wrapper = 'wine'
409
410[host_machine]
411system = 'windows'
412cpu_family = 'x86_64'
413cpu = 'i686'
414endian = 'little'
415</pre>
Eric Engestromb0319d02018-11-29 13:16:42 +0000416
Eric Engestrom67c55072018-05-14 16:45:31 +0100417</div>
418</body>
419</html>