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