558 lines
17 KiB
HTML
558 lines
17 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html lang="en">
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8">
|
|
<title>Compilation and Installation Using Meson</title>
|
|
<link rel="stylesheet" type="text/css" href="mesa.css">
|
|
</head>
|
|
<body>
|
|
|
|
<div class="header">
|
|
The Mesa 3D Graphics Library
|
|
</div>
|
|
|
|
<iframe src="contents.html"></iframe>
|
|
<div class="content">
|
|
|
|
<h1>Compilation and Installation Using Meson</h1>
|
|
|
|
<ul>
|
|
<li><a href="#intro">Introduction</a></li>
|
|
<li><a href="#basic">Basic Usage</a></li>
|
|
<li><a href="#advanced">Advanced Usage</a></li>
|
|
<li><a href="#cross-compilation">Cross-compilation and 32-bit builds</a></li>
|
|
</ul>
|
|
|
|
<h2 id="intro">1. Introduction</h2>
|
|
|
|
<p>For general information about Meson see the
|
|
<a href="https://mesonbuild.com/">Meson website</a>.</p>
|
|
|
|
<p><strong>Mesa's Meson build system is generally considered stable and ready
|
|
for production.</strong></p>
|
|
|
|
<p><strong>Mesa requires Meson >= 0.46.0 to build.</strong>
|
|
|
|
<p>The Meson build of Mesa is tested on Linux, macOS, Windows, Cygwin, Haiku, FreeBSD,
|
|
DragonflyBSD, NetBSD, and should work on OpenBSD.</p>
|
|
|
|
<h4>Unix-like OSes</h4>
|
|
|
|
<p>If Meson is not already installed on your system, you can typically
|
|
install it with your package installer. For example:</p>
|
|
<pre>
|
|
sudo apt-get install meson # Ubuntu
|
|
</pre>
|
|
or
|
|
<pre>
|
|
sudo dnf install meson # Fedora
|
|
</pre>
|
|
|
|
Some older versions of meson do not check that they are too old and will error
|
|
out in odd ways.
|
|
</p>
|
|
|
|
<p>You'll also need <a href="https://ninja-build.org/">Ninja</a>.
|
|
If it's not already installed, use apt-get or dnf to install
|
|
the <em>ninja-build</em> package.
|
|
</p>
|
|
|
|
<h4>Windows</h4>
|
|
|
|
<p>
|
|
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 <a
|
|
href="https://chocolatey.org/">chocolatey</a>.
|
|
</p>
|
|
<pre>
|
|
choco install python3 winflexbison pkgconfiglite
|
|
</pre>
|
|
<p>You can even use chocolatey to install mingw and ninja (ninja can be used with MSVC as well)</p>
|
|
<pre>
|
|
choco install ninja mingw
|
|
</pre>
|
|
<p>Then install meson using pip</p>
|
|
<pre>
|
|
py -3 -m pip install meson mako
|
|
</pre>
|
|
|
|
You may need to add the python3 scripts directory to your path for meson.
|
|
|
|
<h2 id="basic">2. Basic Usage</h2>
|
|
|
|
<p>
|
|
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 <code>--backend</code> switch, as ninja is the default
|
|
backend on all operating systems.
|
|
</p>
|
|
|
|
<p>
|
|
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
|
|
<a href="https://mesonbuild.com/Using-multiple-build-directories.html">
|
|
separate build directory</a> for each configuration you might want to use.
|
|
</p>
|
|
|
|
|
|
|
|
<p>Basic configuration is done with:</p>
|
|
|
|
<pre>
|
|
meson build/
|
|
</pre>
|
|
|
|
<p>
|
|
This will create the build directory.
|
|
If any dependencies are missing, you can install them, or try to remove
|
|
the dependency with a Meson configuration option (see below).
|
|
</p>
|
|
|
|
<p>
|
|
To review the options which Meson chose, run:
|
|
</p>
|
|
<pre>
|
|
meson configure build/
|
|
</pre>
|
|
|
|
<p>
|
|
Meson does not currently support listing configuration options before
|
|
running "meson build/" but this feature is being discussed upstream.
|
|
For now, we have a <code>bin/meson-options.py</code> script that prints
|
|
the options for you.
|
|
If that script doesn't work for some reason, you can always look in the
|
|
<a href="https://gitlab.freedesktop.org/mesa/mesa/blob/master/meson_options.txt">
|
|
meson_options.txt</a> file at the root of the project.
|
|
</p>
|
|
|
|
<p>
|
|
With additional arguments <code>meson configure</code> can be used to change
|
|
options for a previously configured build directory.
|
|
All options passed to this command are in the form
|
|
<code>-D "option"="value"</code>.
|
|
For example:
|
|
</p>
|
|
|
|
<pre>
|
|
meson configure build/ -Dprefix=/tmp/install -Dglx=true
|
|
</pre>
|
|
|
|
<p>
|
|
Note that options taking lists (such as <code>platforms</code>) are
|
|
<a href="https://mesonbuild.com/Build-options.html#using-build-options">a bit
|
|
more complicated</a>, but the simplest form compatible with Mesa options
|
|
is to use a comma to separate values (<code>-D platforms=drm,wayland</code>)
|
|
and brackets to represent an empty list (<code>-D platforms=[]</code>).
|
|
</p>
|
|
|
|
<p>
|
|
Once you've run the initial <code>meson</code> command successfully you can use
|
|
your configured backend to build the project in your build directory:
|
|
</p>
|
|
|
|
<pre>
|
|
ninja -C build/
|
|
</pre>
|
|
|
|
<p>
|
|
The next step is to install the Mesa libraries, drivers, etc.
|
|
This also finishes up some final steps of the build process (such as creating
|
|
symbolic links for drivers). To install:
|
|
</p>
|
|
|
|
<pre>
|
|
ninja -C build/ install
|
|
</pre>
|
|
|
|
<p>
|
|
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:
|
|
</p>
|
|
<pre>
|
|
ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo
|
|
</pre>
|
|
|
|
<h4>Windows specific instructions</h4>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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 <a
|
|
href="https://mesonbuild.com/Native-environments.html">native file</a>, or
|
|
with the CC and CXX environment variables.
|
|
</p>
|
|
<p>
|
|
All of these compilers are tested and work with ninja, but if you want visual
|
|
studio integration or you just like msbuild, passing
|
|
<code>--backend=vs</code> 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.
|
|
</p>
|
|
|
|
<h2 id="advanced">3. Advanced Usage</h2>
|
|
|
|
<dl>
|
|
|
|
<dt>Installation Location</dt>
|
|
<dd>
|
|
<p>
|
|
Meson default to installing libGL.so in your system's main lib/ directory
|
|
and DRI drivers to a dri/ subdirectory.
|
|
</p>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<pre>
|
|
meson --prefix="${PWD}/build/install" build/
|
|
</pre>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
Meson also honors <code>DESTDIR</code> for installs.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt>Compiler Options</dt>
|
|
<dd>
|
|
<p>Meson supports the common CFLAGS, CXXFLAGS, etc. environment
|
|
variables but their use is discouraged because of the many caveats
|
|
in using them.
|
|
</p>
|
|
<p>Instead, it is recomended to use <code>-D${lang}_args</code> and
|
|
<code>-D${lang}_link_args</code>. Among the benefits of these options
|
|
is that they are guaranteed to persist across rebuilds and reconfigurations.
|
|
</p>
|
|
<p>
|
|
This example sets -fmax-errors for compiling C sources and -DMAGIC=123
|
|
for C++ sources:
|
|
</p>
|
|
<pre>
|
|
meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123
|
|
</pre>
|
|
</dd>
|
|
|
|
|
|
<dt>Compiler Specification</dt>
|
|
<dd>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
This is an example of specifying the clang compilers and cleaning
|
|
the build directory before reconfiguring with an extra C option:
|
|
</p>
|
|
<pre>
|
|
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
|
|
</pre>
|
|
<p>
|
|
The default compilers depends on your operating system. Meson supports most of
|
|
the popular compilers, a complete list is available
|
|
<a href="https://mesonbuild.com/Reference-tables.html#compiler-ids">here</a>.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt>LLVM</dt>
|
|
<dd><p>Meson includes upstream logic to wrap llvm-config using its standard
|
|
dependency interface.
|
|
</p></dd>
|
|
|
|
<dd><p>
|
|
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 <pre>-Dcmake_module_path</pre> option in this meson version,
|
|
which points to the root of an alternative installation (the prefix). For
|
|
example:
|
|
<pre>
|
|
meson builddir -Dcmake_module_path=/home/user/mycmake/prefix
|
|
</pre>
|
|
</p></dd>
|
|
|
|
<dd><p>
|
|
As of meson 0.49.0 meson also has the concept of a
|
|
<a href="https://mesonbuild.com/Native-environments.html">"native file"</a>,
|
|
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:
|
|
</p>
|
|
|
|
custom-llvm.ini
|
|
<pre>
|
|
[binaries]
|
|
llvm-config = '/usr/local/bin/llvm/llvm-config'
|
|
</pre>
|
|
|
|
Then configure meson:
|
|
|
|
<pre>
|
|
meson builddir/ --native-file custom-llvm.ini
|
|
</pre>
|
|
</dd>
|
|
|
|
<dd><p>
|
|
Meson < 0.49 doesn't support native files, so to specify a custom
|
|
<code>llvm-config</code> you need to modify your <code>$PATH</code> (or
|
|
<code>%PATH%</code> on windows), which will be searched for
|
|
<code>llvm-config</code>, <code>llvm-config<i>$version</i></code>,
|
|
and <code>llvm-config-<i>$version</i></code>:
|
|
</p>
|
|
<pre>
|
|
PATH=/path/to/folder/with/llvm-config:$PATH meson build
|
|
</pre>
|
|
</dd>
|
|
|
|
<dd><p>
|
|
For selecting llvm-config for cross compiling a
|
|
<a href="https://mesonbuild.com/Cross-compilation.html#defining-the-environment">"cross file"</a>
|
|
should be used. It uses the same format as the native file above:
|
|
</p>
|
|
|
|
<p>cross-llvm.ini</p>
|
|
<pre>
|
|
[binaries]
|
|
...
|
|
llvm-config = '/usr/lib/llvm-config-32'
|
|
cmake = '/usr/bin/cmake-for-my-arch'
|
|
</pre>
|
|
|
|
<p>Obviously, only cmake or llvm-config is required.</p>
|
|
|
|
<p>Then configure meson:</p>
|
|
<pre>
|
|
meson builddir/ --cross-file cross-llvm.ini
|
|
</pre>
|
|
|
|
See the <a href="#cross-compilation">Cross Compilation</a> section for more information.
|
|
</dd>
|
|
|
|
<dd><p>On windows (and in other cases), using llvm-config or cmake may be
|
|
either undesirable or impossible. Meson's solution for this is a
|
|
<a href="https://mesonbuild.com/Wrap-dependency-system-manual.html">wrap</a>, in
|
|
this case a "binary wrap". Follow the steps below:</p>
|
|
<ul>
|
|
<li>Install the binaries and headers into the <code>$mesa_src/subprojects/llvm</code></li>
|
|
<li>Add a meson build.build file to that directory (more on that later)</li>
|
|
</ul>
|
|
|
|
<p>The wrap file must define the following:</p>
|
|
<ul>
|
|
<li><code>dep_llvm</code>: a <code>declare_dependency()</code> object with include_directories, dependencies, and version set)</li>
|
|
</ul>
|
|
|
|
<p>It may also define:</p>
|
|
<ul>
|
|
<li><code>irbuilder_h</code>: a <code>files()</code> object pointing to llvm/IR/IRBuilder.h (this is requred for SWR)</li>
|
|
<li><code>has_rtti</code>: a <code>bool</code> that declares whether LLVM was built with RTTI. Defaults to true</li>
|
|
</ul>
|
|
|
|
<p>such a meson.build file might look like:</p>
|
|
<pre>
|
|
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')
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
<dt><code>PKG_CONFIG_PATH</code></dt>
|
|
<dd><p>The
|
|
<code>pkg-config</code> 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
|
|
<code>pkg-config</code>. For instance, setting
|
|
<code>PKG_CONFIG_PATH=/usr/X11R6/lib/pkgconfig</code> will search for package
|
|
metadata in <code>/usr/X11R6</code> before the standard directories.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
One of the oddities of meson is that some options are different when passed to
|
|
the <code>meson</code> than to <code>meson configure</code>. These options are
|
|
passed as --option=foo to <code>meson</code>, but -Doption=foo to <code>meson
|
|
configure</code>. Mesa defined options are always passed as -Doption=foo.
|
|
</p>
|
|
|
|
<p>For those coming from autotools be aware of the following:</p>
|
|
|
|
<dl>
|
|
<dt><code>--buildtype/-Dbuildtype</code></dt>
|
|
<dd><p>This option will set the compiler debug/optimisation levels to aid
|
|
debugging the Mesa libraries.</p>
|
|
|
|
<p>Note that in meson this defaults to <code>debugoptimized</code>, and
|
|
not setting it to <code>release</code> will yield non-optimal
|
|
performance and binary size. Not using <code>debug</code> may interfere
|
|
with debugging as some code and validation will be optimized away.
|
|
</p>
|
|
|
|
<p> For those wishing to pass their own optimization flags, use the <code>plain</code>
|
|
buildtype, which causes meson to inject no additional compiler arguments, only
|
|
those in the C/CXXFLAGS and those that mesa itself defines.</p>
|
|
</dd>
|
|
|
|
<dt><code>-Db_ndebug</code></dt>
|
|
<dd><p>This option controls assertions in meson projects. When set to <code>false</code>
|
|
(the default) assertions are enabled, when set to true they are disabled. This
|
|
is unrelated to the <code>buildtype</code>; setting the latter to
|
|
<code>release</code> will not turn off assertions.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2 id="cross-compilation">4. Cross-compilation and 32-bit builds</h2>
|
|
|
|
<p><a href="https://mesonbuild.com/Cross-compilation.html">Meson supports
|
|
cross-compilation</a> by specifying a number of binary paths and
|
|
settings in a file and passing this file to <code>meson</code> or
|
|
<code>meson configure</code> with the <code>--cross-file</code>
|
|
parameter.</p>
|
|
|
|
<p>This file can live at any location, but you can use the bare filename
|
|
(without the folder path) if you put it in $XDG_DATA_HOME/meson/cross or
|
|
~/.local/share/meson/cross</p>
|
|
|
|
<p>Below are a few example of cross files, but keep in mind that you
|
|
will likely have to alter them for your system.</p>
|
|
|
|
<p>
|
|
Those running on ArchLinux can use the AUR-maintained packages for some
|
|
of those, as they'll have the right values for your system:
|
|
</p>
|
|
<ul>
|
|
<li><a href="https://aur.archlinux.org/packages/meson-cross-x86-linux-gnu">meson-cross-x86-linux-gnu</a></li>
|
|
<li><a href="https://aur.archlinux.org/packages/meson-cross-aarch64-linux-gnu">meson-cross-aarch64-linux-gnu</a></li>
|
|
</ul>
|
|
|
|
<p>
|
|
32-bit build on x86 linux:
|
|
</p>
|
|
<pre>
|
|
[binaries]
|
|
c = '/usr/bin/gcc'
|
|
cpp = '/usr/bin/g++'
|
|
ar = '/usr/bin/gcc-ar'
|
|
strip = '/usr/bin/strip'
|
|
pkgconfig = '/usr/bin/pkg-config-32'
|
|
llvm-config = '/usr/bin/llvm-config32'
|
|
|
|
[properties]
|
|
c_args = ['-m32']
|
|
c_link_args = ['-m32']
|
|
cpp_args = ['-m32']
|
|
cpp_link_args = ['-m32']
|
|
|
|
[host_machine]
|
|
system = 'linux'
|
|
cpu_family = 'x86'
|
|
cpu = 'i686'
|
|
endian = 'little'
|
|
</pre>
|
|
|
|
<p>
|
|
64-bit build on ARM linux:
|
|
</p>
|
|
<pre>
|
|
[binaries]
|
|
c = '/usr/bin/aarch64-linux-gnu-gcc'
|
|
cpp = '/usr/bin/aarch64-linux-gnu-g++'
|
|
ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
|
|
strip = '/usr/bin/aarch64-linux-gnu-strip'
|
|
pkgconfig = '/usr/bin/aarch64-linux-gnu-pkg-config'
|
|
exe_wrapper = '/usr/bin/qemu-aarch64-static'
|
|
|
|
[host_machine]
|
|
system = 'linux'
|
|
cpu_family = 'aarch64'
|
|
cpu = 'aarch64'
|
|
endian = 'little'
|
|
</pre>
|
|
|
|
<p>
|
|
64-bit build on x86 windows:
|
|
</p>
|
|
<pre>
|
|
[binaries]
|
|
c = '/usr/bin/x86_64-w64-mingw32-gcc'
|
|
cpp = '/usr/bin/x86_64-w64-mingw32-g++'
|
|
ar = '/usr/bin/x86_64-w64-mingw32-ar'
|
|
strip = '/usr/bin/x86_64-w64-mingw32-strip'
|
|
pkgconfig = '/usr/bin/x86_64-w64-mingw32-pkg-config'
|
|
exe_wrapper = 'wine'
|
|
|
|
[host_machine]
|
|
system = 'windows'
|
|
cpu_family = 'x86_64'
|
|
cpu = 'i686'
|
|
endian = 'little'
|
|
</pre>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|