Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / 45c6da5a48b52594ea7f116a56ce92481fbb964a / . / docs / meson.html
blob: 7ffef817f426ca9ec127d6e95dc460254ce68e71 [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>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]20 <li><a href="#intro">Introduction</a></li>
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]21 <li><a href="#basic">Basic Usage</a></li>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]22 <li><a href="#advanced">Advanced Usage</a></li>
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]23 <li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li>
24</ul>
25
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]26<h2 id="intro">1. Introduction</h2>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]27
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]28<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 -0700[diff] [blame]30
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]31<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 -0700[diff] [blame]35DragonflyBSD, NetBSD, and should work on OpenBSD.</p>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]36
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]37<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
Dylan Baker1da60662018-09-18 09:01:45 -0700[diff] [blame]47<p><strong>Mesa requires Meson >= 0.45.0 to build.</strong>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]48
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 -0700[diff] [blame]52
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]53<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 -0700[diff] [blame]60<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 -0700[diff] [blame^]63be enabled via the <code>--backend</code> switch, as ninja is the default
64backend on all
65operating systems.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]66</p>
67
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]68<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
79</p>
80
81<p>Basic configuration is done with:</p>
82
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]83<pre>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]84meson build/
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]85</pre>
86
87<p>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]88This will create the build directory.
89If any dependencies are missing, you can install them, or try to remove
90the dependency with a Meson configuration option (see below).
Eric Engestromc4c5c902019-01-17 16:26:26 +0000[diff] [blame]91</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]92
Eric Engestromc4c5c902019-01-17 16:26:26 +0000[diff] [blame]93<p>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]94To review the options which Meson chose, run:
95</p>
96<pre>
97meson configure build/
98</pre>
99
100<p>
101Meson does not currently support listing configuration options before
102running "meson build/" but this feature is being discussed upstream.
Eric Engestrom00be88a2019-01-17 18:04:42 +0000[diff] [blame]103For now, we have a <code>bin/meson-options.py</code> script that prints
104the options for you.
105If that script doesn't work for some reason, you can always look in the
Eric Engestromc4c5c902019-01-17 16:26:26 +0000[diff] [blame]106<code>meson_options.txt</code> file at the root of the project.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]107</p>
108
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]109<p>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]110With additional arguments <code>meson configure</code> can be used to change
111options for a previously configured build directory.
112All options passed to this command are in the form
113<code>-D "option"="value"</code>.
114For example:
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]115</p>
116
117<pre>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]118meson configure build/ -Dprefix=/tmp/install -Dglx=true
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]119</pre>
120
121<p>
Eric Engestrom57fbc2a2018-05-14 16:39:42 +0100[diff] [blame]122Note that options taking lists (such as <code>platforms</code>) are
123<a href="http://mesonbuild.com/Build-options.html#using-build-options">a bit
124more complicated</a>, but the simplest form compatible with Mesa options
125is to use a comma to separate values (<code>-D platforms=drm,wayland</code>)
126and brackets to represent an empty list (<code>-D platforms=[]</code>).
127</p>
128
129<p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]130Once you've run the initial <code>meson</code> command successfully you can use
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]131your configured backend to build the project in your build directory:
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]132</p>
133
134<pre>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]135ninja -C build/
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]136</pre>
137
138<p>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]139The next step is to install the Mesa libraries, drivers, etc.
140This also finishes up some final steps of the build process (such as creating
141symbolic links for drivers). To install:
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]142</p>
143
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]144<pre>
145ninja -C build/ install
146</pre>
147
Dylan Bakera8004ef2018-10-22 19:33:08 -0700[diff] [blame]148<p>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]149Note: autotools automatically updates translation files (used by the DRI
150configuration tool) as part of the build process,
151Meson does not do this. Instead, you will need do this:
Dylan Bakera8004ef2018-10-22 19:33:08 -0700[diff] [blame]152</p>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]153<pre>
154ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
155</pre>
156
157<h2 id="advanced">3. Advanced Usage</h2>
Dylan Bakera8004ef2018-10-22 19:33:08 -0700[diff] [blame]158
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]159<dl>
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]160
161<dt>Installation Location</dt>
162<dd>
163<p>
164Meson default to installing libGL.so in your system's main lib/ directory
165and DRI drivers to a dri/ subdirectory.
166</p>
167<p>
168Developers will often want to install Mesa to a testing directory rather
169than the system library directory.
170This can be done with the --prefix option. For example:
171</p>
172<code>
173meson --prefix="${PWD}/build/install" build/
174</code>
175<p>
176will put the final libraries and drivers into the build/install/
177directory.
178Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to that location
179to run/test the driver.
180</p>
181</dd>
182
183<dt>Environment Variables</dt>
Eric Engestromdc2dc1f2018-05-14 16:44:08 +0100[diff] [blame]184<dd><p>Meson supports the standard CC and CXX environment variables for
Dylan Baker0ff7eed2018-12-19 13:27:27 -0800[diff] [blame]185changing the default compiler. Meson does support CFLAGS, CXXFLAGS, etc. But
186their use is discouraged because of the many caveats in using them. Instead it
187is recomended to use <code>-D${lang}_args</code> and
188<code>-D${lang}_link_args</code> instead. Among the benefits of these options
189is that they are guaranteed to persist across rebuilds and reconfigurations.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]190
Dylan Baker0ff7eed2018-12-19 13:27:27 -0800[diff] [blame]191Meson does not allow changing compiler in a configured builddir, you will need
192to create a new build dir for a different compiler.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]193</p>
194
195<pre>
196 CC=clang CXX=clang++ meson build-clang
197 ninja -C build-clang
198 ninja -C build-clang clean
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]199 meson configure build -Dc_args="-Wno-typedef-redefinition"
200 ninja -C build-clang
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]201</pre>
202
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]203<p>
204The default compilers depends on your operating system. Meson supports most of
205the popular compilers, a complete list is available
206<a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>.
207</p>
208
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]209<p>Meson also honors <code>DESTDIR</code> for installs</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]210</dd>
211
212
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]213<dt>LLVM</dt>
Dylan Bakerbe56f8a2018-09-18 09:09:47 -0700[diff] [blame]214<dd><p>Meson includes upstream logic to wrap llvm-config using its standard
Dylan Bakera57dbe62018-12-20 11:46:08 -0800[diff] [blame]215dependency interface.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]216</p></dd>
Dylan Bakera57dbe62018-12-20 11:46:08 -0800[diff] [blame]217
218<dd><p>
219As of meson 0.49.0 meson also has the concept of a
220<a href="https://mesonbuild.com/Native-environments.html">"native file"</a>,
221these files provide information about the native build environment (as opposed
222to a cross build environment). They are ini formatted and can override where to
223find llvm-config:
224
225custom-llvm.ini
226<pre>
227 [binaries]
228 llvm-config = '/usr/local/bin/llvm/llvm-config'
229</pre>
230
231Then configure meson:
232
233<pre>
234 meson builddir/ --native-file custom-llvm.ini
235</pre>
236</p></dd>
237
238<dd><p>
239For selecting llvm-config for cross compiling a
240<a href="https://mesonbuild.com/Cross-compilation.html#defining-the-environment">"cross file"</a>
241should be used. It uses the same format as the native file above:
242
243cross-llvm.ini
244<pre>
245 [binaries]
246 ...
247 llvm-config = '/usr/lib/llvm-config-32'
248</pre>
249
250Then configure meson:
251
252<pre>
253 meson builddir/ --cross-file cross-llvm.ini
254</pre>
255
256See the <a href="#cross-compilation">Cross Compilation</a> section for more information.
257</dd></p>
258
259<dd><p>
260For older versions of meson <code>$PATH</code> (or <code>%PATH%</code> on
261windows) will be searched for llvm-config (and llvm-config$version and
262llvm-config-$version), you can override this environment variable to control
263the search: <code>PATH=/path/with/llvm-config:$PATH meson build</code>.
264</dd></p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]265</dl>
266
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]267<dl>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]268<dt><code>PKG_CONFIG_PATH</code></dt>
269<dd><p>The
270<code>pkg-config</code> utility is a hard requirement for configuring and
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]271building Mesa on Unix-like systems. It is used to search for external libraries
272on the system. This environment variable is used to control the search path for
273<code>pkg-config</code>. For instance, setting
274<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package
275metadata in <code>/usr/X11R6</code> before the standard directories.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]276</dd>
277</dl>
278
279<p>
280One of the oddities of meson is that some options are different when passed to
281the <code>meson</code> than to <code>meson configure</code>. These options are
282passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson
283configure</code>. Mesa defined options are always passed as -Doption=foo.
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]284</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]285
286<p>For those coming from autotools be aware of the following:</p>
287
288<dl>
289<dt><code>--buildtype/-Dbuildtype</code></dt>
290<dd><p>This option will set the compiler debug/optimisation levels to aid
291debugging the Mesa libraries.</p>
292
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]293<p>Note that in meson this defaults to <code>debugoptimized</code>, and
294not setting it to <code>release</code> will yield non-optimal
295performance and binary size. Not using <code>debug</code> may interfere
296with debugging as some code and validation will be optimized away.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]297</p>
298
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]299<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]300buildtype, which causes meson to inject no additional compiler arguments, only
301those in the C/CXXFLAGS and those that mesa itself defines.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]302</dd>
303</dl>
304
305<dl>
306<dt><code>-Db_ndebug</code></dt>
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]307<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]308(the default) assertions are enabled, when set to true they are disabled. This
309is unrelated to the <code>buildtype</code>; setting the latter to
310<code>release</code> will not turn off assertions.
311</p>
312</dd>
313</dl>
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]314
Brian Paul45c6da52019-03-07 20:39:49 -0700[diff] [blame^]315<h2 id="cross-compilation">4. Cross-compilation and 32-bit builds</h2>
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]316
317<p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports
318cross-compilation</a> by specifying a number of binary paths and
319settings in a file and passing this file to <code>meson</code> or
320<code>meson configure</code> with the <code>--cross-file</code>
321parameter.</p>
322
323<p>This file can live at any location, but you can use the bare filename
324(without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
325~/.local/share/meson/cross</p>
326
327<p>Below are a few example of cross files, but keep in mind that you
328will likely have to alter them for your system.</p>
329
330<p>
Eric Engestrom393a7562019-01-03 16:01:18 +0000[diff] [blame]331Those running on ArchLinux can use the AUR-maintained packages for some
332of those, as they'll have the right values for your system:
333<ul>
334 <li><a href="https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu">meson-cross-x86-linux-gnu</a></li>
335 <li><a href="https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu">meson-cross-aarch64-linux-gnu</a></li>
336</ul>
337</p>
338
339<p>
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]34032-bit build on x86 linux:
341<pre>
342[binaries]
343c = '/usr/bin/gcc'
344cpp = '/usr/bin/g++'
345ar = '/usr/bin/gcc-ar'
346strip = '/usr/bin/strip'
347pkgconfig = '/usr/bin/pkg-config-32'
348llvm-config = '/usr/bin/llvm-config32'
349
350[properties]
351c_args = ['-m32']
352c_link_args = ['-m32']
353cpp_args = ['-m32']
354cpp_link_args = ['-m32']
355
356[host_machine]
357system = 'linux'
358cpu_family = 'x86'
359cpu = 'i686'
360endian = 'little'
361</pre>
362</p>
363
364<p>
36564-bit build on ARM linux:
366<pre>
367[binaries]
368c = '/usr/bin/aarch64-linux-gnu-gcc'
369cpp = '/usr/bin/aarch64-linux-gnu-g++'
Eric Engestrom8b363bc2019-01-03 15:44:42 +0000[diff] [blame]370ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]371strip = '/usr/bin/aarch64-linux-gnu-strip'
372pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
373exe_wrapper = '/usr/bin/qemu-aarch64-static'
374
375[host_machine]
376system = 'linux'
Eric Engestrom8b363bc2019-01-03 15:44:42 +0000[diff] [blame]377cpu_family = 'aarch64'
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame]378cpu = 'aarch64'
379endian = 'little'
380</pre>
381</p>
382
383<p>
38464-bit build on x86 windows:
385<pre>
386[binaries]
387c = '/usr/bin/x86_64-w64-mingw32-gcc'
388cpp = '/usr/bin/x86_64-w64-mingw32-g++'
389ar = '/usr/bin/x86_64-w64-mingw32-ar'
390strip = '/usr/bin/x86_64-w64-mingw32-strip'
391pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
392exe_wrapper = 'wine'
393
394[host_machine]
395system = 'windows'
396cpu_family = 'x86_64'
397cpu = 'i686'
398endian = 'little'
399</pre>
400</p>
401
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]402</div>
403</body>
404</html>