The Meson Build System http://mesonbuild.com/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

222 lines
6.1 KiB

---
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.
**Returns**: a [python installation][`python_installation` object]
## `python_installation` object
The `python_installation` object is an [external program], with several
added methods.
### Methods
#### `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 [buildtarget object]
#### `dependency()`
``` meson
python_dependency py_installation.dependency(...)
```
This method accepts the same arguments as the standard [dependency] function.
**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:
- `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()`]
#### `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()`].
**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 [dependency 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.
[find_program]: Reference-manual.md#find_program
[shared_module]: Reference-manual.md#shared_module
[external program]: Reference-manual.md#external-program-object
[dependency]: Reference-manual.md#dependency
[install_data]: Reference-manual.md#install-data
[configure_file]: Reference-manual.md#configure-file
[dependency object]: Reference-manual.md#dependency-object
[buildtarget object]: Reference-manual.md#build-target-object