Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / b45aa6290bfcecf6a33dd5eb20f333907fb09251 / . / docs / meson.html
blob: 68f80d6ac42d6f48d359f43302de08f3080be2e8 [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
19<h2 id="basic">1. Basic Usage</h2>
20
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]21<p><strong>The Meson build system is generally considered stable and ready
22for production</strong></p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]23
Dylan Baker1da60662018-09-18 09:01:45 -0700[diff] [blame]24<p>The meson build is tested on Linux, macOS, Cygwin and Haiku, FreeBSD,
25DragonflyBSD, NetBSD, and should work on OpenBSD.</p>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]26
Dylan Baker1da60662018-09-18 09:01:45 -0700[diff] [blame]27<p><strong>Mesa requires Meson >= 0.45.0 to build.</strong>
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]28
29Some older versions of meson do not check that they are too old and will error
30out in odd ways.
31</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]32
33<p>
34The meson program is used to configure the source directory and generates
35either a ninja build file or Visual Studio® build files. The latter must
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]36be 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]37operating systems. Meson only supports out-of-tree builds, and must be passed a
38directory to put built and generated sources into. We'll call that directory
39"build" for examples.
40</p>
41
42<pre>
43 meson build/
44</pre>
45
46<p>
47To see a description of your options you can run <code>meson configure</code>
48along with a build directory to view the selected options for. This will show
49your meson global arguments and project arguments, along with their defaults
50and your local settings.
51
Eric Engestromdc2dc1f2018-05-14 16:44:08 +0100[diff] [blame]52Meson does not currently support listing options before configure a build
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]53directory, but this feature is being discussed upstream.
54</p>
55
56<pre>
57 meson configure build/
58</pre>
59
60<p>
61With additional arguments <code>meson configure</code> is used to change
62options on already configured build directory. All options passed to this
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]63command are in the form <code>-D "command"="value"</code>.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]64</p>
65
66<pre>
67 meson configure build/ -Dprefix=/tmp/install -Dglx=true
68</pre>
69
70<p>
Eric Engestrom57fbc2a2018-05-14 16:39:42 +0100[diff] [blame]71Note that options taking lists (such as <code>platforms</code>) are
72<a href="http://mesonbuild.com/Build-options.html#using-build-options">a bit
73more complicated</a>, but the simplest form compatible with Mesa options
74is to use a comma to separate values (<code>-D platforms=drm,wayland</code>)
75and brackets to represent an empty list (<code>-D platforms=[]</code>).
76</p>
77
78<p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]79Once you've run the initial <code>meson</code> command successfully you can use
80your configured backend to build the project. With ninja, the -C option can be
81be used to point at a directory to build.
82</p>
83
84<pre>
85 ninja -C build/
86</pre>
87
88<p>
89Without arguments, it will produce libGL.so and/or several other libraries
90depending on the options you have chosen. Later, if you want to rebuild for a
91different configuration, you should run <code>ninja clean</code> before
92changing the configuration, or create a new out of tree build directory for
Eric Engestrom5829f612018-05-14 16:47:18 +0100[diff] [blame]93each configuration you want to build
94<a href="http://mesonbuild.com/Using-multiple-build-directories.html">as
95recommended in the documentation</a>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]96</p>
97
Dylan Bakera8004ef2018-10-22 19:33:08 -0700[diff] [blame]98<p>
99Autotools automatically updates translation files as part of the build process,
100meson does not do this. Instead if you want translated drirc files you will need
101to invoke non-default targets for ninja to update them:
102<code>ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo</code>
103</p>
104
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]105<dl>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]106<dt><code>Environment Variables</code></dt>
Eric Engestromdc2dc1f2018-05-14 16:44:08 +0100[diff] [blame]107<dd><p>Meson supports the standard CC and CXX environment variables for
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]108changing the default compiler, and CFLAGS, CXXFLAGS, and LDFLAGS for setting
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]109options to the compiler and linker during the initial configuration.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]110
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]111These arguments are consumed and stored by meson when it is initialized. To
112change these flags after the build is initialized (or when doing a first
113initialization), consider using <code>-D${lang}_args</code> and
114<code>-D${lang}_link_args</code> instead. Meson will never change compiler in a
115configured build directory.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]116</p>
117
118<pre>
119 CC=clang CXX=clang++ meson build-clang
120 ninja -C build-clang
121 ninja -C build-clang clean
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]122 meson configure build -Dc_args="-Wno-typedef-redefinition"
123 ninja -C build-clang
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]124</pre>
125
Dylan Bakere0829f92018-09-18 09:07:25 -0700[diff] [blame]126<p>
127The default compilers depends on your operating system. Meson supports most of
128the popular compilers, a complete list is available
129<a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>.
130</p>
131
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]132<p>Meson also honors <code>DESTDIR</code> for installs</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]133</dd>
134
135
136<dt><code>LLVM</code></dt>
Dylan Bakerbe56f8a2018-09-18 09:09:47 -0700[diff] [blame]137<dd><p>Meson includes upstream logic to wrap llvm-config using its standard
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]138dependency interface. It will search <code>$PATH</code> (or <code>%PATH%</code> on windows) for
Dylan Bakerbe56f8a2018-09-18 09:09:47 -0700[diff] [blame]139llvm-config (and llvm-config$version and llvm-config-$version), so using an
140LLVM from a non-standard path is as easy as
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]141<code>PATH=/path/with/llvm-config:$PATH meson build</code>.
142</p></dd>
143</dl>
144
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]145<dl>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]146<dt><code>PKG_CONFIG_PATH</code></dt>
147<dd><p>The
148<code>pkg-config</code> utility is a hard requirement for configuring and
Dylan Baker2aad12b2018-03-01 11:32:56 -0800[diff] [blame]149building Mesa on Unix-like systems. It is used to search for external libraries
150on the system. This environment variable is used to control the search path for
151<code>pkg-config</code>. For instance, setting
152<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package
153metadata in <code>/usr/X11R6</code> before the standard directories.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]154</dd>
155</dl>
156
157<p>
158One of the oddities of meson is that some options are different when passed to
159the <code>meson</code> than to <code>meson configure</code>. These options are
160passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson
161configure</code>. Mesa defined options are always passed as -Doption=foo.
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]162</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]163
164<p>For those coming from autotools be aware of the following:</p>
165
166<dl>
167<dt><code>--buildtype/-Dbuildtype</code></dt>
168<dd><p>This option will set the compiler debug/optimisation levels to aid
169debugging the Mesa libraries.</p>
170
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]171<p>Note that in meson this defaults to <code>debugoptimized</code>, and
172not setting it to <code>release</code> will yield non-optimal
173performance and binary size. Not using <code>debug</code> may interfere
174with debugging as some code and validation will be optimized away.
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]175</p>
176
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]177<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]178buildtype, which causes meson to inject no additional compiler arguments, only
179those in the C/CXXFLAGS and those that mesa itself defines.</p>
Dylan Bakerbc17ac52017-10-17 12:19:49 -0700[diff] [blame]180</dd>
181</dl>
182
183<dl>
184<dt><code>-Db_ndebug</code></dt>
Eric Engestrom37d44e22018-05-14 16:47:57 +0100[diff] [blame]185<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]186(the default) assertions are enabled, when set to true they are disabled. This
187is unrelated to the <code>buildtype</code>; setting the latter to
188<code>release</code> will not turn off assertions.
189</p>
190</dd>
191</dl>
Eric Engestrom67c55072018-05-14 16:45:31 +0100[diff] [blame]192
193</div>
194</body>
195</html>