Built-in options

b_bitcode will pass -fembed-bitcode while compiling and will pass -Wl,-bitcode_bundle while linking. These options are incompatible with b_asneeded, so that option will be silently disabled.

shared_module()s will not have bitcode embedded because -Wl,-bitcode_bundle is incompatible with both -bundle and -Wl,-undefined,dynamic_lookup which are necessary for shared modules to work.

Compiler options

Same caveats as base options above.

The following options are available. They can be set by passing -Doption=value to meson. Note that both the options themselves and the possible values they can take will depend on the target platform or compiler being used:

The default values of c_winlibs and cpp_winlibs are in compiler-specific argument forms, but the libraries are: kernel32, user32, gdi32, winspool, shell32, ole32, oleaut32, uuid, comdlg32, advapi32.

All these <lang>_* options are specified per machine. See below in the specifying options per machine section on how to do this in cross builds.

When using MSVC, cpp_eh=[value] will result in /EH[value] being passed. The magic value none translates to s-c- to disable exceptions. Since 0.51.0 default translates to sc. When using gcc-style compilers, nothing is passed (allowing exceptions to work), while cpp_eh=none passes -fno-exceptions.

Since 0.54.0 The <lang>_thread_count option can be used to control the value passed to -s PTHREAD_POOL_SIZE when using emcc. No other c/c++ compiler supports this option.

Since 0.63.0 all compiler options can be set per subproject, see here for details on how the default value is inherited from the main project. This is useful, for example, when the main project requires C++11, but a subproject requires C++14. The cpp_std value from the subproject's default_options is now respected.

Since 1.3.0 c_std and cpp_std options now accept a list of values. Projects that prefer GNU C, but can fallback to ISO C, can now set, for example, default_options: 'c_std=gnu11,c11', and it will use gnu11 when available, but fallback to c11 otherwise. It is an error only if none of the values are supported by the current compiler. Likewise, a project that can take benefit of c++17 but can still build with c++11 can set default_options: 'cpp_std=c++17,c++11'. This allows us to deprecate gnuXX values from the MSVC compiler. That means that default_options: 'c_std=gnu11' will now print a warning with MSVC but fallback to c11. No warning is printed if at least one of the values is valid, i.e. default_options: 'c_std=gnu11,c11'. In the future that deprecation warning will become an hard error because c_std=gnu11 should mean GNU is required, for projects that cannot be built with MSVC for example.

Specifying options per machine

Since 0.51.0, some options are specified per machine rather than globally for all machine configurations. Prefixing the option with build. only affects the build machine configuration, while leaving it unprefixed only affects the host machine configuration. For example:

build.pkg_config_path controls the paths pkg-config will search for native: true (build machine) dependencies.

pkg_config_path controls the paths pkg-config will search for native: false (host machine) dependencies.

This is useful for cross builds. In native builds, the build and host machines are the same, and the unprefixed option alone will suffice.

Prior to 0.51.0, these options only affected native builds when specified on the command line as there was no build. prefix. Similarly named fields in the [properties] section of the cross file would affect cross compilers, but the code paths were fairly different, allowing differences in behavior to crop out.

Specifying options per subproject

Since 0.54.0 default_library and werror built-in options can be defined per subproject. This is useful, for example, when building shared libraries in the main project and statically linking a subproject, or when the main project must build with no warnings but some subprojects cannot.

Most of the time, this would be used either in the parent project by setting subproject's default_options (e.g. subproject('foo', default_options: 'default_library=static')), or by the user through the command line: -Dfoo:default_library=static.

The value is overridden in this order:

Since 0.56.0 warning_level can also be defined per subproject.

Module options

Some Meson modules have built-in options. They can be set by prefixing the option with the module's name: -D<module>.<option>=<value> (e.g. -Dpython.platlibdir=/foo).

Pkgconfig module

Since 0.63.0 The pkgconfig.relocatable option is used by the pkgconfig module–namely pkg.generate()–and affects how the prefix (not to be confused with the install prefix) in the generated pkgconfig file is set. When it is true, the prefix will be relative to the install_dir-this allows the pkgconfig file to be moved around and still work, as long as the relative path is not broken. In general, this allows for the whole installed package to be placed anywhere on the system and still work as a dependency. When it is set to false, the prefix will be the same as the install prefix.

An error will be raised if pkgconfig.relocatable is true and the install_dir for a generated pkgconfig file points outside the install prefix. For example: if the install prefix is /usr and the install_dir for a pkgconfig file is /var/lib/pkgconfig.

Python module

Since 0.60.0 The python.platlibdir and python.purelibdir options are used by the python module methods python.install_sources() and python.get_install_dir(); Meson tries to detect the correct installation paths and make them relative to the installation prefix by default which will often result in the interpreter not finding the installed python modules unless prefix is /usr on Linux, or, for instance, C:\Python39 on Windows. These options can be absolute paths outside of prefix.

Since 0.62.0 The python.install_env option is used to detect the correct installation path. Setting to system will avoid making the paths relative to prefix and instead use the global site-packages of the selected python interpreter directly, even if it is a venv. Setting to venv will instead use the paths for the virtualenv the python found installation comes from (or fail if it is not a virtualenv). Setting to auto will check if the found installation is a virtualenv, and use venv or system as appropriate (but never prefix). Note that Conda environments are treated as system. This option is mutually exclusive with the platlibdir/purelibdir.

For backwards compatibility purposes, the default install_env is prefix.

Since 1.2.0 The python.bytecompile option can be used to enable compiling python bytecode. Bytecode has 3 optimization levels:

To this, Meson adds level -1, which is to not attempt to compile bytecode at

Since 1.3.0 The python.allow_limited_api option affects whether the limited_api keyword argument of the extension_module method is respected. If set to false, the effect of the limited_api argument is disabled.