Skip to content

Commit 87435a5

Browse files
peter-urbanpeter-urban
authored
DOC: add documentation for Meson arguments
1 parent 4ee0bea commit 87435a5

File tree

1 file changed

+166
-4
lines changed

1 file changed

+166
-4
lines changed

‎docs/how-to-guides/meson-args.rst

Lines changed: 166 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,176 @@
88
Passing arguments to Meson_
99
***************************
1010

11-
1211
.. todo::
1312

14-
- Explain how you can add extra Meson arguments via ``pyproject.toml``
15-
- Explain how you can add extra Meson arguments via the build config
16-
settings
1713
- Mention the order in which Meson arguments are added, and how it affect
1814
Meson
1915

16+
Advanced Meson options can be accessed by specifying extra arguments to the
17+
individual Meson commands:
18+
19+
- meson dist: https://mesonbuild.com/Commands.html#dist
20+
- meson setup: https://mesonbuild.com/Commands.html#setup
21+
- meson compile: https://mesonbuild.com/Commands.html#compile
22+
- meson install: https://mesonbuild.com/Commands.html#install
23+
24+
These arguments can be added permanently to the project by adding a section
25+
to the project's ``pyproject.toml``:
26+
27+
.. code-block:: toml
28+
29+
[tool.meson-python.args]
30+
dist = ['dist-argument_1', 'dist-argument_2', '...']
31+
setup = ['setup-argument_1', 'setup-argument_2', '...']
32+
compile = ['compile-argument_1', 'compile-argument_2', '...']
33+
install = ['install-argument_1', 'install-argument_2', '...']
34+
35+
They can also be temporarily overwritten at build time using the
36+
:ref:`build config settings<how-to-guides-config-settings>`.
37+
38+
.. tab-set::
39+
40+
.. tab-item:: pypa/buid
41+
:sync: key_pypa_build
42+
43+
.. code-block:: console
44+
45+
$ python -m build -Cdist-args="args" \
46+
-Csetup-args="args" \
47+
-Ccompile-args="args" \
48+
-Cinstall-args="args" .
49+
50+
.. tab-item:: pip
51+
:sync: key_pip
52+
53+
.. code-block:: console
54+
55+
$ python -m pip --config-settings=dist-args="args" \
56+
--config-settings=setup-args="args" \
57+
--config-settings=compile-args="args" \
58+
--config-settings=install-args="args" .
59+
60+
61+
Examples
62+
========
63+
64+
1) Set the default libraries to *static*
65+
------------------------------------------------
66+
67+
Set the default library type to *static* when building a binary wheel.
68+
69+
To set this option permanently in the project's ``pyproject.toml``:
70+
71+
.. code-block:: toml
72+
73+
[tool.meson-python.args]
74+
dist = []
75+
setup = ['--default-library=static']
76+
compile = []
77+
install = []
78+
79+
To set this option temporarily at build-time:
80+
81+
.. tab-set::
82+
83+
.. tab-item:: pypa/build
84+
:sync: key_pypa_build
85+
86+
.. code-block:: console
87+
88+
$ python -m build -Csetup-args="--default-library=static" .
89+
90+
.. tab-item:: pip
91+
:sync: key_pip
92+
93+
.. code-block:: console
94+
95+
$ python -m pip --config-settings=setup-args="--default-library=static" .
96+
97+
98+
2) Use Meson install_tags for selective installs
99+
------------------------------------------------
100+
101+
Meson install_tags can be used (since ``meson-python`` >= 0.13) to select which
102+
targets are installed into the binary wheels. This example causes meson-python
103+
to only install targets tagged with ``runtime`` or ``python-runtime``) into the
104+
binary wheel (ignoring e.g. C++ headers).
105+
106+
To set this option permanently in the project's ``pyproject.toml``:
107+
108+
.. code-block:: toml
109+
110+
[tool.meson-python.args]
111+
dist = []
112+
setup = []
113+
compile = []
114+
install = ['--tags=runtime,python-runtime']
115+
116+
To set this option temporarily at build-time:
117+
118+
.. tab-set::
119+
120+
.. tab-item:: pypa/build
121+
:sync: key_pypa_build
122+
123+
.. code-block:: console
124+
125+
$ python -m build -install-args="--tags=runtime,python-runtime" .
126+
127+
.. tab-item:: pip
128+
:sync: key_pip
129+
130+
.. code-block:: console
131+
132+
$ python -m pip --config-settings=install-args="--tags=runtime,python-runtime" .
133+
134+
135+
.. admonition:: Meson installation tags
136+
:class: seealso
137+
138+
Each Meson target has a default install_tag (e.g. ``runtime`` for shared
139+
libraries and ``devel`` for headers.). Calling
140+
``meson install --tags=tag1,tag2,...`` will cause Meson to only install
141+
the targets tagged with any of the specified tags. The default tag of
142+
each target can be overwritten using the target's "install_tag" option.
143+
For more information refer Mesons documentation in installation-tags:
144+
https://mesonbuild.com/Installing.html#installation-tags
145+
146+
147+
3) Set the build optimization level to 3
148+
----------------------------------------
149+
150+
The default compile optimization level when building a binary wheel is
151+
currently set to 2. This can be overwritten by passing the
152+
``-Doptimization`` argument to the ``meson setup`` command.
153+
154+
To set this option permanently in the project's ``pyproject.toml``:
155+
156+
.. code-block:: toml
157+
158+
[tool.meson-python.args]
159+
dist = []
160+
setup = ['-Doptimization=3;]
161+
compile = []
162+
install = []
163+
164+
To set this option temporarily at build-time:
165+
166+
.. tab-set::
167+
168+
.. tab-item:: pypa/build
169+
:sync: key_pypa_build
170+
171+
.. code-block:: console
172+
173+
$ python -m build -Csetup-args="-Doptimization=3" .
174+
175+
.. tab-item:: pip
176+
:sync: key_pip
177+
178+
.. code-block:: console
179+
180+
$ python -m pip --config-settings=setup-args="-Doptimization=3" .
181+
20182

21183
.. _Meson: https://github.com/mesonbuild/meson

0 commit comments

Comments
 (0)