Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / b0319d07683c8d76a93e233b918ea61b38438a3c / . / docs / meson.html
blob: 21e15ad1c1db1f6e85dab0a5f4677eafbfdd412a [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 Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]113changing the default compiler, and CFLAGS, CXXFLAGS, and LDFLAGS for setting
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]114options to the compiler and linker during the initial configuration.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]115
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]116These arguments are consumed and stored by meson when it is initialized. To
117change these flags after the build is initialized (or when doing a first
118initialization), consider using <code>-D${lang}_args</code> and
119<code>-D${lang}_link_args</code> instead. Meson will never change compiler in a
120configured build directory.
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
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]143dependency interface. It will search <code>$PATH</code> (or <code>%PATH%</code> on windows) for
Dylan Bakerbe56f8a2018-09-18 09:09:47 -0700[diff] [blame]144llvm-config (and llvm-config$version and llvm-config-$version), so using an
145LLVM from a non-standard path is as easy as
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]146<code>PATH=/path/with/llvm-config:$PATH meson build</code>.
147</p></dd>
148</dl>
149
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]150<dl>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]151<dt><code>PKG_CONFIG_PATH</code></dt>
152<dd><p>The
153<code>pkg-config</code> utility is a hard requirement for configuring and
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]154building Mesa on Unix-like systems. It is used to search for external libraries
155on the system. This environment variable is used to control the search path for
156<code>pkg-config</code>. For instance, setting
157<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package
158metadata in <code>/usr/X11R6</code> before the standard directories.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]159</dd>
160</dl>
161
162<p>
163One of the oddities of meson is that some options are different when passed to
164the <code>meson</code> than to <code>meson configure</code>. These options are
165passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson
166configure</code>. Mesa defined options are always passed as -Doption=foo.
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]167</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]168
169<p>For those coming from autotools be aware of the following:</p>
170
171<dl>
172<dt><code>--buildtype/-Dbuildtype</code></dt>
173<dd><p>This option will set the compiler debug/optimisation levels to aid
174debugging the Mesa libraries.</p>
175
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]176<p>Note that in meson this defaults to <code>debugoptimized</code>, and
177not setting it to <code>release</code> will yield non-optimal
178performance and binary size. Not using <code>debug</code> may interfere
179with debugging as some code and validation will be optimized away.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]180</p>
181
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]182<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]183buildtype, which causes meson to inject no additional compiler arguments, only
184those in the C/CXXFLAGS and those that mesa itself defines.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]185</dd>
186</dl>
187
188<dl>
189<dt><code>-Db_ndebug</code></dt>
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]190<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]191(the default) assertions are enabled, when set to true they are disabled. This
192is unrelated to the <code>buildtype</code>; setting the latter to
193<code>release</code> will not turn off assertions.
194</p>
195</dd>
196</dl>
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]197
Eric Engestromb0319d02018-11-29 13:16:42 +0000[diff] [blame^]198<h2 id="cross-compilation">2. Cross-compilation and 32-bit builds</h2>
199
200<p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports
201cross-compilation</a> by specifying a number of binary paths and
202settings in a file and passing this file to <code>meson</code> or
203<code>meson configure</code> with the <code>--cross-file</code>
204parameter.</p>
205
206<p>This file can live at any location, but you can use the bare filename
207(without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
208~/.local/share/meson/cross</p>
209
210<p>Below are a few example of cross files, but keep in mind that you
211will likely have to alter them for your system.</p>
212
213<p>
21432-bit build on x86 linux:
215<pre>
216[binaries]
217c = '/usr/bin/gcc'
218cpp = '/usr/bin/g++'
219ar = '/usr/bin/gcc-ar'
220strip = '/usr/bin/strip'
221pkgconfig = '/usr/bin/pkg-config-32'
222llvm-config = '/usr/bin/llvm-config32'
223
224[properties]
225c_args = ['-m32']
226c_link_args = ['-m32']
227cpp_args = ['-m32']
228cpp_link_args = ['-m32']
229
230[host_machine]
231system = 'linux'
232cpu_family = 'x86'
233cpu = 'i686'
234endian = 'little'
235</pre>
236</p>
237
238<p>
23964-bit build on ARM linux:
240<pre>
241[binaries]
242c = '/usr/bin/aarch64-linux-gnu-gcc'
243cpp = '/usr/bin/aarch64-linux-gnu-g++'
244ar = '/usr/bin/aarch64-linux-gnu-ar'
245strip = '/usr/bin/aarch64-linux-gnu-strip'
246pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
247exe_wrapper = '/usr/bin/qemu-aarch64-static'
248
249[host_machine]
250system = 'linux'
251cpu_family = 'arm'
252cpu = 'aarch64'
253endian = 'little'
254</pre>
255</p>
256
257<p>
25864-bit build on x86 windows:
259<pre>
260[binaries]
261c = '/usr/bin/x86_64-w64-mingw32-gcc'
262cpp = '/usr/bin/x86_64-w64-mingw32-g++'
263ar = '/usr/bin/x86_64-w64-mingw32-ar'
264strip = '/usr/bin/x86_64-w64-mingw32-strip'
265pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
266exe_wrapper = 'wine'
267
268[host_machine]
269system = 'windows'
270cpu_family = 'x86_64'
271cpu = 'i686'
272endian = 'little'
273</pre>
274</p>
275
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]276</div>
277</body>
278</html>