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::
 147
 148    autotools automatically updated translation files (used by the DRI
 149    configuration tool) as part of the build process, Meson does not do
 150    this. Instead, you will need do this:
 151
 152    ::
 153
 154       ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
 155
 156 Windows specific instructions
 157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 158
 159 On windows you have a couple of choices for compilers. If you installed
 160 mingw with chocolatey and want to use ninja you should be able to open
 161 any shell and follow the instructions above. If you want to you MSVC,
 162 clang-cl, or ICL (the Intel Compiler), read on.
 163
 164 Both ICL and MSVC come with shell environments, the easiest way to use
 165 meson with these it to open a shell. For clang-cl you will need to open
 166 an MSVC shell, and then override the compilers, either using a `native
 167 file <https://mesonbuild.com/Native-environments.html>`__, or with the
 168 CC and CXX environment variables.
 169
 170 All of these compilers are tested and work with ninja, but if you want
 171 visual studio integration or you just like msbuild, passing
 172 ``--backend=vs`` to meson will generate a visual studio solution. If you
 173 want to use ICL or clang-cl with the vsbackend you will need meson
 174 0.52.0 or greater. Older versions always use the microsoft compiler.
 175
 176 .. _advanced:
 177
 178 3. Advanced Usage
 179 -----------------
 180
 181 Installation Location
 182 ^^^^^^^^^^^^^^^^^^^^^
 183
 184 Meson default to installing libGL.so in your system's main lib/
 185 directory and DRI drivers to a dri/ subdirectory.
 186
 187 Developers will often want to install Mesa to a testing directory rather
 188 than the system library directory. This can be done with the --prefix
 189 option. For example:
 190
 191 ::
 192
 193    meson --prefix="${PWD}/build/install" build/
 194
 195 will put the final libraries and drivers into the build/install/
 196 directory. Then you can set LD_LIBRARY_PATH and LIBGL_DRIVERS_PATH to
 197 that location to run/test the driver.
 198
 199 Meson also honors ``DESTDIR`` for installs.
 200
 201 Compiler Options
 202 ^^^^^^^^^^^^^^^^
 203
 204 Meson supports the common CFLAGS, CXXFLAGS, etc. environment variables
 205 but their use is discouraged because of the many caveats in using them.
 206
 207 Instead, it is recomended to use ``-D${lang}_args`` and
 208 ``-D${lang}_link_args``. Among the benefits of these options is that
 209 they are guaranteed to persist across rebuilds and reconfigurations.
 210
 211 This example sets -fmax-errors for compiling C sources and -DMAGIC=123
 212 for C++ sources:
 213
 214 ::
 215
 216    meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123
 217
 218 Compiler Specification
 219 ^^^^^^^^^^^^^^^^^^^^^^
 220
 221 Meson supports the standard CC and CXX environment variables for
 222 changing the default compiler. Note that Meson does not allow changing
 223 the compilers in a configured builddir so you will need to create a new
 224 build dir for a different compiler.
 225
 226 This is an example of specifying the clang compilers and cleaning the
 227 build directory before reconfiguring with an extra C option:
 228
 229 ::
 230
 231    CC=clang CXX=clang++ meson build-clang
 232    ninja -C build-clang
 233    ninja -C build-clang clean
 234    meson configure build -Dc_args="-Wno-typedef-redefinition"
 235    ninja -C build-clang
 236
 237 The default compilers depends on your operating system. Meson supports
 238 most of the popular compilers, a complete list is available
 239 `here <https://mesonbuild.com/Reference-tables.html#compiler-ids>`__.
 240
 241 LLVM
 242 ^^^^
 243
 244 Meson includes upstream logic to wrap llvm-config using its standard
 245 dependency interface.
 246
 247 As of meson 0.51.0 meson can use cmake to find llvm (the cmake finder
 248 was added in meson 0.49.0, but LLVM cannot be found until 0.51) Due to
 249 the way LLVM implements its cmake finder it will only find static
 250 libraries, it will never find libllvm.so. There is also a
 251 ``-Dcmake_module_path`` option in this meson version, which points to
 252 the root of an alternative installation (the prefix). For example:
 253
 254 ::
 255
 256    meson builddir -Dcmake_module_path=/home/user/mycmake/prefix
 257
 258 As of meson 0.49.0 meson also has the concept of a `"native
 259 file" <https://mesonbuild.com/Native-environments.html>`__, these files
 260 provide information about the native build environment (as opposed to a
 261 cross build environment). They are ini formatted and can override where
 262 to find llvm-config:
 263
 264 custom-llvm.ini
 265
 266 ::
 267
 268    [binaries]
 269    llvm-config = '/usr/local/bin/llvm/llvm-config'
 270
 271 Then configure meson:
 272
 273 ::
 274
 275    meson builddir/ --native-file custom-llvm.ini
 276
 277 Meson < 0.49 doesn't support native files, so to specify a custom
 278 ``llvm-config`` you need to modify your ``$PATH`` (or ``%PATH%`` on
 279 windows), which will be searched for ``llvm-config``,
 280 ``llvm-config$version``, and ``llvm-config-$version``:
 281
 282 ::
 283
 284    PATH=/path/to/folder/with/llvm-config:$PATH meson build
 285
 286 For selecting llvm-config for cross compiling a `"cross
 287 file" <https://mesonbuild.com/Cross-compilation.html#defining-the-environment>`__
 288 should be used. It uses the same format as the native file above:
 289
 290 cross-llvm.ini
 291
 292 ::
 293
 294    [binaries]
 295    ...
 296    llvm-config = '/usr/lib/llvm-config-32'
 297    cmake = '/usr/bin/cmake-for-my-arch'
 298
 299 Obviously, only cmake or llvm-config is required.
 300
 301 Then configure meson:
 302
 303 ::
 304
 305    meson builddir/ --cross-file cross-llvm.ini
 306
 307 See the `Cross Compilation <#cross-compilation>`__ section for more
 308 information.
 309
 310 On windows (and in other cases), using llvm-config or cmake may be
 311 either undesirable or impossible. Meson's solution for this is a
 312 `wrap <https://mesonbuild.com/Wrap-dependency-system-manual.html>`__, in
 313 this case a "binary wrap". Follow the steps below:
 314
 315 -  Install the binaries and headers into the
 316    ``$mesa_src/subprojects/llvm``
 317 -  Add a meson build.build file to that directory (more on that later)
 318
 319 The wrap file must define the following:
 320
 321 -  ``dep_llvm``: a ``declare_dependency()`` object with
 322    include_directories, dependencies, and version set)
 323
 324 It may also define:
 325
 326 -  ``irbuilder_h``: a ``files()`` object pointing to llvm/IR/IRBuilder.h
 327    (this is requred for SWR)
 328 -  ``has_rtti``: a ``bool`` that declares whether LLVM was built with
 329    RTTI. Defaults to true
 330
 331 such a meson.build file might look like:
 332
 333 ::
 334
 335    project('llvm', ['cpp'])
 336
 337    cpp = meson.get_compiler('cpp')
 338
 339    _deps = []
 340    _search = join_paths(meson.current_source_dir(), 'lib')
 341    foreach d : ['libLLVMCodeGen', 'libLLVMScalarOpts', 'libLLVMAnalysis',
 342                 'libLLVMTransformUtils', 'libLLVMCore', 'libLLVMX86CodeGen',
 343                 'libLLVMSelectionDAG', 'libLLVMipo', 'libLLVMAsmPrinter',
 344                 'libLLVMInstCombine', 'libLLVMInstrumentation', 'libLLVMMC',
 345                 'libLLVMGlobalISel', 'libLLVMObjectYAML', 'libLLVMDebugInfoPDB',
 346                 'libLLVMVectorize', 'libLLVMPasses', 'libLLVMSupport',
 347                 'libLLVMLTO', 'libLLVMObject', 'libLLVMDebugInfoCodeView',
 348                 'libLLVMDebugInfoDWARF', 'libLLVMOrcJIT', 'libLLVMProfileData',
 349                 'libLLVMObjCARCOpts', 'libLLVMBitReader', 'libLLVMCoroutines',
 350                 'libLLVMBitWriter', 'libLLVMRuntimeDyld', 'libLLVMMIRParser',
 351                 'libLLVMX86Desc', 'libLLVMAsmParser', 'libLLVMTableGen',
 352                 'libLLVMFuzzMutate', 'libLLVMLinker', 'libLLVMMCParser',
 353                 'libLLVMExecutionEngine', 'libLLVMCoverage', 'libLLVMInterpreter',
 354                 'libLLVMTarget', 'libLLVMX86AsmParser', 'libLLVMSymbolize',
 355                 'libLLVMDebugInfoMSF', 'libLLVMMCJIT', 'libLLVMXRay',
 356                 'libLLVMX86AsmPrinter', 'libLLVMX86Disassembler',
 357                 'libLLVMMCDisassembler', 'libLLVMOption', 'libLLVMIRReader',
 358                 'libLLVMLibDriver', 'libLLVMDlltoolDriver', 'libLLVMDemangle',
 359                 'libLLVMBinaryFormat', 'libLLVMLineEditor',
 360                 'libLLVMWindowsManifest', 'libLLVMX86Info', 'libLLVMX86Utils']
 361      _deps += cpp.find_library(d, dirs : _search)
 362    endforeach
 363
 364    dep_llvm = declare_dependency(
 365      include_directories : include_directories('include'),
 366      dependencies : _deps,
 367      version : '6.0.0',
 368    )
 369
 370    has_rtti = false
 371    irbuilder_h = files('include/llvm/IR/IRBuilder.h')
 372
 373 It is very important that version is defined and is accurate, if it is
 374 not, workarounds for the wrong version of LLVM might be used resulting
 375 in build failures.
 376
 377 ``PKG_CONFIG_PATH``
 378 ^^^^^^^^^^^^^^^^^^^
 379
 380 The ``pkg-config`` utility is a hard requirement for configuring and
 381 building Mesa on Unix-like systems. It is used to search for external
 382 libraries on the system. This environment variable is used to control
 383 the search path for ``pkg-config``. For instance, setting
 384 ``PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig`` will search for package
 385 metadata in ``/usr/X11R6`` before the standard directories.
 386
 387 Options
 388 ^^^^^^^
 389
 390 One of the oddities of meson is that some options are different when
 391 passed to the ``meson`` than to ``meson configure``. These options are
 392 passed as --option=foo to ``meson``, but -Doption=foo to
 393 ``meson configure``. Mesa defined options are always passed as
 394 -Doption=foo.
 395
 396 For those coming from autotools be aware of the following:
 397
 398 ``--buildtype/-Dbuildtype``
 399    This option will set the compiler debug/optimisation levels to aid
 400    debugging the Mesa libraries.
 401
 402    Note that in meson this defaults to ``debugoptimized``, and not
 403    setting it to ``release`` will yield non-optimal performance and
 404    binary size. Not using ``debug`` may interfere with debugging as some
 405    code and validation will be optimized away.
 406
 407    For those wishing to pass their own optimization flags, use the
 408    ``plain`` buildtype, which causes meson to inject no additional
 409    compiler arguments, only those in the C/CXXFLAGS and those that mesa
 410    itself defines.
 411
 412 ``-Db_ndebug``
 413    This option controls assertions in meson projects. When set to
 414    ``false`` (the default) assertions are enabled, when set to true they
 415    are disabled. This is unrelated to the ``buildtype``; setting the
 416    latter to ``release`` will not turn off assertions.
 417
 418 .. _cross-compilation:
 419
 420 4. Cross-compilation and 32-bit builds
 421 --------------------------------------
 422
 423 `Meson supports
 424 cross-compilation <https://mesonbuild.com/Cross-compilation.html>`__ by
 425 specifying a number of binary paths and settings in a file and passing
 426 this file to ``meson`` or ``meson configure`` with the ``--cross-file``
 427 parameter.
 428
 429 This file can live at any location, but you can use the bare filename
 430 (without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
 431 ~/.local/share/meson/cross
 432
 433 Below are a few example of cross files, but keep in mind that you will
 434 likely have to alter them for your system.
 435
 436 Those running on ArchLinux can use the AUR-maintained packages for some
 437 of those, as they'll have the right values for your system:
 438
 439 -  `meson-cross-x86-linux-gnu <https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu>`__
 440 -  `meson-cross-aarch64-linux-gnu <https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu>`__
 441
 442 32-bit build on x86 linux:
 443
 444 ::
 445
 446    [binaries]
 447    c = '/usr/bin/gcc'
 448    cpp = '/usr/bin/g++'
 449    ar = '/usr/bin/gcc-ar'
 450    strip = '/usr/bin/strip'
 451    pkgconfig = '/usr/bin/pkg-config-32'
 452    llvm-config = '/usr/bin/llvm-config32'
 453
 454    [properties]
 455    c_args = ['-m32']
 456    c_link_args = ['-m32']
 457    cpp_args = ['-m32']
 458    cpp_link_args = ['-m32']
 459
 460    [host_machine]
 461    system = 'linux'
 462    cpu_family = 'x86'
 463    cpu = 'i686'
 464    endian = 'little'
 465
 466 64-bit build on ARM linux:
 467
 468 ::
 469
 470    [binaries]
 471    c = '/usr/bin/aarch64-linux-gnu-gcc'
 472    cpp = '/usr/bin/aarch64-linux-gnu-g++'
 473    ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
 474    strip = '/usr/bin/aarch64-linux-gnu-strip'
 475    pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
 476    exe_wrapper = '/usr/bin/qemu-aarch64-static'
 477
 478    [host_machine]
 479    system = 'linux'
 480    cpu_family = 'aarch64'
 481    cpu = 'aarch64'
 482    endian = 'little'
 483
 484 64-bit build on x86 windows:
 485
 486 ::
 487
 488    [binaries]
 489    c = '/usr/bin/x86_64-w64-mingw32-gcc'
 490    cpp = '/usr/bin/x86_64-w64-mingw32-g++'
 491    ar = '/usr/bin/x86_64-w64-mingw32-ar'
 492    strip = '/usr/bin/x86_64-w64-mingw32-strip'
 493    pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
 494    exe_wrapper = 'wine'
 495
 496    [host_machine]
 497    system = 'windows'
 498    cpu_family = 'x86_64'
 499    cpu = 'i686'
 500    endian = 'little'