| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html lang="en"> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=utf-8"> |
| <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> |
| </div> |
| |
| <iframe src="contents.html"></iframe> |
| <div class="content"> |
| |
| <h1>Compilation and Installation using Meson</h1> |
| |
| <ul> |
| <li><a href="#basic">Basic Usage</a></li> |
| <li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li> |
| </ul> |
| |
| <h2 id="basic">1. Basic Usage</h2> |
| |
| <p><strong>The Meson build system is generally considered stable and ready |
| for production</strong></p> |
| |
| <p>The meson build 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> |
| |
| Some older versions of meson do not check that they are too old and will error |
| out in odd ways. |
| </p> |
| |
| <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 |
| directory to put built and generated sources into. We'll call that directory |
| "build" for examples. |
| </p> |
| |
| <pre> |
| 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. |
| </p> |
| |
| <p> |
| Meson does not currently support listing options before configure a build |
| directory, 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 |
| <code>meson_options.txt</code> file at the root of the project. |
| </p> |
| |
| <pre> |
| 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>. |
| </p> |
| |
| <pre> |
| meson configure build/ -Dprefix=/tmp/install -Dglx=true |
| </pre> |
| |
| <p> |
| Note that options taking lists (such as <code>platforms</code>) are |
| <a href="http://mesonbuild.com/Build-options.html#using-build-options">a bit |
| more complicated</a>, but the simplest form compatible with Mesa options |
| is to use a comma to separate values (<code>-D platforms=drm,wayland</code>) |
| and brackets to represent an empty list (<code>-D platforms=[]</code>). |
| </p> |
| |
| <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. |
| </p> |
| |
| <pre> |
| 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> |
| </p> |
| |
| <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> |
| </p> |
| |
| <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. |
| </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> |
| <dd><p>Meson includes upstream logic to wrap llvm-config using its standard |
| dependency interface. |
| </p></dd> |
| |
| <dd><p> |
| As of meson 0.49.0 meson also has the concept of a |
| <a href="https://mesonbuild.com/Native-environments.html">"native file"</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: |
| |
| custom-llvm.ini |
| <pre> |
| [binaries] |
| llvm-config = '/usr/local/bin/llvm/llvm-config' |
| </pre> |
| |
| Then configure meson: |
| |
| <pre> |
| meson builddir/ --native-file custom-llvm.ini |
| </pre> |
| </p></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: |
| |
| cross-llvm.ini |
| <pre> |
| [binaries] |
| ... |
| llvm-config = '/usr/lib/llvm-config-32' |
| </pre> |
| |
| Then configure meson: |
| |
| <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> |
| |
| <dl> |
| <dt><code>PKG_CONFIG_PATH</code></dt> |
| <dd><p>The |
| <code>pkg-config</code> utility is a hard requirement for configuring and |
| building Mesa on Unix-like systems. It is used to search for external libraries |
| on the system. This environment variable is used to control the search path for |
| <code>pkg-config</code>. For instance, setting |
| <code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package |
| metadata in <code>/usr/X11R6</code> before the standard directories.</p> |
| </dd> |
| </dl> |
| |
| <p> |
| One of the oddities of meson is that some options are different when passed to |
| the <code>meson</code> than to <code>meson configure</code>. These options are |
| passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson |
| configure</code>. Mesa defined options are always passed as -Doption=foo. |
| </p> |
| |
| <p>For those coming from autotools be aware of the following:</p> |
| |
| <dl> |
| <dt><code>--buildtype/-Dbuildtype</code></dt> |
| <dd><p>This option will set the compiler debug/optimisation levels to aid |
| debugging the Mesa libraries.</p> |
| |
| <p>Note that in meson this defaults to <code>debugoptimized</code>, and |
| not setting it to <code>release</code> will yield non-optimal |
| performance and binary size. Not using <code>debug</code> may interfere |
| with debugging as some code and validation will be optimized away. |
| </p> |
| |
| <p> For those wishing to pass their own optimization flags, use the <code>plain</code> |
| 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 |
| is unrelated to the <code>buildtype</code>; setting the latter to |
| <code>release</code> will not turn off assertions. |
| </p> |
| </dd> |
| </dl> |
| |
| <h2 id="cross-compilation">2. 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 |
| settings in a file and passing this file to <code>meson</code> or |
| <code>meson configure</code> with the <code>--cross-file</code> |
| parameter.</p> |
| |
| <p>This file can live at any location, but you can use the bare filename |
| (without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or |
| ~/.local/share/meson/cross</p> |
| |
| <p>Below are a few example of cross files, but keep in mind that you |
| 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: |
| <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: |
| <pre> |
| [binaries] |
| c = '/usr/bin/gcc' |
| cpp = '/usr/bin/g++' |
| ar = '/usr/bin/gcc-ar' |
| strip = '/usr/bin/strip' |
| pkgconfig = '/usr/bin/pkg-config-32' |
| llvm-config = '/usr/bin/llvm-config32' |
| |
| [properties] |
| c_args = ['-m32'] |
| c_link_args = ['-m32'] |
| cpp_args = ['-m32'] |
| cpp_link_args = ['-m32'] |
| |
| [host_machine] |
| system = 'linux' |
| cpu_family = 'x86' |
| cpu = 'i686' |
| endian = 'little' |
| </pre> |
| </p> |
| |
| <p> |
| 64-bit build on ARM linux: |
| <pre> |
| [binaries] |
| c = '/usr/bin/aarch64-linux-gnu-gcc' |
| cpp = '/usr/bin/aarch64-linux-gnu-g++' |
| ar = '/usr/bin/aarch64-linux-gnu-gcc-ar' |
| strip = '/usr/bin/aarch64-linux-gnu-strip' |
| pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config' |
| exe_wrapper = '/usr/bin/qemu-aarch64-static' |
| |
| [host_machine] |
| system = 'linux' |
| cpu_family = 'aarch64' |
| cpu = 'aarch64' |
| endian = 'little' |
| </pre> |
| </p> |
| |
| <p> |
| 64-bit build on x86 windows: |
| <pre> |
| [binaries] |
| c = '/usr/bin/x86_64-w64-mingw32-gcc' |
| cpp = '/usr/bin/x86_64-w64-mingw32-g++' |
| ar = '/usr/bin/x86_64-w64-mingw32-ar' |
| strip = '/usr/bin/x86_64-w64-mingw32-strip' |
| pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config' |
| exe_wrapper = 'wine' |
| |
| [host_machine] |
| system = 'windows' |
| cpu_family = 'x86_64' |
| cpu = 'i686' |
| endian = 'little' |
| </pre> |
| </p> |
| |
| </div> |
| </body> |
| </html> |