docs/meson.html

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