docs/meson.rst

   1 Compilation and Installation Using Meson
   2 ========================================
   3
   4 -  `Introduction <#intro>`__
   5 -  `Basic Usage <#basic>`__
   6 -  `Advanced Usage <#advanced>`__
   7 -  `Cross-compilation and 32-bit builds <#cross-compilation>`__
   8
   9 .. _intro:
  10
  11 1. Introduction
  12 ---------------
  13
  14 For general information about Meson see the `Meson
  15 website <https://mesonbuild.com/>`__.
  16
  17 **Mesa's Meson build system is generally considered stable and ready for
  18 production.**
  19
  20 **Mesa requires Meson >= 0.52.0 to build.**
  21
  22 The Meson build of Mesa is tested on Linux, macOS, Windows, Cygwin,
  23 Haiku, FreeBSD, DragonflyBSD, NetBSD, and should work on OpenBSD.
  24
  25 Unix-like OSes
  26 ^^^^^^^^^^^^^^
  27
  28 If Meson is not already installed on your system, you can typically
  29 install it with your package installer. For example:
  30
  31 ::
  32
  33    sudo apt-get install meson   # Ubuntu
  34
  35 or
  36
  37 ::
  38
  39    sudo dnf install meson   # Fedora
  40
  41 Some older versions of meson do not check that they are too old and will
  42 error out in odd ways.
  43
  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*
  46 package.
  47
  48 Windows
  49 ^^^^^^^
  50
  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/>`__.
  56
  57 ::
  58
  59    choco install python3 winflexbison pkgconfiglite
  60
  61 You can even use chocolatey to install mingw and ninja (ninja can be
  62 used with MSVC as well)
  63
  64 ::
  65
  66    choco install ninja mingw
  67
  68 Then install meson using pip
  69
  70 ::
  71
  72    py -3 -m pip install meson mako
  73
  74 You may need to add the python3 scripts directory to your path for
  75 meson.
  76
  77 .. _basic:
  78
  79 2. Basic Usage
  80 --------------
  81
  82 The meson program is used to configure the source directory and
  83 generates either a ninja build file or Visual Studio® build files. The
  84 latter must be enabled via the ``--backend`` switch, as ninja is the
  85 default backend on all operating systems.
  86
  87 Meson only supports out-of-tree builds, and must be passed a directory
  88 to put built and generated sources into. We'll call that directory
  89 "build" here. It's recommended to create a `separate build
  90 directory <https://mesonbuild.com/Using-multiple-build-directories.html>`__
  91 for each configuration you might want to use.
  92
  93 Basic configuration is done with:
  94
  95 ::
  96
  97    meson build/
  98
  99 This will create the build directory. If any dependencies are missing,
 100 you can install them, or try to remove the dependency with a Meson
 101 configuration option (see below).
 102
 103 To review the options which Meson chose, run:
 104
 105 ::
 106
 107    meson configure build/
 108
 109 Meson does not currently support listing configuration options before
 110 running "meson build/" but this feature is being discussed upstream. For
 111 now, we have a ``bin/meson-options.py`` script that prints the options
 112 for you. If that script doesn't work for some reason, you can always
 113 look in the
 114 `meson_options.txt <https://gitlab.freedesktop.org/mesa/mesa/-/blob/master/meson_options.txt>`__
 115 file at the root of the project.
 116
 117 With additional arguments ``meson configure`` can be used to change
 118 options for a previously configured build directory. All options passed
 119 to this command are in the form ``-D "option"="value"``. For example:
 120
 121 ::
 122
 123    meson configure build/ -Dprefix=/tmp/install -Dglx=true
 124
 125 Note that options taking lists (such as ``platforms``) are `a bit more
 126 complicated <https://mesonbuild.com/Build-options.html#using-build-options>`__,
 127 but the simplest form compatible with Mesa options is to use a comma to
 128 separate values (``-D platforms=drm,wayland``) and brackets to represent
 129 an empty list (``-D platforms=[]``).
 130
 131 Once you've run the initial ``meson`` command successfully you can use
 132 your configured backend to build the project in your build directory:
 133
 134 ::
 135
 136    ninja -C build/
 137
 138 The next step is to install the Mesa libraries, drivers, etc. This also
 139 finishes up some final steps of the build process (such as creating
 140 symbolic links for drivers). To install:
 141
 142 ::
 143
 144    ninja -C build/ install
 145
 146 Note: 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:
 149
 150 ::
 151
 152    ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
 153
 154 Windows specific instructions
 155 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 156
 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.
 161
 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.
 167
 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.
 173
 174 .. _advanced:
 175
 176 3. Advanced Usage
 177 -----------------
 178
 179 Installation Location
 180 ^^^^^^^^^^^^^^^^^^^^^
 181
 182 Meson default to installing libGL.so in your system's main lib/
 183 directory and DRI drivers to a dri/ subdirectory.
 184
 185 Developers will often want to install Mesa to a testing directory rather
 186 than the system library directory. This can be done with the --prefix
 187 option. For example:
 188
 189 ::
 190
 191    meson --prefix="${PWD}/build/install" build/
 192
 193 will put the final libraries and drivers into the build/install/
 194 directory. Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to
 195 that location to run/test the driver.
 196
 197 Meson also honors ``DESTDIR`` for installs.
 198
 199 Compiler Options
 200 ^^^^^^^^^^^^^^^^
 201
 202 Meson supports the common CFLAGS, CXXFLAGS, etc. environment variables
 203 but their use is discouraged because of the many caveats in using them.
 204
 205 Instead, it is recomended to use ``-D${lang}_args`` and
 206 ``-D${lang}_link_args``. Among the benefits of these options is that
 207 they are guaranteed to persist across rebuilds and reconfigurations.
 208
 209 This example sets -fmax-errors for compiling C sources and -DMAGIC=123
 210 for C++ sources:
 211
 212 ::
 213
 214    meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123
 215
 216 Compiler Specification
 217 ^^^^^^^^^^^^^^^^^^^^^^
 218
 219 Meson supports the standard CC and CXX environment variables for
 220 changing the default compiler. Note that Meson does not allow changing
 221 the compilers in a configured builddir so you will need to create a new
 222 build dir for a different compiler.
 223
 224 This is an example of specifying the clang compilers and cleaning the
 225 build directory before reconfiguring with an extra C option:
 226
 227 ::
 228
 229    CC=clang CXX=clang++ meson build-clang
 230    ninja -C build-clang
 231    ninja -C build-clang clean
 232    meson configure build -Dc_args="-Wno-typedef-redefinition"
 233    ninja -C build-clang
 234
 235 The default compilers depends on your operating system. Meson supports
 236 most of the popular compilers, a complete list is available
 237 `here <https://mesonbuild.com/Reference-tables.html#compiler-ids>`__.
 238
 239 LLVM
 240 ^^^^
 241
 242 Meson includes upstream logic to wrap llvm-config using its standard
 243 dependency interface.
 244
 245 As of meson 0.51.0 meson can use cmake to find llvm (the cmake finder
 246 was added in meson 0.49.0, but LLVM cannot be found until 0.51) Due to
 247 the way LLVM implements its cmake finder it will only find static
 248 libraries, it will never find libllvm.so. There is also a
 249 ``-Dcmake_module_path`` option in this meson version, which points to
 250 the root of an alternative installation (the prefix). For example:
 251
 252 ::
 253
 254    meson builddir -Dcmake_module_path=/home/user/mycmake/prefix
 255
 256 As of meson 0.49.0 meson also has the concept of a `"native
 257 file" <https://mesonbuild.com/Native-environments.html>`__, these files
 258 provide information about the native build environment (as opposed to a
 259 cross build environment). They are ini formatted and can override where
 260 to find llvm-config:
 261
 262 custom-llvm.ini
 263
 264 ::
 265
 266    [binaries]
 267    llvm-config = '/usr/local/bin/llvm/llvm-config'
 268
 269 Then configure meson:
 270
 271 ::
 272
 273    meson builddir/ --native-file custom-llvm.ini
 274
 275 Meson < 0.49 doesn't support native files, so to specify a custom
 276 ``llvm-config`` you need to modify your ``$PATH`` (or ``%PATH%`` on
 277 windows), which will be searched for ``llvm-config``,
 278 ``llvm-config$version``, and ``llvm-config-$version``:
 279
 280 ::
 281
 282    PATH=/path/to/folder/with/llvm-config:$PATH meson build
 283
 284 For selecting llvm-config for cross compiling a `"cross
 285 file" <https://mesonbuild.com/Cross-compilation.html#defining-the-environment>`__
 286 should be used. It uses the same format as the native file above:
 287
 288 cross-llvm.ini
 289
 290 ::
 291
 292    [binaries]
 293    ...
 294    llvm-config = '/usr/lib/llvm-config-32'
 295    cmake = '/usr/bin/cmake-for-my-arch'
 296
 297 Obviously, only cmake or llvm-config is required.
 298
 299 Then configure meson:
 300
 301 ::
 302
 303    meson builddir/ --cross-file cross-llvm.ini
 304
 305 See the `Cross Compilation <#cross-compilation>`__ section for more
 306 information.
 307
 308 On windows (and in other cases), using llvm-config or cmake may be
 309 either undesirable or impossible. Meson's solution for this is a
 310 `wrap <https://mesonbuild.com/Wrap-dependency-system-manual.html>`__, in
 311 this case a "binary wrap". Follow the steps below:
 312
 313 -  Install the binaries and headers into the
 314    ``$mesa_src/subprojects/llvm``
 315 -  Add a meson build.build file to that directory (more on that later)
 316
 317 The wrap file must define the following:
 318
 319 -  ``dep_llvm``: a ``declare_dependency()`` object with
 320    include_directories, dependencies, and version set)
 321
 322 It may also define:
 323
 324 -  ``irbuilder_h``: a ``files()`` object pointing to llvm/IR/IRBuilder.h
 325    (this is requred for SWR)
 326 -  ``has_rtti``: a ``bool`` that declares whether LLVM was built with
 327    RTTI. Defaults to true
 328
 329 such a meson.build file might look like:
 330
 331 ::
 332
 333    project('llvm', ['cpp'])
 334
 335    cpp = meson.get_compiler('cpp')
 336
 337    _deps = []
 338    _search = join_paths(meson.current_source_dir(), 'lib')
 339    foreach d : ['libLLVMCodeGen', 'libLLVMScalarOpts', 'libLLVMAnalysis',
 340                 'libLLVMTransformUtils', 'libLLVMCore', 'libLLVMX86CodeGen',
 341                 'libLLVMSelectionDAG', 'libLLVMipo', 'libLLVMAsmPrinter',
 342                 'libLLVMInstCombine', 'libLLVMInstrumentation', 'libLLVMMC',
 343                 'libLLVMGlobalISel', 'libLLVMObjectYAML', 'libLLVMDebugInfoPDB',
 344                 'libLLVMVectorize', 'libLLVMPasses', 'libLLVMSupport',
 345                 'libLLVMLTO', 'libLLVMObject', 'libLLVMDebugInfoCodeView',
 346                 'libLLVMDebugInfoDWARF', 'libLLVMOrcJIT', 'libLLVMProfileData',
 347                 'libLLVMObjCARCOpts', 'libLLVMBitReader', 'libLLVMCoroutines',
 348                 'libLLVMBitWriter', 'libLLVMRuntimeDyld', 'libLLVMMIRParser',
 349                 'libLLVMX86Desc', 'libLLVMAsmParser', 'libLLVMTableGen',
 350                 'libLLVMFuzzMutate', 'libLLVMLinker', 'libLLVMMCParser',
 351                 'libLLVMExecutionEngine', 'libLLVMCoverage', 'libLLVMInterpreter',
 352                 'libLLVMTarget', 'libLLVMX86AsmParser', 'libLLVMSymbolize',
 353                 'libLLVMDebugInfoMSF', 'libLLVMMCJIT', 'libLLVMXRay',
 354                 'libLLVMX86AsmPrinter', 'libLLVMX86Disassembler',
 355                 'libLLVMMCDisassembler', 'libLLVMOption', 'libLLVMIRReader',
 356                 'libLLVMLibDriver', 'libLLVMDlltoolDriver', 'libLLVMDemangle',
 357                 'libLLVMBinaryFormat', 'libLLVMLineEditor',
 358                 'libLLVMWindowsManifest', 'libLLVMX86Info', 'libLLVMX86Utils']
 359      _deps += cpp.find_library(d, dirs : _search)
 360    endforeach
 361
 362    dep_llvm = declare_dependency(
 363      include_directories : include_directories('include'),
 364      dependencies : _deps,
 365      version : '6.0.0',
 366    )
 367
 368    has_rtti = false
 369    irbuilder_h = files('include/llvm/IR/IRBuilder.h')
 370
 371 It is very important that version is defined and is accurate, if it is
 372 not, workarounds for the wrong version of LLVM might be used resulting
 373 in build failures.
 374
 375 ``PKG_CONFIG_PATH``
 376 ^^^^^^^^^^^^^^^^^^^
 377
 378 The ``pkg-config`` utility is a hard requirement for configuring and
 379 building Mesa on Unix-like systems. It is used to search for external
 380 libraries on the system. This environment variable is used to control
 381 the search path for ``pkg-config``. For instance, setting
 382 ``PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig`` will search for package
 383 metadata in ``/usr/X11R6`` before the standard directories.
 384
 385 Options
 386 ^^^^^^^
 387
 388 One of the oddities of meson is that some options are different when
 389 passed to the ``meson`` than to ``meson configure``. These options are
 390 passed as --option=foo to ``meson``, but -Doption=foo to
 391 ``meson configure``. Mesa defined options are always passed as
 392 -Doption=foo.
 393
 394 For those coming from autotools be aware of the following:
 395
 396 ``--buildtype/-Dbuildtype``
 397    This option will set the compiler debug/optimisation levels to aid
 398    debugging the Mesa libraries.
 399
 400    Note that in meson this defaults to ``debugoptimized``, and not
 401    setting it to ``release`` will yield non-optimal performance and
 402    binary size. Not using ``debug`` may interfere with debugging as some
 403    code and validation will be optimized away.
 404
 405    For those wishing to pass their own optimization flags, use the
 406    ``plain`` buildtype, which causes meson to inject no additional
 407    compiler arguments, only those in the C/CXXFLAGS and those that mesa
 408    itself defines.
 409
 410 ``-Db_ndebug``
 411    This option controls assertions in meson projects. When set to
 412    ``false`` (the default) assertions are enabled, when set to true they
 413    are disabled. This is unrelated to the ``buildtype``; setting the
 414    latter to ``release`` will not turn off assertions.
 415
 416 .. _cross-compilation:
 417
 418 4. Cross-compilation and 32-bit builds
 419 --------------------------------------
 420
 421 `Meson supports
 422 cross-compilation <https://mesonbuild.com/Cross-compilation.html>`__ by
 423 specifying a number of binary paths and settings in a file and passing
 424 this file to ``meson`` or ``meson configure`` with the ``--cross-file``
 425 parameter.
 426
 427 This file can live at any location, but you can use the bare filename
 428 (without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
 429 ~/.local/share/meson/cross
 430
 431 Below are a few example of cross files, but keep in mind that you will
 432 likely have to alter them for your system.
 433
 434 Those running on ArchLinux can use the AUR-maintained packages for some
 435 of those, as they'll have the right values for your system:
 436
 437 -  `meson-cross-x86-linux-gnu <https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu>`__
 438 -  `meson-cross-aarch64-linux-gnu <https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu>`__
 439
 440 32-bit build on x86 linux:
 441
 442 ::
 443
 444    [binaries]
 445    c = '/usr/bin/gcc'
 446    cpp = '/usr/bin/g++'
 447    ar = '/usr/bin/gcc-ar'
 448    strip = '/usr/bin/strip'
 449    pkgconfig = '/usr/bin/pkg-config-32'
 450    llvm-config = '/usr/bin/llvm-config32'
 451
 452    [properties]
 453    c_args = ['-m32']
 454    c_link_args = ['-m32']
 455    cpp_args = ['-m32']
 456    cpp_link_args = ['-m32']
 457
 458    [host_machine]
 459    system = 'linux'
 460    cpu_family = 'x86'
 461    cpu = 'i686'
 462    endian = 'little'
 463
 464 64-bit build on ARM linux:
 465
 466 ::
 467
 468    [binaries]
 469    c = '/usr/bin/aarch64-linux-gnu-gcc'
 470    cpp = '/usr/bin/aarch64-linux-gnu-g++'
 471    ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
 472    strip = '/usr/bin/aarch64-linux-gnu-strip'
 473    pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
 474    exe_wrapper = '/usr/bin/qemu-aarch64-static'
 475
 476    [host_machine]
 477    system = 'linux'
 478    cpu_family = 'aarch64'
 479    cpu = 'aarch64'
 480    endian = 'little'
 481
 482 64-bit build on x86 windows:
 483
 484 ::
 485
 486    [binaries]
 487    c = '/usr/bin/x86_64-w64-mingw32-gcc'
 488    cpp = '/usr/bin/x86_64-w64-mingw32-g++'
 489    ar = '/usr/bin/x86_64-w64-mingw32-ar'
 490    strip = '/usr/bin/x86_64-w64-mingw32-strip'
 491    pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
 492    exe_wrapper = 'wine'
 493
 494    [host_machine]
 495    system = 'windows'
 496    cpu_family = 'x86_64'
 497    cpu = 'i686'
 498    endian = 'little'