1b8e80941Smrg<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2b8e80941Smrg<html lang="en"> 3b8e80941Smrg<head> 4b8e80941Smrg <meta http-equiv="content-type" content="text/html; charset=utf-8"> 5b8e80941Smrg <title>Compilation and Installation using Meson</title> 6b8e80941Smrg <link rel="stylesheet" type="text/css" href="mesa.css"> 7b8e80941Smrg</head> 8b8e80941Smrg<body> 9b8e80941Smrg 10b8e80941Smrg<div class="header"> 11b8e80941Smrg <h1>The Mesa 3D Graphics Library</h1> 12b8e80941Smrg</div> 13b8e80941Smrg 14b8e80941Smrg<iframe src="contents.html"></iframe> 15b8e80941Smrg<div class="content"> 16b8e80941Smrg 17b8e80941Smrg<h1>Compilation and Installation using Meson</h1> 18b8e80941Smrg 19b8e80941Smrg<ul> 20b8e80941Smrg <li><a href="#intro">Introduction</a></li> 21b8e80941Smrg <li><a href="#basic">Basic Usage</a></li> 22b8e80941Smrg <li><a href="#advanced">Advanced Usage</a></li> 23b8e80941Smrg <li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li> 24b8e80941Smrg</ul> 25b8e80941Smrg 26b8e80941Smrg<h2 id="intro">1. Introduction</h2> 27b8e80941Smrg 28b8e80941Smrg<p>For general information about Meson see the 29b8e80941Smrg<a href="http://mesonbuild.com/">Meson website</a>.</p> 30b8e80941Smrg 31b8e80941Smrg<p><strong>Mesa's Meson build system is generally considered stable and ready 32b8e80941Smrgfor production.</strong></p> 33b8e80941Smrg 34b8e80941Smrg<p>The Meson build of Mesa is tested on Linux, macOS, Cygwin and Haiku, FreeBSD, 35b8e80941SmrgDragonflyBSD, NetBSD, and should work on OpenBSD.</p> 36b8e80941Smrg 37b8e80941Smrg<p>If Meson is not already installed on your system, you can typically 38b8e80941Smrginstall it with your package installer. For example:</p> 39b8e80941Smrg<pre> 40b8e80941Smrgsudo apt-get install meson # Ubuntu 41b8e80941Smrg</pre> 42b8e80941Smrgor 43b8e80941Smrg<pre> 44b8e80941Smrgsudo dnf install meson # Fedora 45b8e80941Smrg</pre> 46b8e80941Smrg 47b8e80941Smrg<p><strong>Mesa requires Meson >= 0.45.0 to build.</strong> 48b8e80941Smrg 49b8e80941SmrgSome older versions of meson do not check that they are too old and will error 50b8e80941Smrgout in odd ways. 51b8e80941Smrg</p> 52b8e80941Smrg 53b8e80941Smrg<p>You'll also need <a href="https://ninja-build.org/">Ninja</a>. 54b8e80941SmrgIf it's not already installed, use apt-get or dnf to install 55b8e80941Smrgthe <em>ninja-build</em> package. 56b8e80941Smrg</p> 57b8e80941Smrg 58b8e80941Smrg<h2 id="basic">2. Basic Usage</h2> 59b8e80941Smrg 60b8e80941Smrg<p> 61b8e80941SmrgThe meson program is used to configure the source directory and generates 62b8e80941Smrgeither a ninja build file or Visual Studio® build files. The latter must 63b8e80941Smrgbe enabled via the <code>--backend</code> switch, as ninja is the default 64b8e80941Smrgbackend on all 65b8e80941Smrgoperating systems. 66b8e80941Smrg</p> 67b8e80941Smrg 68b8e80941Smrg<p> 69b8e80941SmrgMeson only supports out-of-tree builds, and must be passed a 70b8e80941Smrgdirectory to put built and generated sources into. We'll call that directory 71b8e80941Smrg"build" here. 72b8e80941SmrgIt's recommended to create a 73b8e80941Smrg<a href="http://mesonbuild.com/Using-multiple-build-directories.html"> 74b8e80941Smrgseparate build directory</a> for each configuration you might want to use. 75b8e80941Smrg</p> 76b8e80941Smrg 77b8e80941Smrg 78b8e80941Smrg 79b8e80941Smrg<p>Basic configuration is done with:</p> 80b8e80941Smrg 81b8e80941Smrg<pre> 82b8e80941Smrgmeson build/ 83b8e80941Smrg</pre> 84b8e80941Smrg 85b8e80941Smrg<p> 86b8e80941SmrgThis will create the build directory. 87b8e80941SmrgIf any dependencies are missing, you can install them, or try to remove 88b8e80941Smrgthe dependency with a Meson configuration option (see below). 89b8e80941Smrg</p> 90b8e80941Smrg 91b8e80941Smrg<p> 92b8e80941SmrgTo review the options which Meson chose, run: 93b8e80941Smrg</p> 94b8e80941Smrg<pre> 95b8e80941Smrgmeson configure build/ 96b8e80941Smrg</pre> 97b8e80941Smrg 98b8e80941Smrg<p> 99b8e80941SmrgMeson does not currently support listing configuration options before 100b8e80941Smrgrunning "meson build/" but this feature is being discussed upstream. 101b8e80941SmrgFor now, we have a <code>bin/meson-options.py</code> script that prints 102b8e80941Smrgthe options for you. 103b8e80941SmrgIf that script doesn't work for some reason, you can always look in the 104b8e80941Smrg<a href="https://gitlab.freedesktop.org/mesa/mesa/blob/master/meson_options.txt"> 105b8e80941Smrgmeson_options.txt</a> file at the root of the project. 106b8e80941Smrg</p> 107b8e80941Smrg 108b8e80941Smrg<p> 109b8e80941SmrgWith additional arguments <code>meson configure</code> can be used to change 110b8e80941Smrgoptions for a previously configured build directory. 111b8e80941SmrgAll options passed to this command are in the form 112b8e80941Smrg<code>-D "option"="value"</code>. 113b8e80941SmrgFor example: 114b8e80941Smrg</p> 115b8e80941Smrg 116b8e80941Smrg<pre> 117b8e80941Smrgmeson configure build/ -Dprefix=/tmp/install -Dglx=true 118b8e80941Smrg</pre> 119b8e80941Smrg 120b8e80941Smrg<p> 121b8e80941SmrgNote that options taking lists (such as <code>platforms</code>) are 122b8e80941Smrg<a href="http://mesonbuild.com/Build-options.html#using-build-options">a bit 123b8e80941Smrgmore complicated</a>, but the simplest form compatible with Mesa options 124b8e80941Smrgis to use a comma to separate values (<code>-D platforms=drm,wayland</code>) 125b8e80941Smrgand brackets to represent an empty list (<code>-D platforms=[]</code>). 126b8e80941Smrg</p> 127b8e80941Smrg 128b8e80941Smrg<p> 129b8e80941SmrgOnce you've run the initial <code>meson</code> command successfully you can use 130b8e80941Smrgyour configured backend to build the project in your build directory: 131b8e80941Smrg</p> 132b8e80941Smrg 133b8e80941Smrg<pre> 134b8e80941Smrgninja -C build/ 135b8e80941Smrg</pre> 136b8e80941Smrg 137b8e80941Smrg<p> 138b8e80941SmrgThe next step is to install the Mesa libraries, drivers, etc. 139b8e80941SmrgThis also finishes up some final steps of the build process (such as creating 140b8e80941Smrgsymbolic links for drivers). To install: 141b8e80941Smrg</p> 142b8e80941Smrg 143b8e80941Smrg<pre> 144b8e80941Smrgninja -C build/ install 145b8e80941Smrg</pre> 146b8e80941Smrg 147b8e80941Smrg<p> 148b8e80941SmrgNote: autotools automatically updated translation files (used by the DRI 149b8e80941Smrgconfiguration tool) as part of the build process, 150b8e80941SmrgMeson does not do this. Instead, you will need do this: 151b8e80941Smrg</p> 152b8e80941Smrg<pre> 153b8e80941Smrgninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo 154b8e80941Smrg</pre> 155b8e80941Smrg 156b8e80941Smrg<h2 id="advanced">3. Advanced Usage</h2> 157b8e80941Smrg 158b8e80941Smrg<dl> 159b8e80941Smrg 160b8e80941Smrg<dt>Installation Location</dt> 161b8e80941Smrg<dd> 162b8e80941Smrg<p> 163b8e80941SmrgMeson default to installing libGL.so in your system's main lib/ directory 164b8e80941Smrgand DRI drivers to a dri/ subdirectory. 165b8e80941Smrg</p> 166b8e80941Smrg<p> 167b8e80941SmrgDevelopers will often want to install Mesa to a testing directory rather 168b8e80941Smrgthan the system library directory. 169b8e80941SmrgThis can be done with the --prefix option. For example: 170b8e80941Smrg</p> 171b8e80941Smrg<pre> 172b8e80941Smrgmeson --prefix="${PWD}/build/install" build/ 173b8e80941Smrg</pre> 174b8e80941Smrg<p> 175b8e80941Smrgwill put the final libraries and drivers into the build/install/ 176b8e80941Smrgdirectory. 177b8e80941SmrgThen you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to that location 178b8e80941Smrgto run/test the driver. 179b8e80941Smrg</p> 180b8e80941Smrg<p> 181b8e80941SmrgMeson also honors <code>DESTDIR</code> for installs. 182b8e80941Smrg</p> 183b8e80941Smrg</dd> 184b8e80941Smrg 185b8e80941Smrg<dt>Compiler Options</dt> 186b8e80941Smrg<dd> 187b8e80941Smrg<p>Meson supports the common CFLAGS, CXXFLAGS, etc. environment 188b8e80941Smrgvariables but their use is discouraged because of the many caveats 189b8e80941Smrgin using them. 190b8e80941Smrg</p> 191b8e80941Smrg<p>Instead, it is recomended to use <code>-D${lang}_args</code> and 192b8e80941Smrg<code>-D${lang}_link_args</code>. Among the benefits of these options 193b8e80941Smrgis that they are guaranteed to persist across rebuilds and reconfigurations. 194b8e80941Smrg</p> 195b8e80941Smrg<p> 196b8e80941SmrgThis example sets -fmax-errors for compiling C sources and -DMAGIC=123 197b8e80941Smrgfor C++ sources: 198b8e80941Smrg</p> 199b8e80941Smrg<pre> 200b8e80941Smrgmeson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123 201b8e80941Smrg</pre> 202b8e80941Smrg</dd> 203b8e80941Smrg 204b8e80941Smrg 205b8e80941Smrg<dt>Compiler Specification</dt> 206b8e80941Smrg<dd> 207b8e80941Smrg<p> 208b8e80941SmrgMeson supports the standard CC and CXX environment variables for 209b8e80941Smrgchanging the default compiler. Note that Meson does not allow 210b8e80941Smrgchanging the compilers in a configured builddir so you will need 211b8e80941Smrgto create a new build dir for a different compiler. 212b8e80941Smrg</p> 213b8e80941Smrg<p> 214b8e80941SmrgThis is an example of specifying the clang compilers and cleaning 215b8e80941Smrgthe build directory before reconfiguring with an extra C option: 216b8e80941Smrg</p> 217b8e80941Smrg<pre> 218b8e80941SmrgCC=clang CXX=clang++ meson build-clang 219b8e80941Smrgninja -C build-clang 220b8e80941Smrgninja -C build-clang clean 221b8e80941Smrgmeson configure build -Dc_args="-Wno-typedef-redefinition" 222b8e80941Smrgninja -C build-clang 223b8e80941Smrg</pre> 224b8e80941Smrg<p> 225b8e80941SmrgThe default compilers depends on your operating system. Meson supports most of 226b8e80941Smrgthe popular compilers, a complete list is available 227b8e80941Smrg<a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>. 228b8e80941Smrg</p> 229b8e80941Smrg</dd> 230b8e80941Smrg 231b8e80941Smrg<dt>LLVM</dt> 232b8e80941Smrg<dd><p>Meson includes upstream logic to wrap llvm-config using its standard 233b8e80941Smrgdependency interface. 234b8e80941Smrg</p></dd> 235b8e80941Smrg 236b8e80941Smrg<dd><p> 237b8e80941SmrgAs of meson 0.49.0 meson also has the concept of a 238b8e80941Smrg<a href="https://mesonbuild.com/Native-environments.html">"native file"</a>, 239b8e80941Smrgthese files provide information about the native build environment (as opposed 240b8e80941Smrgto a cross build environment). They are ini formatted and can override where to 241b8e80941Smrgfind llvm-config: 242b8e80941Smrg</p> 243b8e80941Smrg 244b8e80941Smrgcustom-llvm.ini 245b8e80941Smrg<pre> 246b8e80941Smrg [binaries] 247b8e80941Smrg llvm-config = '/usr/local/bin/llvm/llvm-config' 248b8e80941Smrg</pre> 249b8e80941Smrg 250b8e80941SmrgThen configure meson: 251b8e80941Smrg 252b8e80941Smrg<pre> 253b8e80941Smrg meson builddir/ --native-file custom-llvm.ini 254b8e80941Smrg</pre> 255b8e80941Smrg</dd> 256b8e80941Smrg 257b8e80941Smrg<dd><p> 258b8e80941SmrgFor selecting llvm-config for cross compiling a 259b8e80941Smrg<a href="https://mesonbuild.com/Cross-compilation.html#defining-the-environment">"cross file"</a> 260b8e80941Smrgshould be used. It uses the same format as the native file above: 261b8e80941Smrg</p> 262b8e80941Smrg 263b8e80941Smrg<p>cross-llvm.ini</p> 264b8e80941Smrg<pre> 265b8e80941Smrg [binaries] 266b8e80941Smrg ... 267b8e80941Smrg llvm-config = '/usr/lib/llvm-config-32' 268b8e80941Smrg</pre> 269b8e80941Smrg 270b8e80941Smrg<p>Then configure meson:</p> 271b8e80941Smrg<pre> 272b8e80941Smrg meson builddir/ --cross-file cross-llvm.ini 273b8e80941Smrg</pre> 274b8e80941Smrg 275b8e80941SmrgSee the <a href="#cross-compilation">Cross Compilation</a> section for more information. 276b8e80941Smrg</dd> 277b8e80941Smrg 278b8e80941Smrg<dd><p> 279b8e80941SmrgFor older versions of meson <code>$PATH</code> (or <code>%PATH%</code> on 280b8e80941Smrgwindows) will be searched for llvm-config (and llvm-config$version and 281b8e80941Smrgllvm-config-$version), you can override this environment variable to control 282b8e80941Smrgthe search: <code>PATH=/path/with/llvm-config:$PATH meson build</code>. 283b8e80941Smrg</p></dd> 284b8e80941Smrg 285b8e80941Smrg<dt><code>PKG_CONFIG_PATH</code></dt> 286b8e80941Smrg<dd><p>The 287b8e80941Smrg<code>pkg-config</code> utility is a hard requirement for configuring and 288b8e80941Smrgbuilding Mesa on Unix-like systems. It is used to search for external libraries 289b8e80941Smrgon the system. This environment variable is used to control the search path for 290b8e80941Smrg<code>pkg-config</code>. For instance, setting 291b8e80941Smrg<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package 292b8e80941Smrgmetadata in <code>/usr/X11R6</code> before the standard directories.</p> 293b8e80941Smrg</dd> 294b8e80941Smrg</dl> 295b8e80941Smrg 296b8e80941Smrg<p> 297b8e80941SmrgOne of the oddities of meson is that some options are different when passed to 298b8e80941Smrgthe <code>meson</code> than to <code>meson configure</code>. These options are 299b8e80941Smrgpassed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson 300b8e80941Smrgconfigure</code>. Mesa defined options are always passed as -Doption=foo. 301b8e80941Smrg</p> 302b8e80941Smrg 303b8e80941Smrg<p>For those coming from autotools be aware of the following:</p> 304b8e80941Smrg 305b8e80941Smrg<dl> 306b8e80941Smrg<dt><code>--buildtype/-Dbuildtype</code></dt> 307b8e80941Smrg<dd><p>This option will set the compiler debug/optimisation levels to aid 308b8e80941Smrgdebugging the Mesa libraries.</p> 309b8e80941Smrg 310b8e80941Smrg<p>Note that in meson this defaults to <code>debugoptimized</code>, and 311b8e80941Smrgnot setting it to <code>release</code> will yield non-optimal 312b8e80941Smrgperformance and binary size. Not using <code>debug</code> may interfere 313b8e80941Smrgwith debugging as some code and validation will be optimized away. 314b8e80941Smrg</p> 315b8e80941Smrg 316b8e80941Smrg<p> For those wishing to pass their own optimization flags, use the <code>plain</code> 317b8e80941Smrgbuildtype, which causes meson to inject no additional compiler arguments, only 318b8e80941Smrgthose in the C/CXXFLAGS and those that mesa itself defines.</p> 319b8e80941Smrg</dd> 320b8e80941Smrg 321b8e80941Smrg<dt><code>-Db_ndebug</code></dt> 322b8e80941Smrg<dd><p>This option controls assertions in meson projects. When set to <code>false</code> 323b8e80941Smrg(the default) assertions are enabled, when set to true they are disabled. This 324b8e80941Smrgis unrelated to the <code>buildtype</code>; setting the latter to 325b8e80941Smrg<code>release</code> will not turn off assertions. 326b8e80941Smrg</p> 327b8e80941Smrg</dd> 328b8e80941Smrg</dl> 329b8e80941Smrg 330b8e80941Smrg<h2 id="cross-compilation">4. Cross-compilation and 32-bit builds</h2> 331b8e80941Smrg 332b8e80941Smrg<p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports 333b8e80941Smrgcross-compilation</a> by specifying a number of binary paths and 334b8e80941Smrgsettings in a file and passing this file to <code>meson</code> or 335b8e80941Smrg<code>meson configure</code> with the <code>--cross-file</code> 336b8e80941Smrgparameter.</p> 337b8e80941Smrg 338b8e80941Smrg<p>This file can live at any location, but you can use the bare filename 339b8e80941Smrg(without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or 340b8e80941Smrg~/.local/share/meson/cross</p> 341b8e80941Smrg 342b8e80941Smrg<p>Below are a few example of cross files, but keep in mind that you 343b8e80941Smrgwill likely have to alter them for your system.</p> 344b8e80941Smrg 345b8e80941Smrg<p> 346b8e80941SmrgThose running on ArchLinux can use the AUR-maintained packages for some 347b8e80941Smrgof those, as they'll have the right values for your system: 348b8e80941Smrg</p> 349b8e80941Smrg<ul> 350b8e80941Smrg <li><a href="https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu">meson-cross-x86-linux-gnu</a></li> 351b8e80941Smrg <li><a href="https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu">meson-cross-aarch64-linux-gnu</a></li> 352b8e80941Smrg</ul> 353b8e80941Smrg 354b8e80941Smrg<p> 355b8e80941Smrg32-bit build on x86 linux: 356b8e80941Smrg</p> 357b8e80941Smrg<pre> 358b8e80941Smrg[binaries] 359b8e80941Smrgc = '/usr/bin/gcc' 360b8e80941Smrgcpp = '/usr/bin/g++' 361b8e80941Smrgar = '/usr/bin/gcc-ar' 362b8e80941Smrgstrip = '/usr/bin/strip' 363b8e80941Smrgpkgconfig = '/usr/bin/pkg-config-32' 364b8e80941Smrgllvm-config = '/usr/bin/llvm-config32' 365b8e80941Smrg 366b8e80941Smrg[properties] 367b8e80941Smrgc_args = ['-m32'] 368b8e80941Smrgc_link_args = ['-m32'] 369b8e80941Smrgcpp_args = ['-m32'] 370b8e80941Smrgcpp_link_args = ['-m32'] 371b8e80941Smrg 372b8e80941Smrg[host_machine] 373b8e80941Smrgsystem = 'linux' 374b8e80941Smrgcpu_family = 'x86' 375b8e80941Smrgcpu = 'i686' 376b8e80941Smrgendian = 'little' 377b8e80941Smrg</pre> 378b8e80941Smrg 379b8e80941Smrg<p> 380b8e80941Smrg64-bit build on ARM linux: 381b8e80941Smrg</p> 382b8e80941Smrg<pre> 383b8e80941Smrg[binaries] 384b8e80941Smrgc = '/usr/bin/aarch64-linux-gnu-gcc' 385b8e80941Smrgcpp = '/usr/bin/aarch64-linux-gnu-g++' 386b8e80941Smrgar = '/usr/bin/aarch64-linux-gnu-gcc-ar' 387b8e80941Smrgstrip = '/usr/bin/aarch64-linux-gnu-strip' 388b8e80941Smrgpkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config' 389b8e80941Smrgexe_wrapper = '/usr/bin/qemu-aarch64-static' 390b8e80941Smrg 391b8e80941Smrg[host_machine] 392b8e80941Smrgsystem = 'linux' 393b8e80941Smrgcpu_family = 'aarch64' 394b8e80941Smrgcpu = 'aarch64' 395b8e80941Smrgendian = 'little' 396b8e80941Smrg</pre> 397b8e80941Smrg 398b8e80941Smrg<p> 399b8e80941Smrg64-bit build on x86 windows: 400b8e80941Smrg</p> 401b8e80941Smrg<pre> 402b8e80941Smrg[binaries] 403b8e80941Smrgc = '/usr/bin/x86_64-w64-mingw32-gcc' 404b8e80941Smrgcpp = '/usr/bin/x86_64-w64-mingw32-g++' 405b8e80941Smrgar = '/usr/bin/x86_64-w64-mingw32-ar' 406b8e80941Smrgstrip = '/usr/bin/x86_64-w64-mingw32-strip' 407b8e80941Smrgpkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config' 408b8e80941Smrgexe_wrapper = 'wine' 409b8e80941Smrg 410b8e80941Smrg[host_machine] 411b8e80941Smrgsystem = 'windows' 412b8e80941Smrgcpu_family = 'x86_64' 413b8e80941Smrgcpu = 'i686' 414b8e80941Smrgendian = 'little' 415b8e80941Smrg</pre> 416b8e80941Smrg 417b8e80941Smrg</div> 418b8e80941Smrg</body> 419b8e80941Smrg</html> 420