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=enable', '-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 Python wheel. User options specified via pyproject.toml or via Python build front-end config settings can be used to override the meson-python defaults..

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 -install-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" .