Compilation and Installation using Meson
+Compilation and Installation Using Meson
-1. Basic Usage
+ -The Meson build system is generally considered stable and ready -for production
+1. Introduction
-The meson build is tested on Linux, macOS, Cygwin and Haiku, FreeBSD, +
For general information about Meson see the +Meson website.
+ +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.
-
-Meson does not currently support listing options before configure a build
-directory, but this feature is being discussed upstream.
+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).
+To review the options which Meson chose, run: +
- meson configure build/ +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".
+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.
+
+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=[]).
@@ -77,64 +152,274 @@ 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 ++ +
+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 ++ +
Windows specific instructions
+ ++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
+-
-
Environment Variables
-Meson supports the standard CC and CXX environment variables for -changing the default compiler, and CFLAGS, CXXFLAGS, and LDFLAGS for setting -options to the compiler and linker. +
- 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: +
++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
+DESTDIRfor 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}_argsand +-D${lang}_link_args. Among the benefits of these options +is that they are guaranteed to persist across rebuilds and reconfigurations. ++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 +
+
+
+
+ - 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. +here. +
+
-These arguments are consumed and stored by meson when it is initialized or
-re-initialized. Therefore passing them to meson configure will not do anything,
-and passing them to ninja will only do something if ninja decides to
-re-initialize meson, for example, if a meson.build file has been changed.
-Changing these variables will not cause all targets to be rebuilt, so running
-ninja clean is recommended when changing CFLAGS or CXXFLAGS. Meson will never
-change compiler in a configured build directory.
+ - 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- CC=clang CXX=clang++ meson build-clang - ninja -C build-clang - ninja -C build-clang clean - touch meson.build - CFLAGS=-Wno-typedef-redefinition ninja -C build-clang + [binaries] + llvm-config = '/usr/local/bin/llvm/llvm-config'
-Meson also honors
+Then configure meson: + +DESTDIRfor installs+ meson builddir/ --native-file custom-llvm.ini +
++Meson < 0.49 doesn't support native files, so to specify a custom +
+llvm-configyou need to modify your$PATH(or +%PATH%on windows), which will be searched for +llvm-config,llvm-config$version, +andllvm-config-$version: ++PATH=/path/to/folder/with/llvm-config:$PATH meson build +
+
-LLVM
-Meson includes upstream logic to wrap llvm-config using it's standard -dependency interface. It will search
$PATH(or%PATH%on windows) for -llvm-config, so using an LLVM from a non-standard path is as easy as -PATH=/path/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
++ [binaries] + ... + llvm-config = '/usr/lib/llvm-config-32' + cmake = '/usr/bin/cmake-for-my-arch' +
+ +Obviously, only cmake or llvm-config is required.
+ +Then configure meson:
++ meson builddir/ --cross-file cross-llvm.ini +
+ +See the Cross Compilation section for more information. +
+
+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: adeclare_dependency()object with include_directories, dependencies, and version set)
+
It may also define:
+-
+
irbuilder_h: afiles()object pointing to llvm/IR/IRBuilder.h (this is requred for SWR)
+ has_rtti: aboolthat 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.
+ +- Install the binaries and headers into the
PKG_CONFIG_PATHThe
pkg-configutility is a hard requirement for configuring and @@ -170,9 +455,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_ndebugThis option controls assertions in meson projects. When set to
false(the default) assertions are enabled, when set to true they are disabled. This @@ -182,6 +465,93 @@ is unrelated to thebuildtype; setting the latter to
4. Cross-compilation and 32-bit builds
+ +Meson supports
+cross-compilation by specifying a number of binary paths and
+settings in a file and passing this file to meson or
+meson configure with the --cross-file
+parameter.
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
+ +Below are a few example of cross files, but keep in mind that you +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' +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' ++ +
+64-bit build on ARM linux: +
++[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' ++ +
+64-bit build on x86 windows: +
++[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' ++