1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
.. SPDX-FileCopyrightText: 2023 The meson-python developers
..
.. SPDX-License-Identifier: MIT
:orphan:
.. _explanations-design-old:
*******************************
How does ``meson-python`` work?
*******************************
.. admonition:: Old documentation
:class: attention
You are looking at the old documentation. We are currently in the process of
refactoring the whole documentation and this page was part of the old
version. While it still contains lots of relevant information, it is not
necessarily in the format we ultimately want to present, and is not well
integrated with the other parts of the documentation.
How does it work?
=================
We implement the Python build system hooks, enabling any standards compliant
Python tool (pip_, `pypa/build`_, etc.) to build and install the project.
``meson-python`` will build a Python sdist (source distribution) or
wheel (binary distribution) from Meson_ project.
Binary distribution (wheels)
----------------------------
The binary distribution is built by running Meson_ and introspecting the build
and trying to map the files to their correct location. Due to some limitations
and/or bugs in Meson_, we might not be able to map some of the files with
certainty. In these cases, we will take the safest approach and warn the user.
In some cases, we might need to resort to heuristics to perform the mapping,
similarly, the user will be warned. These warnings are not necessarily a reason
for concern, they are there to help identifying issues. In these cases, we
recommend that you check if the files in question were indeed mapped to the
expected place, and open a bug report if they weren't.
If the project itself includes shared libraries that are needed by other files,
those libraries will be included in the wheel, and native files will have their
library search path extended to include the directory where the libraries are
placed.
If the project depends on external shared libraries, those libraries will not
be included in the wheel. This can be handled in several ways by the package
developer using ``meson-python``:
1. Finding or creating a suitable Python package that provides those shared
libraries and can be added to ``dependencies`` in ``pyproject.toml``.
2. Vendoring those libraries into the wheel. Currently ``meson-python`` does
not provide an OS-agnostic way of doing that; on Linux ``auditwheel`` can be
used, and on macOS ``delocate``. Or, the package developer can copy the
shared libraries into the source tree and patch ``meson.build`` files to
include them.
3. Documenting that the dependency is assumed to already be installed on the
end user's system, and letting the end user install it themselves (e.g.,
through their Linux distro package manager).
.. _pip: https://github.com/pypa/pip
.. _pypa/build: https://github.com/pypa/build
.. _Meson: https://github.com/mesonbuild/meson
|
