Compilation and Installation using Meson

Compilation and Installation Using Meson

Introduction
Basic Usage
Advanced Usage
Cross-compilation and 32-bit builds

1. Basic Usage

1. Introduction

The Meson build system is generally considered stable and ready -for production

For general information about Meson see the +Meson website.

The meson build is tested on Linux, macOS, Cygwin and Haiku, FreeBSD, +

Mesa's Meson build system is generally considered stable and ready +for production.

+ +

Mesa requires Meson >= 0.46.0 to build. + +

The Meson build of Mesa is tested on Linux, macOS, Windows, Cygwin, Haiku, FreeBSD, DragonflyBSD, NetBSD, and should work on OpenBSD.

Mesa requires Meson >= 0.45.0 to build. +

Unix-like OSes

If Meson is not already installed on your system, you can typically +install it with your package installer. For example:

+sudo apt-get install meson   # Ubuntu
+

+or +

+sudo dnf install meson   # Fedora
+

Some older versions of meson do not check that they are too old and will error out in odd ways.

You'll also need Ninja. +If it's not already installed, use apt-get or dnf to install +the ninja-build package. +

+ +

Windows

+ +

+You will need to install python3 and meson as a module using pip. This is +because we use python for generating code, and rely on external modules +(mako). You also need pkg-config (a hard dependency of meson), flex, and bison. + +The easiest way to install everything you need is with chocolatey. +

+choco install python3 winflexbison pkgconfiglite
+

You can even use chocolatey to install mingw and ninja (ninja can be used with MSVC as well)

+choco install ninja mingw
+

Then install meson using pip

+py -3 -m pip install meson mako
+

+ +You may need to add the python3 scripts directory to your path for meson. + +

2. Basic Usage

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 --backend 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 --backend 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. +"build" here. +It's recommended to create a + +separate build directory for each configuration you might want to use.

+ + +

Basic configuration is done with:

-    meson build/
+meson build/

-To see a description of your options you can run meson configure -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).

-Meson does not currently support listing options before configure a build -directory, but this feature is being discussed upstream. +To review the options which Meson chose, run: +

+meson configure build/
+

+ +

+Meson does not currently support listing configuration options before +running "meson build/" but this feature is being discussed upstream. For now, we have a bin/meson-options.py script that prints the options for you. If that script doesn't work for some reason, you can always look in the -meson_options.txt file at the root of the project. + +meson_options.txt file at the root of the project.

-    meson configure build/
-

-With additional arguments meson configure is used to change -options on already configured build directory. All options passed to this -command are in the form -D "command"="value". +With additional arguments meson configure can be used to change +options for a previously configured build directory. +All options passed to this command are in the form +-D "option"="value". +For example:

-    meson configure build/ -Dprefix=/tmp/install -Dglx=true
+meson configure build/ -Dprefix=/tmp/install -Dglx=true

Note that options taking lists (such as platforms) are -a bit +a bit more complicated, but the simplest form compatible with Mesa options is to use a comma to separate values (-D platforms=drm,wayland) and brackets to represent an empty list (-D platforms=[]). @@ -88,128 +152,269 @@ and brackets to represent an empty list (-D platforms=[]).

Once you've run the initial meson 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:

-    ninja -C build/
+ninja -C build/

-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 ninja clean before -changing the configuration, or create a new out of tree build directory for -each configuration you want to build -as -recommended in the documentation +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:

+ninja -C build/ install
+

-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: -ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo +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:

+ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
+

Environment Variables

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 -D${lang}_args and --D${lang}_link_args instead. Among the benefits of these options -is that they are guaranteed to persist across rebuilds and reconfigurations. +

Windows specific instructions

-Meson does not allow changing compiler in a configured builddir, you will need -to create a new build dir for a different compiler. +

+On windows you have a couple of choices for compilers. If you installed mingw +with chocolatey and want to use ninja you should be able to open any shell +and follow the instructions above. If you want to you MSVC, clang-cl, or ICL +(the Intel Compiler), read on. +

+Both ICL and MSVC come with shell environments, the easiest way to use meson +with these it to open a shell. For clang-cl you will need to open an MSVC +shell, and then override the compilers, either using a native file, or +with the CC and CXX environment variables. +

