Compilation and Installation using Meson

Compilation and Installation Using Meson

Introduction

1. Introduction

For general information about Meson see the -Meson website.

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

The Meson build of Mesa is tested on Linux, macOS, Cygwin and Haiku, FreeBSD, +

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.

Unix-like OSes

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

@@ -43,9 +47,7 @@ or
  sudo dnf install meson   # Fedora
 
-
-Mesa requires Meson >= 0.45.0 to build.
-
+

 Some older versions of meson do not check that they are too old and will error
 out in odd ways.
 
@@ -55,14 +57,37 @@ 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.
+backend on all operating systems.
 
 
 
@@ -70,14 +95,12 @@ 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" here.
 It's recommended to create a
-
+
 separate build directory for each configuration you might want to use.
 
 
 
 
-
-
 Basic configuration is done with:
 
 @@ -103,7 +126,8 @@ 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.
 
 
 
@@ -120,7 +144,7 @@ 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=[]).
@@ -146,7 +170,7 @@ ninja -C build/ install
 
 
 
-Note: autotools automatically updates translation files (used by the DRI
+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:
 
@@ -154,12 +178,32 @@ Meson does not do this.  Instead, you will need do this:
 ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo

3. Advanced Usage

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

Installation Location

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. @@ -169,113 +213,208 @@ 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 DESTDIR for installs. +

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 +

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

+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 does not allow changing compiler in a configured builddir, you will need +

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

Meson also honors DESTDIR for installs

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 @@ -300,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 @@ -330,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'
@@ -359,10 +497,10 @@ cpu_family = 'x86'
 cpu = 'i686'
 endian = 'little'

64-bit build on ARM linux: +

 [binaries]
 c = '/usr/bin/aarch64-linux-gnu-gcc'
@@ -378,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'
@@ -397,7 +535,6 @@ cpu_family = 'x86_64'
 cpu = 'i686'
 endian = 'little'

The Mesa 3D Graphics Library

Compilation and Installation using Meson

Compilation and Installation Using Meson

1. Introduction

Unix-like OSes

Windows

2. Basic Usage

3. Advanced Usage

Windows specific instructions

3. Advanced Usage

Installation Location

Compiler Options

Compiler Specification

LLVM

PKG_CONFIG_PATH

Options

`PKG_CONFIG_PATH`