meson-python

The abi3t stable ABI allows a single wheel (tagged abi3.abi3t) to support both GIL-enabled and free-threaded CPython 3.15 and later.

To target abi3t, you must use a free-threaded interpreter for the build and set the limited_api version to '3.15' or later. You can detect if a build is free-threaded by checking the Py_GIL_DISABLED sysconfig variable (which returns 1 for free-threaded builds).

py = import('python').find_installation(pure: false)

limited_api = '3.10'
if py.language_version().version_compare('>=3.15')
    if py.get_variable('Py_GIL_DISABLED') == 1
        limited_api = '3.15'
    endif
endif

py.extension_module(
    '_core',
    '_core.c',
    limited_api: limited_api,
    install: true,
    subdir: 'example',
)

In editable mode, compiled components are loaded directly from a build directory located inside your source tree.

meson-python names the build directory based on the wheel ABI tag of the interpreter used. For example, a CPython 3.11 installation will use build/cp311/. This structure allows you to maintain different build directories for different Python interpreters within the same source tree.

Configuration: You can specify an alternative build directory using the build-dir config setting.

When using meson-python, avoid installing data files into Meson's {datadir} location if they need to be accessed by your Python code at run-time. While meson-python will include files installed via Meson's install_data() into the resulting wheel, these files are unpacked into platform-specific locations that lack a reliable way to be located at run-time.

Recommended Pattern: Include data files inside the Python package directory alongside your .py source files. Use importlib.resources (or the importlib-resources backport for older Python versions) to access these files reliably at run-time.

While Meson provides many built-in options for controlling builds, meson-python overrides several of them to optimize the process for creating Python wheels.

These overrides are applied in a specific hierarchy:

1. User-provided options: Options passed via the Python build front-end (e.g., using python -m build).
2. Package-specific options: Options defined in your project's pyproject.toml.
3. meson-python defaults: The internal defaults set by meson-python to ensure compatible wheel builds.

You can verify which options are being used by inspecting the User defined options section in the output of the meson setup stage (for example, when running python -m build -w).

The source distribution process in meson-python follows these steps:

1. meson-python runs meson setup to successfully configure the Meson project.
2. It then executes meson dist to create the archive, adding required metadata files.

Because meson dist relies on the underlying revision control system's archival tool, a project must be versioned in Git or Mercurial to create a source distribution. You can pass additional arguments to meson dist to modify its behavior.

Before submitting changes, ensure your code adheres to the project's quality standards by running the following commands:

• ruff check: Runs the linter.
• mypy: Runs the type checker.
• pytest: Runs the test suite.

$ ruff check
$ mypy
$ pytest

Commit messages should be organized with a subject line (briefly describing the commit), a blank line, and an optional body. Lines should be word-wrapped at 72 characters.

The subject line must start with a capitalized acronym followed by a colon to indicate the nature of the change:

• BUG: Bug fixes
• ENH: New features and other enhancements
• TST: Addition or modification of tests
• MAINT: Maintenance commits (refactoring, typos, or code style fixes)
• DOC: Documentation changes
• CI: Changes to the continuous integration setup

To allow Python build front-ends like pip or build to build Python source distributions (sdist) or binary wheels for a Meson project, you must include a pyproject.toml file in the root of your source tree (next to your top-level meson.build file). This file must specify mesonpy as the build backend and include meson-python in the requirements.

[build-system]
build-backend = 'mesonpy'
requires = ['meson-python']