Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / d43ec104b7487d3a8930c0d1cd2a2732967f6275 / . / docs / meson.html
blob: ac941b8407979aeb733005783566a1f9731f46f7 [file] [log] [blame]
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]1<!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">
5 <title>Compilation and Installation using Meson</title>
6 <link rel="stylesheet" type="text/css" href="mesa.css">
7</head>
8<body>
9
10<div class="header">
11 <h1>The Mesa 3D Graphics Library</h1>
12</div>
13
14<iframe src="contents.html"></iframe>
15<div class="content">
16
17<h1>Compilation and Installation using Meson</h1>
18
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]19<ul>
20 <li><a href="#basic">Basic Usage</a></li>
21 <li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li>
22</ul>
23
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]24<h2 id="basic">1. Basic Usage</h2>
25
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]26<p><strong>The Meson build system is generally considered stable and ready
27for production</strong></p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]28
Dylan Baker1da60662018-09-18 09:01:45 -0700[diff] [blame]29<p>The meson build is tested on Linux, macOS, Cygwin and Haiku, FreeBSD,
30DragonflyBSD, NetBSD, and should work on OpenBSD.</p>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]31
Dylan Baker1da60662018-09-18 09:01:45 -0700[diff] [blame]32<p><strong>Mesa requires Meson >= 0.45.0 to build.</strong>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]33
34Some older versions of meson do not check that they are too old and will error
35out in odd ways.
36</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]37
38<p>
39The meson program is used to configure the source directory and generates
40either a ninja build file or Visual Studio® build files. The latter must
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]41be enabled via the <code>--backend</code> switch, as ninja is the default backend on all
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]42operating systems. Meson only supports out-of-tree builds, and must be passed a
43directory to put built and generated sources into. We'll call that directory
44"build" for examples.
45</p>
46
47<pre>
48 meson build/
49</pre>
50
51<p>
52To see a description of your options you can run <code>meson configure</code>
53along with a build directory to view the selected options for. This will show
54your meson global arguments and project arguments, along with their defaults
55and your local settings.
Eric Engestromc4c5c902019-01-17 16:26:26 +0000[diff] [blame]56</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]57
Eric Engestromc4c5c902019-01-17 16:26:26 +0000[diff] [blame]58<p>
Eric Engestromdc2dc1f2018-05-14 16:44:08 +0100[diff] [blame]59Meson does not currently support listing options before configure a build
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]60directory, but this feature is being discussed upstream.
Eric Engestromc4c5c902019-01-17 16:26:26 +0000[diff] [blame]61For now, the only way to see what options exist is to look at the
62<code>meson_options.txt</code> file at the root of the project.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]63</p>
64
65<pre>
66 meson configure build/
67</pre>
68
69<p>
70With additional arguments <code>meson configure</code> is used to change
71options on already configured build directory. All options passed to this
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]72command are in the form <code>-D "command"="value"</code>.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]73</p>
74
75<pre>
76 meson configure build/ -Dprefix=/tmp/install -Dglx=true
77</pre>
78
79<p>
Eric Engestrom57fbc2a2018-05-14 16:39:42 +0100[diff] [blame]80Note that options taking lists (such as <code>platforms</code>) are
81<a href="http://mesonbuild.com/Build-options.html#using-build-options">a bit
82more complicated</a>, but the simplest form compatible with Mesa options
83is to use a comma to separate values (<code>-D platforms=drm,wayland</code>)
84and brackets to represent an empty list (<code>-D platforms=[]</code>).
85</p>
86
87<p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]88Once you've run the initial <code>meson</code> command successfully you can use
89your configured backend to build the project. With ninja, the -C option can be
90be used to point at a directory to build.
91</p>
92
93<pre>
94 ninja -C build/
95</pre>
96
97<p>
98Without arguments, it will produce libGL.so and/or several other libraries
99depending on the options you have chosen. Later, if you want to rebuild for a
100different configuration, you should run <code>ninja clean</code> before
101changing the configuration, or create a new out of tree build directory for
Eric Engestrom5829f612018-05-14 16:47:18 +0100[diff] [blame]102each configuration you want to build
103<a href="http://mesonbuild.com/Using-multiple-build-directories.html">as
104recommended in the documentation</a>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]105</p>
106
Dylan Bakera8004ef2018-10-22 19:33:08 -0700[diff] [blame]107<p>
108Autotools automatically updates translation files as part of the build process,
109meson does not do this. Instead if you want translated drirc files you will need
110to invoke non-default targets for ninja to update them:
111<code>ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo</code>
112</p>
113
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]114<dl>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]115<dt><code>Environment Variables</code></dt>
Eric Engestromdc2dc1f2018-05-14 16:44:08 +0100[diff] [blame]116<dd><p>Meson supports the standard CC and CXX environment variables for
Dylan Baker0ff7eed2018-12-19 13:27:27 -0800[diff] [blame]117changing the default compiler. Meson does support CFLAGS, CXXFLAGS, etc. But
118their use is discouraged because of the many caveats in using them. Instead it
119is recomended to use <code>-D${lang}_args</code> and
120<code>-D${lang}_link_args</code> instead. Among the benefits of these options
121is that they are guaranteed to persist across rebuilds and reconfigurations.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]122
Dylan Baker0ff7eed2018-12-19 13:27:27 -0800[diff] [blame]123Meson does not allow changing compiler in a configured builddir, you will need
124to create a new build dir for a different compiler.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]125</p>
126
127<pre>
128 CC=clang CXX=clang++ meson build-clang
129 ninja -C build-clang
130 ninja -C build-clang clean
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]131 meson configure build -Dc_args="-Wno-typedef-redefinition"
132 ninja -C build-clang
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]133</pre>
134
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]135<p>
136The default compilers depends on your operating system. Meson supports most of
137the popular compilers, a complete list is available
138<a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>.
139</p>
140
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]141<p>Meson also honors <code>DESTDIR</code> for installs</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]142</dd>
143
144
145<dt><code>LLVM</code></dt>
Dylan Bakerbe56f8a2018-09-18 09:09:47 -0700[diff] [blame]146<dd><p>Meson includes upstream logic to wrap llvm-config using its standard
Dylan Bakera57dbe62018-12-20 11:46:08 -0800[diff] [blame]147dependency interface.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]148</p></dd>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800[diff] [blame]149
150<dd><p>
151As of meson 0.49.0 meson also has the concept of a
152<a href="https://mesonbuild.com/Native-environments.html">"native file"</a>,
153these files provide information about the native build environment (as opposed
154to a cross build environment). They are ini formatted and can override where to
155find llvm-config:
156
157custom-llvm.ini
158<pre>
159 [binaries]
160 llvm-config = '/usr/local/bin/llvm/llvm-config'
161</pre>
162
163Then configure meson:
164
165<pre>
166 meson builddir/ --native-file custom-llvm.ini
167</pre>
168</p></dd>
169
170<dd><p>
171For selecting llvm-config for cross compiling a
172<a href="https://mesonbuild.com/Cross-compilation.html#defining-the-environment">"cross file"</a>
173should be used. It uses the same format as the native file above:
174
175cross-llvm.ini
176<pre>
177 [binaries]
178 ...
179 llvm-config = '/usr/lib/llvm-config-32'
180</pre>
181
182Then configure meson:
183
184<pre>
185 meson builddir/ --cross-file cross-llvm.ini
186</pre>
187
188See the <a href="#cross-compilation">Cross Compilation</a> section for more information.
189</dd></p>
190
191<dd><p>
192For older versions of meson <code>$PATH</code> (or <code>%PATH%</code> on
193windows) will be searched for llvm-config (and llvm-config$version and
194llvm-config-$version), you can override this environment variable to control
195the search: <code>PATH=/path/with/llvm-config:$PATH meson build</code>.
196</dd></p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]197</dl>
198
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]199<dl>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]200<dt><code>PKG_CONFIG_PATH</code></dt>
201<dd><p>The
202<code>pkg-config</code> utility is a hard requirement for configuring and
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]203building Mesa on Unix-like systems. It is used to search for external libraries
204on the system. This environment variable is used to control the search path for
205<code>pkg-config</code>. For instance, setting
206<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package
207metadata in <code>/usr/X11R6</code> before the standard directories.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]208</dd>
209</dl>
210
211<p>
212One of the oddities of meson is that some options are different when passed to
213the <code>meson</code> than to <code>meson configure</code>. These options are
214passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson
215configure</code>. Mesa defined options are always passed as -Doption=foo.
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]216</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]217
218<p>For those coming from autotools be aware of the following:</p>
219
220<dl>
221<dt><code>--buildtype/-Dbuildtype</code></dt>
222<dd><p>This option will set the compiler debug/optimisation levels to aid
223debugging the Mesa libraries.</p>
224
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]225<p>Note that in meson this defaults to <code>debugoptimized</code>, and
226not setting it to <code>release</code> will yield non-optimal
227performance and binary size. Not using <code>debug</code> may interfere
228with debugging as some code and validation will be optimized away.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]229</p>
230
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]231<p> For those wishing to pass their own optimization flags, use the <code>plain</code>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]232buildtype, which causes meson to inject no additional compiler arguments, only
233those in the C/CXXFLAGS and those that mesa itself defines.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]234</dd>
235</dl>
236
237<dl>
238<dt><code>-Db_ndebug</code></dt>
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]239<dd><p>This option controls assertions in meson projects. When set to <code>false</code>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]240(the default) assertions are enabled, when set to true they are disabled. This
241is unrelated to the <code>buildtype</code>; setting the latter to
242<code>release</code> will not turn off assertions.
243</p>
244</dd>
245</dl>
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]246
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]247<h2 id="cross-compilation">2. Cross-compilation and 32-bit builds</h2>
248
249<p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports
250cross-compilation</a> by specifying a number of binary paths and
251settings in a file and passing this file to <code>meson</code> or
252<code>meson configure</code> with the <code>--cross-file</code>
253parameter.</p>
254
255<p>This file can live at any location, but you can use the bare filename
256(without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
257~/.local/share/meson/cross</p>
258
259<p>Below are a few example of cross files, but keep in mind that you
260will likely have to alter them for your system.</p>
261
262<p>
Eric Engestrom393a7562019-01-03 16:01:18 +0000[diff] [blame]263Those running on ArchLinux can use the AUR-maintained packages for some
264of those, as they'll have the right values for your system:
265<ul>
266 <li><a href="https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu">meson-cross-x86-linux-gnu</a></li>
267 <li><a href="https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu">meson-cross-aarch64-linux-gnu</a></li>
268</ul>
269</p>
270
271<p>
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]27232-bit build on x86 linux:
273<pre>
274[binaries]
275c = '/usr/bin/gcc'
276cpp = '/usr/bin/g++'
277ar = '/usr/bin/gcc-ar'
278strip = '/usr/bin/strip'
279pkgconfig = '/usr/bin/pkg-config-32'
280llvm-config = '/usr/bin/llvm-config32'
281
282[properties]
283c_args = ['-m32']
284c_link_args = ['-m32']
285cpp_args = ['-m32']
286cpp_link_args = ['-m32']
287
288[host_machine]
289system = 'linux'
290cpu_family = 'x86'
291cpu = 'i686'
292endian = 'little'
293</pre>
294</p>
295
296<p>
29764-bit build on ARM linux:
298<pre>
299[binaries]
300c = '/usr/bin/aarch64-linux-gnu-gcc'
301cpp = '/usr/bin/aarch64-linux-gnu-g++'
Eric Engestrom8b363bc2019-01-03 15:44:42 +0000[diff] [blame]302ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]303strip = '/usr/bin/aarch64-linux-gnu-strip'
304pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
305exe_wrapper = '/usr/bin/qemu-aarch64-static'
306
307[host_machine]
308system = 'linux'
Eric Engestrom8b363bc2019-01-03 15:44:42 +0000[diff] [blame]309cpu_family = 'aarch64'
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]310cpu = 'aarch64'
311endian = 'little'
312</pre>
313</p>
314
315<p>
31664-bit build on x86 windows:
317<pre>
318[binaries]
319c = '/usr/bin/x86_64-w64-mingw32-gcc'
320cpp = '/usr/bin/x86_64-w64-mingw32-g++'
321ar = '/usr/bin/x86_64-w64-mingw32-ar'
322strip = '/usr/bin/x86_64-w64-mingw32-strip'
323pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
324exe_wrapper = 'wine'
325
326[host_machine]
327system = 'windows'
328cpu_family = 'x86_64'
329cpu = 'i686'
330endian = 'little'
331</pre>
332</p>
333
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]334</div>
335</body>
336</html>