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