+All of these compilers are tested and work with ninja, but if you want visual +studio integration or you just like msbuild, passing +--backend=vs to meson will generate a visual studio solution. If +you want to use ICL or clang-cl with the vsbackend you will need meson 0.52.0 +or greater. Older versions always use the microsoft compiler.

3. Advanced Usage

+ +

Installation Location

+Meson default to installing libGL.so in your system's main lib/ directory +and DRI drivers to a dri/ subdirectory. +

+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: +

-    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 --prefix="${PWD}/build/install" build/

+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. +

+Meson also honors DESTDIR for installs. +

Compiler Options

Meson supports the common CFLAGS, CXXFLAGS, etc. environment +variables but their use is discouraged because of the many caveats +in using them. +

Instead, it is recomended to use -D${lang}_args and +-D${lang}_link_args. Among the benefits of these options +is that they are guaranteed to persist across rebuilds and reconfigurations. +

-The default compilers depends on your operating system. Meson supports most of -the popular compilers, a complete list is available -here. +This example sets -fmax-errors for compiling C sources and -DMAGIC=123 +for C++ sources:

+meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123
+

Meson also honors DESTDIR for installs

Compiler Specification

+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. +

+This is an example of specifying the clang compilers and cleaning +the build directory before reconfiguring with an extra C option: +

+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
+

+The default compilers depends on your operating system. Meson supports most of +the popular compilers, a complete list is available +here. +

LLVM

Meson includes upstream logic to wrap llvm-config using its standard +

LLVM

Meson includes upstream logic to wrap llvm-config using its standard dependency interface. -

+As of meson 0.51.0 meson can use cmake to find llvm (the cmake finder +was added in meson 0.49.0, but LLVM cannot be found until 0.51) Due to the +way LLVM implements its cmake finder it will only find static libraries, it +will never find libllvm.so. + +There is also a -Dcmake_module_path option in this meson version, +which points to the root of an alternative installation (the prefix). For +example: +

+meson builddir -Dcmake_module_path=/home/user/mycmake/prefix
+

As of meson 0.49.0 meson also has the concept of a "native file", 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

-    [binaries]
-    llvm-config = '/usr/local/bin/llvm/llvm-config'
+[binaries]
+llvm-config = '/usr/local/bin/llvm/llvm-config'

Then configure meson:

-    meson builddir/ --native-file custom-llvm.ini
+meson builddir/ --native-file custom-llvm.ini

+Meson < 0.49 doesn't support native files, so to specify a custom +llvm-config you need to modify your $PATH (or +%PATH% on windows), which will be searched for +llvm-config, llvm-config$version, +and llvm-config-$version: +

+PATH=/path/to/folder/with/llvm-config:$PATH meson build
+

+ +

For selecting llvm-config for cross compiling a "cross file" should be used. It uses the same format as the native file above: +

-cross-llvm.ini +

cross-llvm.ini

-    [binaries]
-    ...
-    llvm-config = '/usr/lib/llvm-config-32'
+[binaries]
+...
+llvm-config = '/usr/lib/llvm-config-32'
+cmake = '/usr/bin/cmake-for-my-arch'

-Then configure meson: +

Obviously, only cmake or llvm-config is required.

Then configure meson:

-    meson builddir/ --cross-file cross-llvm.ini
+meson builddir/ --cross-file cross-llvm.ini

See the Cross Compilation section for more information. -

-For older versions of meson $PATH (or %PATH% 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: PATH=/path/with/llvm-config:$PATH meson build. -

PKG_CONFIG_PATH

The +

On windows (and in other cases), using llvm-config or cmake may be +either undesirable or impossible. Meson's solution for this is a +wrap, in +this case a "binary wrap". Follow the steps below:

Install the binaries and headers into the $mesa_src/subprojects/llvm
Add a meson build.build file to that directory (more on that later)

+ +

The wrap file must define the following:

dep_llvm: a declare_dependency() object with include_directories, dependencies, and version set)

+ +

It may also define:

irbuilder_h: a files() object pointing to llvm/IR/IRBuilder.h (this is requred for SWR)
has_rtti: a bool that declares whether LLVM was built with RTTI. Defaults to true

+ +

such a meson.build file might look like:

