diff options
| author | Jonathan Gray <jsg@cvs.openbsd.org> | 2020-01-22 02:13:18 +0000 |
|---|---|---|
| committer | Jonathan Gray <jsg@cvs.openbsd.org> | 2020-01-22 02:13:18 +0000 |
| commit | fdcc03929065b5bf5dd93553db219ea3e05c8c34 (patch) | |
| tree | ca90dc8d9e89febdcd4160956c1b8ec098a4efc9 /lib/mesa/docs/meson.html | |
| parent | 3c9de4a7e13712b5696750bbd59a18c848742022 (diff) | |
Import Mesa 19.2.8
Diffstat (limited to 'lib/mesa/docs/meson.html')
| -rw-r--r-- | lib/mesa/docs/meson.html | 246 |
1 files changed, 167 insertions, 79 deletions
diff --git a/lib/mesa/docs/meson.html b/lib/mesa/docs/meson.html index ac941b840..d46741e67 100644 --- a/lib/mesa/docs/meson.html +++ b/lib/mesa/docs/meson.html @@ -2,78 +2,119 @@ <html lang="en"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> - <title>Compilation and Installation using Meson</title> + <title>Compilation and Installation Using Meson</title> <link rel="stylesheet" type="text/css" href="mesa.css"> </head> <body> <div class="header"> - <h1>The Mesa 3D Graphics Library</h1> + The Mesa 3D Graphics Library </div> <iframe src="contents.html"></iframe> <div class="content"> -<h1>Compilation and Installation using Meson</h1> +<h1>Compilation and Installation Using Meson</h1> <ul> + <li><a href="#intro">Introduction</a></li> <li><a href="#basic">Basic Usage</a></li> + <li><a href="#advanced">Advanced Usage</a></li> <li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li> </ul> -<h2 id="basic">1. Basic Usage</h2> +<h2 id="intro">1. Introduction</h2> -<p><strong>The Meson build system is generally considered stable and ready -for production</strong></p> +<p>For general information about Meson see the +<a href="http://mesonbuild.com/">Meson website</a>.</p> -<p>The meson build is tested on Linux, macOS, Cygwin and Haiku, FreeBSD, +<p><strong>Mesa's Meson build system is generally considered stable and ready +for production.</strong></p> + +<p>The Meson build of Mesa is tested on Linux, macOS, Cygwin and Haiku, FreeBSD, DragonflyBSD, NetBSD, and should work on OpenBSD.</p> -<p><strong>Mesa requires Meson >= 0.45.0 to build.</strong> +<p>If Meson is not already installed on your system, you can typically +install it with your package installer. For example:</p> +<pre> +sudo apt-get install meson # Ubuntu +</pre> +or +<pre> +sudo dnf install meson # Fedora +</pre> + +<p><strong>Mesa requires Meson >= 0.46.0 to build.</strong> Some older versions of meson do not check that they are too old and will error out in odd ways. </p> +<p>You'll also need <a href="https://ninja-build.org/">Ninja</a>. +If it's not already installed, use apt-get or dnf to install +the <em>ninja-build</em> package. +</p> + +<h2 id="basic">2. Basic Usage</h2> + <p> The meson program is used to configure the source directory and generates either a ninja build file or Visual Studio® build files. The latter must -be enabled via the <code>--backend</code> switch, as ninja is the default backend on all -operating systems. Meson only supports out-of-tree builds, and must be passed a +be enabled via the <code>--backend</code> switch, as ninja is the default +backend on all +operating systems. +</p> + +<p> +Meson only supports out-of-tree builds, and must be passed a directory to put built and generated sources into. We'll call that directory -"build" for examples. +"build" here. +It's recommended to create a +<a href="http://mesonbuild.com/Using-multiple-build-directories.html"> +separate build directory</a> for each configuration you might want to use. </p> + + +<p>Basic configuration is done with:</p> + <pre> - meson build/ +meson build/ </pre> <p> -To see a description of your options you can run <code>meson configure</code> -along with a build directory to view the selected options for. This will show -your meson global arguments and project arguments, along with their defaults -and your local settings. +This will create the build directory. +If any dependencies are missing, you can install them, or try to remove +the dependency with a Meson configuration option (see below). </p> <p> -Meson does not currently support listing options before configure a build -directory, but this feature is being discussed upstream. -For now, the only way to see what options exist is to look at the -<code>meson_options.txt</code> file at the root of the project. +To review the options which Meson chose, run: </p> - <pre> - meson configure build/ +meson configure build/ </pre> <p> -With additional arguments <code>meson configure</code> is used to change -options on already configured build directory. All options passed to this -command are in the form <code>-D "command"="value"</code>. +Meson does not currently support listing configuration options before +running "meson build/" but this feature is being discussed upstream. +For now, we have a <code>bin/meson-options.py</code> script that prints +the options for you. +If that script doesn't work for some reason, you can always look in the +<a href="https://gitlab.freedesktop.org/mesa/mesa/blob/master/meson_options.txt"> +meson_options.txt</a> file at the root of the project. +</p> + +<p> +With additional arguments <code>meson configure</code> can be used to change +options for a previously configured build directory. +All options passed to this command are in the form +<code>-D "option"="value"</code>. +For example: </p> <pre> - meson configure build/ -Dprefix=/tmp/install -Dglx=true +meson configure build/ -Dprefix=/tmp/install -Dglx=true </pre> <p> @@ -86,63 +127,108 @@ and brackets to represent an empty list (<code>-D platforms=[]</code>). <p> Once you've run the initial <code>meson</code> command successfully you can use -your configured backend to build the project. With ninja, the -C option can be -be used to point at a directory to build. +your configured backend to build the project in your build directory: </p> <pre> - ninja -C build/ +ninja -C build/ </pre> <p> -Without arguments, it will produce libGL.so and/or several other libraries -depending on the options you have chosen. Later, if you want to rebuild for a -different configuration, you should run <code>ninja clean</code> before -changing the configuration, or create a new out of tree build directory for -each configuration you want to build -<a href="http://mesonbuild.com/Using-multiple-build-directories.html">as -recommended in the documentation</a> +The next step is to install the Mesa libraries, drivers, etc. +This also finishes up some final steps of the build process (such as creating +symbolic links for drivers). To install: </p> +<pre> +ninja -C build/ install +</pre> + <p> -Autotools automatically updates translation files as part of the build process, -meson does not do this. Instead if you want translated drirc files you will need -to invoke non-default targets for ninja to update them: -<code>ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo</code> +Note: autotools automatically updated translation files (used by the DRI +configuration tool) as part of the build process, +Meson does not do this. Instead, you will need do this: </p> +<pre> +ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo +</pre> + +<h2 id="advanced">3. Advanced Usage</h2> <dl> -<dt><code>Environment Variables</code></dt> -<dd><p>Meson supports the standard CC and CXX environment variables for -changing the default compiler. Meson does support CFLAGS, CXXFLAGS, etc. But -their use is discouraged because of the many caveats in using them. Instead it -is recomended to use <code>-D${lang}_args</code> and -<code>-D${lang}_link_args</code> instead. Among the benefits of these options -is that they are guaranteed to persist across rebuilds and reconfigurations. -Meson does not allow changing compiler in a configured builddir, you will need -to create a new build dir for a different compiler. +<dt>Installation Location</dt> +<dd> +<p> +Meson default to installing libGL.so in your system's main lib/ directory +and DRI drivers to a dri/ subdirectory. +</p> +<p> +Developers will often want to install Mesa to a testing directory rather +than the system library directory. +This can be done with the --prefix option. For example: </p> +<pre> +meson --prefix="${PWD}/build/install" build/ +</pre> +<p> +will put the final libraries and drivers into the build/install/ +directory. +Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to that location +to run/test the driver. +</p> +<p> +Meson also honors <code>DESTDIR</code> for installs. +</p> +</dd> +<dt>Compiler Options</dt> +<dd> +<p>Meson supports the common CFLAGS, CXXFLAGS, etc. environment +variables but their use is discouraged because of the many caveats +in using them. +</p> +<p>Instead, it is recomended to use <code>-D${lang}_args</code> and +<code>-D${lang}_link_args</code>. Among the benefits of these options +is that they are guaranteed to persist across rebuilds and reconfigurations. +</p> +<p> +This example sets -fmax-errors for compiling C sources and -DMAGIC=123 +for C++ sources: +</p> <pre> - CC=clang CXX=clang++ meson build-clang - ninja -C build-clang - ninja -C build-clang clean - meson configure build -Dc_args="-Wno-typedef-redefinition" - ninja -C build-clang +meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123 </pre> +</dd> + +<dt>Compiler Specification</dt> +<dd> +<p> +Meson supports the standard CC and CXX environment variables for +changing the default compiler. Note that Meson does not allow +changing the compilers in a configured builddir so you will need +to create a new build dir for a different compiler. +</p> +<p> +This is an example of specifying the clang compilers and cleaning +the build directory before reconfiguring with an extra C option: +</p> +<pre> +CC=clang CXX=clang++ meson build-clang +ninja -C build-clang +ninja -C build-clang clean +meson configure build -Dc_args="-Wno-typedef-redefinition" +ninja -C build-clang +</pre> <p> The default compilers depends on your operating system. Meson supports most of the popular compilers, a complete list is available <a href="http://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>. </p> - -<p>Meson also honors <code>DESTDIR</code> for installs</p> </dd> - -<dt><code>LLVM</code></dt> +<dt>LLVM</dt> <dd><p>Meson includes upstream logic to wrap llvm-config using its standard dependency interface. </p></dd> @@ -153,6 +239,7 @@ As of meson 0.49.0 meson also has the concept of a these files provide information about the native build environment (as opposed to a cross build environment). They are ini formatted and can override where to find llvm-config: +</p> custom-llvm.ini <pre> @@ -165,38 +252,41 @@ Then configure meson: <pre> meson builddir/ --native-file custom-llvm.ini </pre> -</p></dd> +</dd> + +<dd><p> +Meson < 0.49 doesn't support native files, so to specify a custom +<code>llvm-config</code> you need to modify your <code>$PATH</code> (or +<code>%PATH%</code> on windows), which will be searched for +<code>llvm-config</code>, <code>llvm-config<i>$version</i></code>, +and <code>llvm-config-<i>$version</i></code>: +</p> +<pre> +PATH=/path/to/folder/with/llvm-config:$PATH meson build +</pre> +</dd> <dd><p> For selecting llvm-config for cross compiling a <a href="https://mesonbuild.com/Cross-compilation.html#defining-the-environment">"cross file"</a> should be used. It uses the same format as the native file above: +</p> -cross-llvm.ini +<p>cross-llvm.ini</p> <pre> [binaries] ... llvm-config = '/usr/lib/llvm-config-32' </pre> -Then configure meson: - +<p>Then configure meson:</p> <pre> meson builddir/ --cross-file cross-llvm.ini </pre> See the <a href="#cross-compilation">Cross Compilation</a> section for more information. -</dd></p> - -<dd><p> -For older versions of meson <code>$PATH</code> (or <code>%PATH%</code> on -windows) will be searched for llvm-config (and llvm-config$version and -llvm-config-$version), you can override this environment variable to control -the search: <code>PATH=/path/with/llvm-config:$PATH meson build</code>. -</dd></p> -</dl> +</dd> -<dl> <dt><code>PKG_CONFIG_PATH</code></dt> <dd><p>The <code>pkg-config</code> utility is a hard requirement for configuring and @@ -232,9 +322,7 @@ with debugging as some code and validation will be optimized away. buildtype, which causes meson to inject no additional compiler arguments, only those in the C/CXXFLAGS and those that mesa itself defines.</p> </dd> -</dl> -<dl> <dt><code>-Db_ndebug</code></dt> <dd><p>This option controls assertions in meson projects. When set to <code>false</code> (the default) assertions are enabled, when set to true they are disabled. This @@ -244,7 +332,7 @@ is unrelated to the <code>buildtype</code>; setting the latter to </dd> </dl> -<h2 id="cross-compilation">2. Cross-compilation and 32-bit builds</h2> +<h2 id="cross-compilation">4. Cross-compilation and 32-bit builds</h2> <p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports cross-compilation</a> by specifying a number of binary paths and @@ -262,14 +350,15 @@ will likely have to alter them for your system.</p> <p> Those running on ArchLinux can use the AUR-maintained packages for some of those, as they'll have the right values for your system: +</p> <ul> <li><a href="https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu">meson-cross-x86-linux-gnu</a></li> <li><a href="https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu">meson-cross-aarch64-linux-gnu</a></li> </ul> -</p> <p> 32-bit build on x86 linux: +</p> <pre> [binaries] c = '/usr/bin/gcc' @@ -291,10 +380,10 @@ cpu_family = 'x86' cpu = 'i686' endian = 'little' </pre> -</p> <p> 64-bit build on ARM linux: +</p> <pre> [binaries] c = '/usr/bin/aarch64-linux-gnu-gcc' @@ -310,10 +399,10 @@ cpu_family = 'aarch64' cpu = 'aarch64' endian = 'little' </pre> -</p> <p> 64-bit build on x86 windows: +</p> <pre> [binaries] c = '/usr/bin/x86_64-w64-mingw32-gcc' @@ -329,7 +418,6 @@ cpu_family = 'x86_64' cpu = 'i686' endian = 'little' </pre> -</p> </div> </body> |