The Meson Build System http://mesonbuild.com/

7.2 KiB

Raw Blame History

Cross and Native File reference

Cross and native files are nearly identical, but not completely. This is the documentation on the common values used by both, for the specific values of one or the other see the cross compilation and native environments.

Data Types

There are four basic data types in a machine file:

strings
arrays
booleans
integers

A string is specified single quoted:

[section]
option1 = 'false'
option2 = '2'

An array is enclosed in square brackets, and must consist of strings or booleans

[section]
option = ['value']

A boolean must be either true or false, and unquoted.

option = false

An integer must be either an unquoted numeric constant;

option = 42

Sections

The following sections are allowed:

constants
binaries
paths
properties
project options
built-in options

constants

Since 0.56.0

String and list concatenation is supported using the + operator, joining paths is supported using the / operator. Entries defined in the [constants] section can be used in any other section (they are always parsed first), entries in any other section can be used only within that same section and only after it has been defined.

[constants]
toolchain = '/toolchain'
common_flags = ['--sysroot=' + toolchain / 'sysroot']

[properties]
c_args = common_flags + ['-DSOMETHING']
cpp_args = c_args + ['-DSOMETHING_ELSE']

[binaries]
c = toolchain / 'gcc'

This can be useful with cross file composition as well. A generic cross file could be composed with a platform specific file where constants are defined:

# aarch64.ini
[constants]
arch = 'aarch64-linux-gnu'

# cross.ini
[binaries]
c = arch + '-gcc'
cpp = arch + '-g++'
strip = arch + '-strip'
pkgconfig = arch + '-pkg-config'
...

This can be used as meson setup --cross-file aarch64.ini --cross-file cross.ini builddir.

Note that file composition happens before the parsing of values. The example below results in b being 'HelloWorld':

# file1.ini:
[constants]
a = 'Foo'
b = a + 'World'

#file2.ini:
[constants]
a = 'Hello'

The example below results in an error when file1.ini is included before file2.ini because b would be defined before a:

# file1.ini:
[constants]
b = a + 'World'

#file2.ini:
[constants]
a = 'Hello'

Binaries

The binaries section contains a list of binaries. These can be used internally by meson, or by the find_program function.

These values must be either strings or an array of strings

Compilers and linkers are defined here using <lang> and <lang>_ld. <lang>_ld is special because it is compiler specific. For compilers like gcc and clang which are used to invoke the linker this is a value to pass to their "choose the linker" argument (-fuse-ld= in this case). For compilers like MSVC and Clang-Cl, this is the path to a linker for meson to invoke, such as link.exe or lld-link.exe. Support for ld is new in 0.53.0

changed in 0.53.1 the ld variable was replaced by <lang>_ld, because it *regressed a large number of projects. in 0.53.0 the ld variable was used instead.

Native example:

c = '/usr/bin/clang'
c_ld = 'lld'
sed = 'C:\\program files\\gnu\\sed.exe'
llvm-config = '/usr/lib/llvm8/bin/llvm-config'

Cross example:

c = ['ccache', '/usr/bin/i586-mingw32msvc-gcc']
cpp = ['ccache', '/usr/bin/i586-mingw32msvc-g++']
c_ld = 'gold'
cpp_ld = 'gold'
ar = '/usr/i586-mingw32msvc/bin/ar'
strip = '/usr/i586-mingw32msvc/bin/strip'
pkgconfig = '/usr/bin/i586-mingw32msvc-pkg-config'

An incomplete list of internally used programs that can be overridden here is:

cmake
cups-config
gnustep-config
gpgme-config
libgcrypt-config
libwmf-config
llvm-config
pcap-config
pkgconfig
sdl2-config
wx-config (or wx-3.0-config or wx-config-gtk)

Paths and Directories

Deprecated in 0.56.0 use the built-in section instead.

As of 0.50.0 paths and directories such as libdir can be defined in the native and cross files in a paths section. These should be strings.

[paths]
libdir = 'mylibdir'
prefix = '/my prefix'

These values will only be loaded when not cross compiling. Any arguments on the command line will override any options in the native file. For example, passing --libdir=otherlibdir would result in a prefix of /my prefix and a libdir of otherlibdir.

Properties

New in native files in 0.54.0, always in cross files.

In addition to special data that may be specified in cross files, this section may contain random key value pairs accessed using the meson.get_external_property(), or meson.get_cross_property().

Changed in 0.56.0 putting <lang>_args and <lang>_link_args in the properties section has been deprecated, and should be put in the built-in options section.

Project specific options

New in 0.56.0

Path options are not allowed, those must be set in the [paths] section.

Being able to set project specific options in a cross or native file can be done using the [project options] section of the specific file (if doing a cross build the options from the native file will be ignored)

For setting options in subprojects use the [<subproject>:project options] section instead.

[project options]
build-tests = true

[zlib:project options]
build-tests = false

Meson built-in options

Meson built-in options can be set the same way:

[built-in options]
c_std = 'c99'

You can set some meson built-in options on a per-subproject basis, such as default_library and werror. The order of precedence is:

Command line
Machine file
Build system definitions

[zlib:built-in options]
default_library = 'static'
werror = false

Options set on a per-subproject basis will inherit the option from the parent if the parent has a setting but the subproject doesn't, even when there is a default set meson language.

[built-in options]
default_library = 'static'

will make subprojects use default_library as static.

Some options can be set on a per-machine basis (in other words, the value of the build machine can be different than the host machine in a cross compile). In these cases the values from both a cross file and a native file are used.

An incomplete list of options is:

pkg_config_path
cmake_prefix_path

Loading multiple machine files

Native files allow layering (cross files can be layered since meson 0.52.0). More than one file can be loaded, with values from a previous file being overridden by the next. The intention of this is not overriding, but to allow composing files. This composition is done by passing the command line argument multiple times:

meson setup builddir/ --cross-file first.ini --cross-file second.ini --cross-file thrid.ini

In this case first.ini will be loaded, then second.ini, with values from second.ini replacing first.ini, and so on.

For example, if there is a project using C and C++, python 3.4-3.7, and LLVM 5-7, and it needs to build with clang 5, 6, and 7, and gcc 5.x, 6.x, and 7.x; expressing all of these configurations in monolithic configurations would result in 81 different native files. By layering them, it can be expressed by just 12 native files.

7.2 KiB Raw Blame History