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