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.52.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,7 @@ 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.
 
 
@@ -121,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=[]).
@@ -155,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.
@@ -182,10 +225,8 @@ to run/test the driver.
 

 Meson also honors DESTDIR for installs.
 
-
 
-Compiler 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.
@@ -194,19 +235,16 @@ in using them.
 -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
-
+Compiler Specification
 
 Meson supports the standard CC and CXX environment variables for
 changing the default compiler.  Note that Meson does not allow
@@ -227,76 +265,156 @@ 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.
 
-
 
-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
@@ -321,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
@@ -351,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:
+
 
   meson-cross-x86-linux-gnu
   meson-cross-aarch64-linux-gnu
 
-
 
 
 32-bit build on x86 linux:
+
  [binaries]
 c = '/usr/bin/gcc'
@@ -380,10 +497,10 @@ cpu_family = 'x86'
 cpu = 'i686'
 endian = 'little'
 
-
 
 
 64-bit build on ARM linux:
+
  [binaries]
 c = '/usr/bin/aarch64-linux-gnu-gcc'
@@ -399,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'
@@ -418,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
