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
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
---
short-description: Generic python module
authors:
- name: Mathieu Duponchelle
email: mathieu@centricular.com
years: [2018]
has-copyright: false
...
# Python module
This module provides support for finding and building extensions against
python installations, be they python 2 or 3.
*Added 0.46.0*
## Functions
### `find_installation()`
``` meson
pymod.find_installation(name_or_path, ...)
```
Find a python installation matching `name_or_path`.
That argument is optional, if not provided then the returned python
installation will be the one used to run Meson.
If provided, it can be:
- A simple name, eg `python-2.7`, Meson will look for an external program
named that way, using [[find_program]]
- A path, eg `/usr/local/bin/python3.4m`
- One of `python2` or `python3`: in either case, the module will try
some alternative names: `py -2` or `py -3` on Windows, and `python`
everywhere. In the latter case, it will check whether the version
provided by the sysconfig module matches the required major version
Keyword arguments are the following:
- `required`: by default, `required` is set to `true` and Meson will
abort if no python installation can be found. If `required` is set to `false`,
Meson will continue even if no python installation was found. You can
then use the `.found()` method on the returned object to check
whether it was found or not. Since *0.48.0* the value of a
[`feature`](Build-options.md#features) option can also be passed to the
`required` keyword argument.
- `disabler`: if `true` and no python installation can be found, return a
[[@disabler]] object instead of a not-found object.
*Since 0.49.0*
- `modules`: a list of module names that this python installation must have.
*Since 0.51.0*
**Returns**: a [python installation][`python_installation` object]
## `python_installation` object
The `python_installation` object is an [[@external_program]], with several
added methods.
### Methods
#### `path()`
```meson
str py_installation.path()
```
*Added 0.50.0*
Works like the path method of other `ExternalProgram` objects. Was not
provided prior to 0.50.0 due to a bug.
#### `extension_module()`
``` meson
shared_module py_installation.extension_module(module_name, list_of_sources, ...)
```
Create a [[shared_module]] target that is named according to the naming
conventions of the target platform.
All positional and keyword arguments are the same as for
[[shared_module]], excluding `name_suffix` and `name_prefix`, and with
the addition of the following:
- `subdir`: By default, Meson will install the extension module in
the relevant top-level location for the python installation, eg
`/usr/lib/site-packages`. When subdir is passed to this method,
it will be appended to that location. This keyword argument is
mutually exclusive with `install_dir`
`extension_module` does not add any dependencies to the library so
user may need to add `dependencies : py_installation.dependency()`,
see [[dependency]].
**Returns**: a [[@build_tgt]] object
#### `dependency()`
``` meson
python_dependency py_installation.dependency(...)
```
This method accepts no positional arguments, and the same keyword
arguments as the standard [[dependency]] function. It also supports the
following keyword argument:
- `embed`: *(since 0.53.0)* If true, Meson will try to find a python
dependency that can be used for embedding python into an
application.
- `disabler` *(since 0.60.0)*: if `true` and the dependency couldn't be found,
returns a [disabler object](#disabler-object) instead of a not-found dependency.
**Returns**: a [python dependency][`python_dependency` object]
#### `install_sources()`
``` meson
void py_installation.install_sources(list_of_files, ...)
```
Install actual python sources (`.py`).
All positional and keyword arguments are the same as for
[[install_data]], with the addition of the following:
*Since 0.60.0* `python.platlibdir` and `python.purelibdir` options can be used
to control the default installation path. See [Python module options](Builtin-options.md#python-module).
- `pure`: On some platforms, architecture independent files are
expected to be placed in a separate directory. However, if the
python sources should be installed alongside an extension module
built with this module, this keyword argument can be used to
override that behaviour. Defaults to `true`
- `subdir`: See documentation for the argument of the same name to
[][`extension_module()`]
- `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
to install only a subset of the files. By default it has the tag `python-runtime`.
#### `get_install_dir()`
``` meson
string py_installation.get_install_dir(...)
```
Retrieve the directory [][`install_sources()`] will install to.
It can be useful in cases where `install_sources` cannot be used
directly, for example when using [[configure_file]].
This function accepts no arguments, its keyword arguments are the same
as [][`install_sources()`].
*Since 0.60.0* `python.platlibdir` and `python.purelibdir` options can be used
to control the default installation path. See [Python module options](Builtin-options.md#python-module).
**Returns**: A string
#### `language_version()`
``` meson
string py_installation.language_version()
```
Get the major.minor python version, eg `2.7`.
The version is obtained through the `sysconfig` module.
This function expects no arguments or keyword arguments.
**Returns**: A string
#### `get_path()`
``` meson
string py_installation.get_path(path_name, fallback)
```
Get a path as defined by the `sysconfig` module.
For example:
``` meson
purelib = py_installation.get_path('purelib')
```
This function requires at least one argument, `path_name`,
which is expected to be a non-empty string.
If `fallback` is specified, it will be returned if no path
with the given name exists. Otherwise, attempting to read
a non-existing path will cause a fatal error.
**Returns**: A string
#### `has_path()`
``` meson
bool py_installation.has_path(path_name)
```
**Returns**: true if a path named `path_name` can be retrieved with
[][`get_path()`], false otherwise.
#### `get_variable()`
``` meson
string py_installation.get_variable(variable_name, fallback)
```
Get a variable as defined by the `sysconfig` module.
For example:
``` meson
py_bindir = py_installation.get_variable('BINDIR', '')
```
This function requires at least one argument, `variable_name`,
which is expected to be a non-empty string.
If `fallback` is specified, it will be returned if no variable
with the given name exists. Otherwise, attempting to read
a non-existing variable will cause a fatal error.
**Returns**: A string
#### `has_variable()`
``` meson
bool py_installation.has_variable(variable_name)
```
**Returns**: true if a variable named `variable_name` can be retrieved
with [][`get_variable()`], false otherwise.
## `python_dependency` object
This [[@dep]] object subclass will try various methods to obtain
the compiler and linker arguments, starting with pkg-config then
potentially using information obtained from python's `sysconfig`
module.
It exposes the same methods as its parent class.
|