Passing arguments to Meson

meson-python invokes the meson setup, ninja, and meson install commands to build the files that will be included in the Python wheel, and meson dist to collect the files that will be included in the Python sdist. Arguments can be passed to these commands to modify their behavior. Refer to the Meson documentation and to the ninja documentation for details.

Command line arguments for meson and ninja can be specified via tool specific settings in pyproject.toml as lists of strings for the setup, compile, install, and dist keys in the tool.meson-python.args table. For example:

[tool.meson-python.args]
setup = ['-Doption=false', '-Dfeature=enabled', '-Dvalue=42']
compile = ['-j4']
install = ['--tags=bindings']
dist = ['--include-subprojects']

Or can be specified via configuration settings passed by the Python build front-end as setup-args, compile-args, install-args, and dist-args config settings. Configuration settings specified via the Python build front-end have precedence over, and can be used to override, the ones specified in pyproject.toml.

meson-python overrides some of the default Meson options with settings more appropriate for building a Python wheel. User options specified via pyproject.toml or via Python build front-end config settings override the meson-python defaults.

When building on Windows, meson-python invokes the ninja command via the meson compile wrapper. When the GCC or the LLVM compilers are not found on the $PATH, this activates the Visual Studio environment and allows ninja to use the MSVC compilers. To activate the Visual Studio environment unconditionally, pass the --vsenv option to meson setup, see this example. When using the meson compile wrapper, the user supplied options for the compilation command are passed via the --ninja-args option. This ensures that the behaviour is independent of how the build is initiated. Refer to the Meson documentation for more details.

Examples

Set the default libraries to static

Set the default library type to static when building a binary wheel.

To set this option permanently in the project’s pyproject.toml:

[tool.meson-python.args]
setup = ['--default-library=static']

To set this option temporarily at build-time:

$ python -m build -Csetup-args="--default-library=static" .

$ python -m pip wheel --config-settings=setup-args="--default-library=static" .

Select the build targets to include in the wheel

It is possible to include in the Python wheel only a subset of the installable files using Meson installation tags via the meson install’s --tags command line option. When --tags is specified, only files that have one of the specified the tags are going to be installed.

Meson sets predefined tags on some files. Custom installation tags can be set using the install_tag keyword argument passed to the target definition function. In this example only targets tagged with runtime or python-runtime are included in the Python wheel.

To set this option permanently in the project’s pyproject.toml:

[tool.meson-python.args]
install = ['--tags=runtime,python-runtime']

To set this option temporarily at build-time:

$ python -m build -Cinstall-args="--tags=runtime,python-runtime" .

$ python -m pip wheel --config-settings=install-args="--tags=runtime,python-runtime" .

Set the build optimization level

The default compile optimization level when building a binary wheel is currently set to 2. This can be overwritten by passing the -Doptimization argument to the meson setup command.

To set this option permanently in the project’s pyproject.toml:

[tool.meson-python.args]
setup = ['-Doptimization=3']

To set this option temporarily at build-time:

$ python -m build -Csetup-args="-Doptimization=3" .

$ python -m pip wheel --config-settings=setup-args="-Doptimization=3" .

Force the use of the MSVC compilers on Windows

The MSVC compilers are not installed in the $PATH. The Visual Studio environment needs to be activated for ninja to be able to use these compilers. This is taken care of by meson compile but only when the GCC compilers or the LLVM compilers are not found on the $PATH. Passing the --vsenv option to meson setup forces the activation of the Visual Studio environment and generates an error when the activation fails.

This option has no effect on other platforms thus, if your project requires to be compiled with MSVC, you can consider to set this option permanently in the project’s pyproject.toml:

[tool.meson-python.args]
setup = ['--vsenv']

To set this option temporarily at build-time:

$ python -m build -Csetup-args="--vsenv" .

$ python -m pip wheel --config-settings=setup-args="--vsenv" .