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 | |
| 19 | <h2 id="basic">1. Basic Usage</h2> |
| 20 | |
| 21 | <p><strong>The Meson build system for Mesa is still under active development, |
| 22 | and should not be used in production environments.</strong></p> |
| 23 | |
| 24 | <p>The meson build is currently only tested on linux, and is known to not work |
| 25 | on macOS, Windows, and haiku. This will be fixed.</p> |
| 26 | |
| 27 | <p> |
| 28 | The meson program is used to configure the source directory and generates |
| 29 | either a ninja build file or Visual Studio® build files. The latter must |
| 30 | be enabled via the --backend switch, as ninja is the default backend on all |
| 31 | operating systems. Meson only supports out-of-tree builds, and must be passed a |
| 32 | directory to put built and generated sources into. We'll call that directory |
| 33 | "build" for examples. |
| 34 | </p> |
| 35 | |
| 36 | <pre> |
| 37 | meson build/ |
| 38 | </pre> |
| 39 | |
| 40 | <p> |
| 41 | To see a description of your options you can run <code>meson configure</code> |
| 42 | along with a build directory to view the selected options for. This will show |
| 43 | your meson global arguments and project arguments, along with their defaults |
| 44 | and your local settings. |
| 45 | |
| 46 | Moes does not currently support listing options before configure a build |
| 47 | directory, but this feature is being discussed upstream. |
| 48 | </p> |
| 49 | |
| 50 | <pre> |
| 51 | meson configure build/ |
| 52 | </pre> |
| 53 | |
| 54 | <p> |
| 55 | With additional arguments <code>meson configure</code> is used to change |
| 56 | options on already configured build directory. All options passed to this |
| 57 | command are in the form -D "command"="value". |
| 58 | </p> |
| 59 | |
| 60 | <pre> |
| 61 | meson configure build/ -Dprefix=/tmp/install -Dglx=true |
| 62 | </pre> |
| 63 | |
| 64 | <p> |
| 65 | Once you've run the initial <code>meson</code> command successfully you can use |
| 66 | your configured backend to build the project. With ninja, the -C option can be |
| 67 | be used to point at a directory to build. |
| 68 | </p> |
| 69 | |
| 70 | <pre> |
| 71 | ninja -C build/ |
| 72 | </pre> |
| 73 | |
| 74 | <p> |
| 75 | Without arguments, it will produce libGL.so and/or several other libraries |
| 76 | depending on the options you have chosen. Later, if you want to rebuild for a |
| 77 | different configuration, you should run <code>ninja clean</code> before |
| 78 | changing the configuration, or create a new out of tree build directory for |
| 79 | each configuration you want to build. |
| 80 | |
| 81 | http://mesonbuild.com/Using-multiple-build-directories.html |
| 82 | </p> |
| 83 | |
| 84 | <dt><code>Environment Variables</code></dt> |
| 85 | <dd><p>Meson supports the standard CC and CXX envrionment variables for |
| 86 | changing the default compiler, and CFLAGS, CXXFLAGS, and LDFLAGS for setting |
| 87 | options to the compiler and linker. |
| 88 | |
| 89 | The default compilers depends on your operating system. Meson supports most of |
| 90 | the popular compilers, a complete list is available |
| 91 | <a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>. |
| 92 | |
| 93 | These arguments are consumed and stored by meson when it is initialized or |
| 94 | re-initialized. Therefore passing them to meson configure will not do anything, |
| 95 | and passing them to ninja will only do something if ninja decides to |
| 96 | re-initialze meson, for example, if a meson.build file has been changed. |
| 97 | Changing these variables will not cause all targets to be rebuilt, so running |
| 98 | ninja clean is recomended when changing CFLAGS or CXXFLAGS. meson will never |
| 99 | change compiler in a configured build directory. |
| 100 | </p> |
| 101 | |
| 102 | <pre> |
| 103 | CC=clang CXX=clang++ meson build-clang |
| 104 | ninja -C build-clang |
| 105 | ninja -C build-clang clean |
| 106 | touch meson.build |
| 107 | CFLAGS=-Wno-typedef-redefinition ninja -C build-clang |
| 108 | </pre> |
| 109 | |
| 110 | <p>Meson also honors DESTDIR for installs</p> |
| 111 | </dd> |
| 112 | |
| 113 | |
| 114 | <dt><code>LLVM</code></dt> |
| 115 | <dd><p>Meson includes upstream logic to wrap llvm-config using it's standard |
| 116 | dependncy interface. It will search $PATH (or %PATH% on windows) for |
| 117 | llvm-config, so using an LLVM from a non-standard path is as easy as |
| 118 | <code>PATH=/path/with/llvm-config:$PATH meson build</code>. |
| 119 | </p></dd> |
| 120 | </dl> |
| 121 | |
| 122 | <dt><code>PKG_CONFIG_PATH</code></dt> |
| 123 | <dd><p>The |
| 124 | <code>pkg-config</code> utility is a hard requirement for configuring and |
| 125 | building Mesa on Linux and *BSD. It is used to search for external libraries |
| 126 | on the system. This environment variable is used to control the search |
| 127 | path for <code>pkg-config</code>. For instance, setting |
| 128 | <code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for |
| 129 | package metadata in <code>/usr/X11R6</code> before the standard |
| 130 | directories.</p> |
| 131 | </dd> |
| 132 | </dl> |
| 133 | |
| 134 | <p> |
| 135 | One of the oddities of meson is that some options are different when passed to |
| 136 | the <code>meson</code> than to <code>meson configure</code>. These options are |
| 137 | passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson |
| 138 | configure</code>. Mesa defined options are always passed as -Doption=foo. |
| 139 | <p> |
| 140 | |
| 141 | <p>For those coming from autotools be aware of the following:</p> |
| 142 | |
| 143 | <dl> |
| 144 | <dt><code>--buildtype/-Dbuildtype</code></dt> |
| 145 | <dd><p>This option will set the compiler debug/optimisation levels to aid |
| 146 | debugging the Mesa libraries.</p> |
| 147 | |
| 148 | <p>Note that in meson this defaults to "debugoptimized", and not setting it to |
| 149 | "release" will yield non-optimal performance and binary size. Not using "debug" |
| 150 | may interfer with debbugging as some code and validation will be optimized |
| 151 | away. |
| 152 | </p> |
| 153 | |
| 154 | <p> For those wishing to pass their own -O option, use the "plain" buildtype, |
| 155 | which cuases meson to inject no additional compiler arguments, only those in |
| 156 | the C/CXXFLAGS and those that mesa itself defines.</p> |
| 157 | </dd> |
| 158 | </dl> |
| 159 | |
| 160 | <dl> |
| 161 | <dt><code>-Db_ndebug</code></dt> |
| 162 | <dd><p>This option controls assertions in meson projects. When set to false |
| 163 | (the default) assertions are enabled, when set to true they are disabled. This |
| 164 | is unrelated to the <code>buildtype</code>; setting the latter to |
| 165 | <code>release</code> will not turn off assertions. |
| 166 | </p> |
| 167 | </dd> |
| 168 | </dl> |