Skip to content
Back to top
View this page

# 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:

pypa/build

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

pip

    $ python -m pip wheel -Csetup-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:

pypa/build

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

pip

    $ python -m pip wheel -Cinstall-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:

pypa/build

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

pip

    $ python -m pip wheel -Csetup-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']

And in case you don’t want to set `--vsenv` as the default, but do want to build Windows wheels with MSVC in CI using cibuildwheel:

    [tool.cibuildwheel.windows]
    config-settings = { setup-args = ["--vsenv"] }

To set this option temporarily at build-time:

pypa/build

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

pip

    $ python -m pip wheel -Csetup-args="--vsenv" .