Using build config settings

Build config settings can be used to customize some aspects of the build. See the Build config settings reference for a list of the settings implemented by meson-python.

How build config settings are specified depends on the Python package build front-end used. The most popular build front-end are build and pip. These use the --config-settings long command line option or the -C short command line option:

$ python -m build \
    -Csetup-args="-Doption=true" \
    -Csetup-args="-Dvalue=1" \
    -Ccompile-args="-j6"

$ python -m pip wheel . \
    --config-settings=setup-args="-Doption=disable" \
    --config-settings=compile-args="-j6"

Refer to the build and pip documentation for details. This example uses the python -m pip wheel command to build a Python wheel that can be later installed or distributed. To build a package and immediately install it, replace wheel with install. See the Passing arguments to Meson guide for more examples.

Passing multiple settings

Please note that pip prior to 23.1 did not offer a way to set a build config setting to a list of strings: later values for the same key passed to --config-settings override earlier ones, effectively limiting the number of options that can be passed to each command invoked in the build process to one. This limitation has been lifted in pip release 23.1.

Using a persistent build directory

By default, meson-python uses a temporary build directory which is deleted when the build terminates. A persistent build directory allows faster incremental builds and to access build logs and intermediate build artifacts. The build-dir config setting instructs meson-python to use a user-specified build directory which will not be deleted. For example:

$ python -m build -Cbuild-dir=build

$ python -m pip install . -Cbuild-dir=build

After running this command, the build directory will contain all the build artifacts and support files created by meson, ninja and meson-python. The same build directory can be used by subsequent invocations of meson-python, avoiding the need to rebuild the whole project when testing changes during development.

Using a permanent build directory also aids in debugging a failing build by allowing access to build logs and intermediate build outputs, including the Meson introspection files and detailed log. The latter is stored in the meson-logs/meson-log.txt file in the build directory and can be useful to diagnose why a build fails at the project configuration stage. For example, to understand why dependency detection failed, it is often necessary to look at the pkg-config or other dependency detection methods output.

Access to detailed logs and intermediate build outputs is particularly helpful in CI setups where introspecting the build environment is usually more difficult than on a local system. Therefore, it can be useful to show the more detailed log files when the CI build step fails. For example, the following GitHub Actions workflow file snippet shows the detailed Meson setup log when the build fails:

- name: Build the package
  run: python -m build --wheel -Cbuild-dir=build
- name: Show meson-log.txt
  if: failure()
  run: cat build/meson-logs/meson-log.txt

Replacing failure() with always() in the code above will result in the Meson log file always being shown. See the GitHub Actions documentation for more details. Please be aware that the setup log can become very long for complex projects, and the GitHub Actions web interface becomes unresponsive when the running job emits many output lines.