Compilation and Installation Using Meson — The Mesa 3D Graphics Library latest documentation (2024)

Unix-like OSes¶

If Meson is not already installed on your system, you can typicallyinstall 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 willerror out in odd ways.

You’ll also need Ninja. If it’s notalready installed, use apt-get or dnf to install the ninja-buildpackage.

Windows¶

You will need to install Python 3 and Meson as a module using pip. Thisis because we use Python for generating code, and rely on externalmodules (Mako). You also need pkg-config (a hard dependency of Meson),Flex, and Bison. The easiest way to install everything you need is withChocolatey.

choco install python3 winflexbison pkgconfiglite

You can even use Chocolatey to install MinGW and Ninja (Ninja can beused 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 Python 3 scripts directory to your path forMeson.

Windows specific instructions¶

On Windows you have a couple of choices for compilers. If you installedMinGW with Chocolatey and want to use Ninja you should be able to openany 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 useMeson with these it to open a shell. For clang-cl you will need to openan MSVC shell, and then override the compilers, either using a nativefile, or with theCC and CXX environment variables.

All of these compilers are tested and work with Ninja, but if you wantVisual Studio integration or you just like msbuild, passing--backend=vs to Meson will generate a Visual Studio solution.

Installation Location¶

Meson default to installing libGL.so in your system’s mainlib/ directory and DRI drivers to a dri/ subdirectory.

Developers will often want to install Mesa to a testing directory ratherthan the system library directory. This can be done with the –prefixoption. 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 tothat location to run/test the driver.

Meson also honors DESTDIR for installs.

Compiler Options¶

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

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

This example sets -fmax-errors for compiling C sources and -DMAGIC=123for C++ sources:

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

Compiler Specification¶

Meson supports the standard CC and CXX environment variables forchanging the default compiler. Note that Meson does not allow changingthe compilers in a configured build directory so you will need to createa new build dir for a different compiler.

This is an example of specifying the Clang compilers and cleaning thebuild directory before reconfiguring with an extra C option:

CC=clang CXX=clang++ meson setup build-clangninja -C build-clangninja -C build-clang cleanmeson configure build -Dc_args="-Wno-typedef-redefinition"ninja -C build-clang

The default compilers depends on your operating system. Meson supportsmost of the popular compilers, a complete list is availablehere.

LLVM¶

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

Meson can use CMake to find LLVM. But due to the way LLVM implements itsCMake finder it will only find static libraries, it will never findlibllvm.so. There is also a -Dcmake_module_path option,which points to the root of an alternative installation (the prefix).For example:

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

As of Meson 0.49.0 Meson also has the concept of a “nativefile”, these filesprovide information about the native build environment (as opposed to across build environment). They are INI formatted and can override whereto find llvm-config:

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

Then configure Meson:

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

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

[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 setup builddir/ --cross-file cross-llvm.ini

See the Cross Compilation section for moreinformation.

On Windows (and in other cases), using llvm-config or CMake may beeither undesirable or impossible. Meson’s solution for this is awrap, inthis case a “binary wrap”. Follow the steps below:

• Install the binaries and headers into the$mesa_src/subprojects/llvm

• Add a meson.build file to that directory (more on that later)

The wrap file must define the following:

• dep_llvm: a declare_dependency() object withinclude_directories, dependencies, and version set)

It may also define:

• irbuilder_h: a files() object pointing to llvm/IR/IRBuilder.h

• has_rtti: a bool that declares whether LLVM was built withRTTI. 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)endforeachdep_llvm = declare_dependency( include_directories : include_directories('include'), dependencies : _deps, version : '6.0.0',)has_rtti = falseirbuilder_h = files('include/llvm/IR/IRBuilder.h')

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

PKG_CONFIG_PATH¶

The pkg-config utility is a hard requirement for configuring andbuilding Mesa on Unix-like systems. It is used to search for externallibraries on the system. This environment variable is used to controlthe search path for pkg-config. For instance, settingPKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig will search for packagemetadata in /usr/X11R6 before the standard directories.

Options¶

One of the oddities of Meson is that some options are different whenpassed to meson than to meson configure. These options arepassed as –option=foo to meson, but -Doption=foo tomeson configure. Mesa defined options are always passed as-Doption=foo.

For those coming from Autotools be aware of the following:

--buildtype/-Dbuildtype

This option will set the compiler debug/optimization levels to aiddebugging the Mesa libraries.

Note that in Meson this defaults to debugoptimized, and notsetting it to release will yield non-optimal performance andbinary size. Not using debug may interfere with debugging as somecode and validation will be optimized away.

For those wishing to pass their own optimization flags, use theplain buildtype, which causes Meson to inject no additionalcompiler arguments, only those in the C/CXXFLAGS and those that mesaitself defines.

-Db_ndebug

This option controls assertions in Meson projects. When set tofalse (the default) assertions are enabled, when set to true theyare disabled. This is unrelated to the buildtype; setting thelatter to release will not turn off assertions.