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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
.. SPDX-FileCopyrightText: 2023 The meson-python developers
..
.. SPDX-License-Identifier: MIT
.. _how-to-guides-meson-args:
**************************
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.
.. _Meson documentation: https://mesonbuild.com/Commands.html
.. _ninja documentation: https://ninja-build.org/manual.html#_running_ninja
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:
.. code-block:: toml
[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`` :ref:`config settings <how-to-guides-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
:ref:`settings <explanations-default-options>` 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 :ref:`example
<vsenv-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.
__ https://mesonbuild.com/Commands.html#backend-specific-arguments
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``:
.. code-block:: toml
[tool.meson-python.args]
setup = ['--default-library=static']
To set this option temporarily at build-time:
.. tab-set::
.. tab-item:: pypa/build
:sync: key_pypa_build
.. code-block:: console
$ python -m build -Csetup-args="--default-library=static" .
.. tab-item:: pip
:sync: key_pip
.. code-block:: console
$ 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.
.. _installation tags: https://mesonbuild.com/Installing.html#installation-tags
To set this option permanently in the project's ``pyproject.toml``:
.. code-block:: toml
[tool.meson-python.args]
install = ['--tags=runtime,python-runtime']
To set this option temporarily at build-time:
.. tab-set::
.. tab-item:: pypa/build
:sync: key_pypa_build
.. code-block:: console
$ python -m build -Cinstall-args="--tags=runtime,python-runtime" .
.. tab-item:: pip
:sync: key_pip
.. code-block:: console
$ 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``:
.. code-block:: toml
[tool.meson-python.args]
setup = ['-Doptimization=3']
To set this option temporarily at build-time:
.. tab-set::
.. tab-item:: pypa/build
:sync: key_pypa_build
.. code-block:: console
$ python -m build -Csetup-args="-Doptimization=3" .
.. tab-item:: pip
:sync: key_pip
.. code-block:: console
$ python -m pip wheel --config-settings=setup-args="-Doptimization=3" .
.. _vsenv-example:
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``:
.. code-block:: toml
[tool.meson-python.args]
setup = ['--vsenv']
To set this option temporarily at build-time:
.. tab-set::
.. tab-item:: pypa/build
:sync: key_pypa_build
.. code-block:: console
$ python -m build -Csetup-args="--vsenv" .
.. tab-item:: pip
:sync: key_pip
.. code-block:: console
$ python -m pip wheel --config-settings=setup-args="--vsenv" .
|
