1 Compilation and Installation Using Meson
2 ========================================
7 For general information about Meson see the `Meson
8 website <https://mesonbuild.com/>`__.
10 **Mesa's Meson build system is generally considered stable and ready for
15 Mesa requires Meson >= 0.52.0 to build.
17 If your distribution doesn't have something recent enough in its
18 repositories, you can `try the methods suggested here
19 <https://mesonbuild.com/Getting-meson.html>`__ to install the
20 current version of Meson.
22 The Meson build of Mesa is tested on Linux, macOS, Windows, Cygwin,
23 Haiku, FreeBSD, DragonflyBSD, NetBSD, and should work on OpenBSD.
28 If Meson is not already installed on your system, you can typically
29 install it with your package installer. For example:
31 .. code-block:: console
33 sudo apt-get install meson # Ubuntu
37 .. code-block:: console
39 sudo dnf install meson # Fedora
41 Some older versions of meson do not check that they are too old and will
42 error out in odd ways.
44 You'll also need `Ninja <https://ninja-build.org/>`__. If it's not
45 already installed, use apt-get or dnf to install the *ninja-build*
51 You will need to install python3 and meson as a module using pip. This
52 is because we use python for generating code, and rely on external
53 modules (mako). You also need pkg-config (a hard dependency of meson),
54 flex, and bison. The easiest way to install everything you need is with
55 `chocolatey <https://chocolatey.org/>`__.
57 .. code-block:: console
59 choco install python3 winflexbison pkgconfiglite
61 You can even use chocolatey to install mingw and ninja (ninja can be
62 used with MSVC as well)
64 .. code-block:: console
66 choco install ninja mingw
68 Then install meson using pip
70 .. code-block:: console
72 py -3 -m pip install meson mako
74 You may need to add the python3 scripts directory to your path for
80 The meson program is used to configure the source directory and
81 generates either a ninja build file or Visual Studio® build files. The
82 latter must be enabled via the ``--backend`` switch, as ninja is the
83 default backend on all operating systems.
85 Meson only supports out-of-tree builds, and must be passed a directory
86 to put built and generated sources into. We'll call that directory
87 "build" here. It's recommended to create a `separate build
88 directory <https://mesonbuild.com/Using-multiple-build-directories.html>`__
89 for each configuration you might want to use.
91 Basic configuration is done with:
93 .. code-block:: console
97 This will create the build directory. If any dependencies are missing,
98 you can install them, or try to remove the dependency with a Meson
99 configuration option (see below).
101 To review the options which Meson chose, run:
103 .. code-block:: console
105 meson configure build/
107 Meson does not currently support listing configuration options before
108 running "meson build/" but this feature is being discussed upstream. For
109 now, we have a ``bin/meson-options.py`` script that prints the options
110 for you. If that script doesn't work for some reason, you can always
112 `meson_options.txt <https://gitlab.freedesktop.org/mesa/mesa/-/blob/master/meson_options.txt>`__
113 file at the root of the project.
115 With additional arguments ``meson configure`` can be used to change
116 options for a previously configured build directory. All options passed
117 to this command are in the form ``-D "option"="value"``. For example:
119 .. code-block:: console
121 meson configure build/ -Dprefix=/tmp/install -Dglx=true
123 Note that options taking lists (such as ``platforms``) are `a bit more
124 complicated <https://mesonbuild.com/Build-options.html#using-build-options>`__,
125 but the simplest form compatible with Mesa options is to use a comma to
126 separate values (``-D platforms=drm,wayland``) and brackets to represent
127 an empty list (``-D platforms=[]``).
129 Once you've run the initial ``meson`` command successfully you can use
130 your configured backend to build the project in your build directory:
132 .. code-block:: console
136 The next step is to install the Mesa libraries, drivers, etc. This also
137 finishes up some final steps of the build process (such as creating
138 symbolic links for drivers). To install:
140 .. code-block:: console
142 ninja -C build/ install
146 autotools automatically updated translation files (used by the DRI
147 configuration tool) as part of the build process, Meson does not do
148 this. Instead, you will need do this:
150 .. code-block:: console
152 ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
154 Windows specific instructions
155 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
157 On windows you have a couple of choices for compilers. If you installed
158 mingw with chocolatey and want to use ninja you should be able to open
159 any shell and follow the instructions above. If you want to you MSVC,
160 clang-cl, or ICL (the Intel Compiler), read on.
162 Both ICL and MSVC come with shell environments, the easiest way to use
163 meson with these it to open a shell. For clang-cl you will need to open
164 an MSVC shell, and then override the compilers, either using a `native
165 file <https://mesonbuild.com/Native-environments.html>`__, or with the
166 CC and CXX environment variables.
168 All of these compilers are tested and work with ninja, but if you want
169 visual studio integration or you just like msbuild, passing
170 ``--backend=vs`` to meson will generate a visual studio solution. If you
171 want to use ICL or clang-cl with the vsbackend you will need meson
172 0.52.0 or greater. Older versions always use the microsoft compiler.
177 Installation Location
178 ^^^^^^^^^^^^^^^^^^^^^
180 Meson default to installing libGL.so in your system's main lib/
181 directory and DRI drivers to a dri/ subdirectory.
183 Developers will often want to install Mesa to a testing directory rather
184 than the system library directory. This can be done with the --prefix
187 .. code-block:: console
189 meson --prefix="${PWD}/build/install" build/
191 will put the final libraries and drivers into the build/install/
192 directory. Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to
193 that location to run/test the driver.
195 Meson also honors ``DESTDIR`` for installs.
200 Meson supports the common CFLAGS, CXXFLAGS, etc. environment variables
201 but their use is discouraged because of the many caveats in using them.
203 Instead, it is recomended to use ``-D${lang}_args`` and
204 ``-D${lang}_link_args``. Among the benefits of these options is that
205 they are guaranteed to persist across rebuilds and reconfigurations.
207 This example sets -fmax-errors for compiling C sources and -DMAGIC=123
210 .. code-block:: console
212 meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123
214 Compiler Specification
215 ^^^^^^^^^^^^^^^^^^^^^^
217 Meson supports the standard CC and CXX environment variables for
218 changing the default compiler. Note that Meson does not allow changing
219 the compilers in a configured builddir so you will need to create a new
220 build dir for a different compiler.
222 This is an example of specifying the clang compilers and cleaning the
223 build directory before reconfiguring with an extra C option:
225 .. code-block:: console
227 CC=clang CXX=clang++ meson build-clang
229 ninja -C build-clang clean
230 meson configure build -Dc_args="-Wno-typedef-redefinition"
233 The default compilers depends on your operating system. Meson supports
234 most of the popular compilers, a complete list is available
235 `here <https://mesonbuild.com/Reference-tables.html#compiler-ids>`__.
240 Meson includes upstream logic to wrap llvm-config using its standard
241 dependency interface.
243 As of meson 0.51.0 meson can use cmake to find llvm (the cmake finder
244 was added in meson 0.49.0, but LLVM cannot be found until 0.51) Due to
245 the way LLVM implements its cmake finder it will only find static
246 libraries, it will never find libllvm.so. There is also a
247 ``-Dcmake_module_path`` option in this meson version, which points to
248 the root of an alternative installation (the prefix). For example:
250 .. code-block:: console
252 meson builddir -Dcmake_module_path=/home/user/mycmake/prefix
254 As of meson 0.49.0 meson also has the concept of a `"native
255 file" <https://mesonbuild.com/Native-environments.html>`__, these files
256 provide information about the native build environment (as opposed to a
257 cross build environment). They are ini formatted and can override where
265 llvm-config = '/usr/local/bin/llvm/llvm-config'
267 Then configure meson:
269 .. code-block:: console
271 meson builddir/ --native-file custom-llvm.ini
273 Meson < 0.49 doesn't support native files, so to specify a custom
274 ``llvm-config`` you need to modify your ``$PATH`` (or ``%PATH%`` on
275 windows), which will be searched for ``llvm-config``,
276 ``llvm-config$version``, and ``llvm-config-$version``:
278 .. code-block:: console
280 PATH=/path/to/folder/with/llvm-config:$PATH meson build
282 For selecting llvm-config for cross compiling a `"cross
283 file" <https://mesonbuild.com/Cross-compilation.html#defining-the-environment>`__
284 should be used. It uses the same format as the native file above:
292 llvm-config = '/usr/lib/llvm-config-32'
293 cmake = '/usr/bin/cmake-for-my-arch'
295 Obviously, only cmake or llvm-config is required.
297 Then configure meson:
299 .. code-block:: console
301 meson builddir/ --cross-file cross-llvm.ini
303 See the `Cross Compilation <#cross-compilation>`__ section for more
306 On windows (and in other cases), using llvm-config or cmake may be
307 either undesirable or impossible. Meson's solution for this is a
308 `wrap <https://mesonbuild.com/Wrap-dependency-system-manual.html>`__, in
309 this case a "binary wrap". Follow the steps below:
311 - Install the binaries and headers into the
312 ``$mesa_src/subprojects/llvm``
313 - Add a meson build.build file to that directory (more on that later)
315 The wrap file must define the following:
317 - ``dep_llvm``: a ``declare_dependency()`` object with
318 include_directories, dependencies, and version set)
322 - ``irbuilder_h``: a ``files()`` object pointing to llvm/IR/IRBuilder.h
323 (this is requred for SWR)
324 - ``has_rtti``: a ``bool`` that declares whether LLVM was built with
325 RTTI. Defaults to true
327 such a meson.build file might look like:
331 project('llvm', ['cpp'])
333 cpp = meson.get_compiler('cpp')
336 _search = join_paths(meson.current_source_dir(), 'lib')
337 foreach d : ['libLLVMCodeGen', 'libLLVMScalarOpts', 'libLLVMAnalysis',
338 'libLLVMTransformUtils', 'libLLVMCore', 'libLLVMX86CodeGen',
339 'libLLVMSelectionDAG', 'libLLVMipo', 'libLLVMAsmPrinter',
340 'libLLVMInstCombine', 'libLLVMInstrumentation', 'libLLVMMC',
341 'libLLVMGlobalISel', 'libLLVMObjectYAML', 'libLLVMDebugInfoPDB',
342 'libLLVMVectorize', 'libLLVMPasses', 'libLLVMSupport',
343 'libLLVMLTO', 'libLLVMObject', 'libLLVMDebugInfoCodeView',
344 'libLLVMDebugInfoDWARF', 'libLLVMOrcJIT', 'libLLVMProfileData',
345 'libLLVMObjCARCOpts', 'libLLVMBitReader', 'libLLVMCoroutines',
346 'libLLVMBitWriter', 'libLLVMRuntimeDyld', 'libLLVMMIRParser',
347 'libLLVMX86Desc', 'libLLVMAsmParser', 'libLLVMTableGen',
348 'libLLVMFuzzMutate', 'libLLVMLinker', 'libLLVMMCParser',
349 'libLLVMExecutionEngine', 'libLLVMCoverage', 'libLLVMInterpreter',
350 'libLLVMTarget', 'libLLVMX86AsmParser', 'libLLVMSymbolize',
351 'libLLVMDebugInfoMSF', 'libLLVMMCJIT', 'libLLVMXRay',
352 'libLLVMX86AsmPrinter', 'libLLVMX86Disassembler',
353 'libLLVMMCDisassembler', 'libLLVMOption', 'libLLVMIRReader',
354 'libLLVMLibDriver', 'libLLVMDlltoolDriver', 'libLLVMDemangle',
355 'libLLVMBinaryFormat', 'libLLVMLineEditor',
356 'libLLVMWindowsManifest', 'libLLVMX86Info', 'libLLVMX86Utils']
357 _deps += cpp.find_library(d, dirs : _search)
360 dep_llvm = declare_dependency(
361 include_directories : include_directories('include'),
362 dependencies : _deps,
367 irbuilder_h = files('include/llvm/IR/IRBuilder.h')
369 It is very important that version is defined and is accurate, if it is
370 not, workarounds for the wrong version of LLVM might be used resulting
376 The ``pkg-config`` utility is a hard requirement for configuring and
377 building Mesa on Unix-like systems. It is used to search for external
378 libraries on the system. This environment variable is used to control
379 the search path for ``pkg-config``. For instance, setting
380 ``PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig`` will search for package
381 metadata in ``/usr/X11R6`` before the standard directories.
386 One of the oddities of meson is that some options are different when
387 passed to the ``meson`` than to ``meson configure``. These options are
388 passed as --option=foo to ``meson``, but -Doption=foo to
389 ``meson configure``. Mesa defined options are always passed as
392 For those coming from autotools be aware of the following:
394 ``--buildtype/-Dbuildtype``
395 This option will set the compiler debug/optimisation levels to aid
396 debugging the Mesa libraries.
398 Note that in meson this defaults to ``debugoptimized``, and not
399 setting it to ``release`` will yield non-optimal performance and
400 binary size. Not using ``debug`` may interfere with debugging as some
401 code and validation will be optimized away.
403 For those wishing to pass their own optimization flags, use the
404 ``plain`` buildtype, which causes meson to inject no additional
405 compiler arguments, only those in the C/CXXFLAGS and those that mesa
409 This option controls assertions in meson projects. When set to
410 ``false`` (the default) assertions are enabled, when set to true they
411 are disabled. This is unrelated to the ``buildtype``; setting the
412 latter to ``release`` will not turn off assertions.
414 4. Cross-compilation and 32-bit builds
415 --------------------------------------
418 cross-compilation <https://mesonbuild.com/Cross-compilation.html>`__ by
419 specifying a number of binary paths and settings in a file and passing
420 this file to ``meson`` or ``meson configure`` with the ``--cross-file``
423 This file can live at any location, but you can use the bare filename
424 (without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
425 ~/.local/share/meson/cross
427 Below are a few example of cross files, but keep in mind that you will
428 likely have to alter them for your system.
430 Those running on ArchLinux can use the AUR-maintained packages for some
431 of those, as they'll have the right values for your system:
433 - `meson-cross-x86-linux-gnu <https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu>`__
434 - `meson-cross-aarch64-linux-gnu <https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu>`__
436 32-bit build on x86 linux:
443 ar = '/usr/bin/gcc-ar'
444 strip = '/usr/bin/strip'
445 pkgconfig = '/usr/bin/pkg-config-32'
446 llvm-config = '/usr/bin/llvm-config32'
450 c_link_args = ['-m32']
452 cpp_link_args = ['-m32']
460 64-bit build on ARM linux:
465 c = '/usr/bin/aarch64-linux-gnu-gcc'
466 cpp = '/usr/bin/aarch64-linux-gnu-g++'
467 ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
468 strip = '/usr/bin/aarch64-linux-gnu-strip'
469 pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
470 exe_wrapper = '/usr/bin/qemu-aarch64-static'
474 cpu_family = 'aarch64'
478 64-bit build on x86 windows:
483 c = '/usr/bin/x86_64-w64-mingw32-gcc'
484 cpp = '/usr/bin/x86_64-w64-mingw32-g++'
485 ar = '/usr/bin/x86_64-w64-mingw32-ar'
486 strip = '/usr/bin/x86_64-w64-mingw32-strip'
487 pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
492 cpu_family = 'x86_64'