+project('llvm', ['cpp'])
+
+cpp = meson.get_compiler('cpp')
+
+_deps = []
+_search = join_paths(meson.current_source_dir(), 'lib')
+foreach d : ['libLLVMCodeGen', 'libLLVMScalarOpts', 'libLLVMAnalysis',
+             'libLLVMTransformUtils', 'libLLVMCore', 'libLLVMX86CodeGen',
+             'libLLVMSelectionDAG', 'libLLVMipo', 'libLLVMAsmPrinter',
+             'libLLVMInstCombine', 'libLLVMInstrumentation', 'libLLVMMC',
+             'libLLVMGlobalISel', 'libLLVMObjectYAML', 'libLLVMDebugInfoPDB',
+             'libLLVMVectorize', 'libLLVMPasses', 'libLLVMSupport',
+             'libLLVMLTO', 'libLLVMObject', 'libLLVMDebugInfoCodeView',
+             'libLLVMDebugInfoDWARF', 'libLLVMOrcJIT', 'libLLVMProfileData',
+             'libLLVMObjCARCOpts', 'libLLVMBitReader', 'libLLVMCoroutines',
+             'libLLVMBitWriter', 'libLLVMRuntimeDyld', 'libLLVMMIRParser',
+             'libLLVMX86Desc', 'libLLVMAsmParser', 'libLLVMTableGen',
+             'libLLVMFuzzMutate', 'libLLVMLinker', 'libLLVMMCParser',
+             'libLLVMExecutionEngine', 'libLLVMCoverage', 'libLLVMInterpreter',
+             'libLLVMTarget', 'libLLVMX86AsmParser', 'libLLVMSymbolize',
+             'libLLVMDebugInfoMSF', 'libLLVMMCJIT', 'libLLVMXRay',
+             'libLLVMX86AsmPrinter', 'libLLVMX86Disassembler',
+             'libLLVMMCDisassembler', 'libLLVMOption', 'libLLVMIRReader',
+             'libLLVMLibDriver', 'libLLVMDlltoolDriver', 'libLLVMDemangle',
+             'libLLVMBinaryFormat', 'libLLVMLineEditor',
+             'libLLVMWindowsManifest', 'libLLVMX86Info', 'libLLVMX86Utils']
+  _deps += cpp.find_library(d, dirs : _search)
+endforeach
+
+dep_llvm = declare_dependency(
+  include_directories : include_directories('include'),
+  dependencies : _deps,
+  version : '6.0.0',
+)
+
+has_rtti = false
+irbuilder_h = files('include/llvm/IR/IRBuilder.h')
+

+ +

It is very important that version is defined and is accurate, if it is not, +workarounds for the wrong version of LLVM might be used resulting in build +failures.

+ +

`PKG_CONFIG_PATH`

The pkg-config 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 pkg-config. For instance, setting PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig will search for package metadata in /usr/X11R6 before the standard directories.

Options

One of the oddities of meson is that some options are different when passed to the meson than to meson configure. These options are @@ -234,9 +439,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.

- -

-Db_ndebug: This option controls assertions in meson projects. When set to false (the default) assertions are enabled, when set to true they are disabled. This @@ -246,7 +449,7 @@ is unrelated to the buildtype; setting the latter to

2. Cross-compilation and 32-bit builds

4. Cross-compilation and 32-bit builds

Meson supports cross-compilation by specifying a number of binary paths and @@ -264,14 +467,15 @@ will likely have to alter them for your system.

Those running on ArchLinux can use the AUR-maintained packages for some of those, as they'll have the right values for your system: +

32-bit build on x86 linux: +

 [binaries]
 c = '/usr/bin/gcc'
@@ -293,10 +497,10 @@ cpu_family = 'x86'
 cpu = 'i686'
 endian = 'little'

64-bit build on ARM linux: +

 [binaries]
 c = '/usr/bin/aarch64-linux-gnu-gcc'
@@ -312,10 +516,10 @@ cpu_family = 'aarch64'
 cpu = 'aarch64'
 endian = 'little'

64-bit build on x86 windows: +

 [binaries]
 c = '/usr/bin/x86_64-w64-mingw32-gcc'
@@ -331,7 +535,6 @@ cpu_family = 'x86_64'
 cpu = 'i686'
 endian = 'little'

The Mesa 3D Graphics Library