diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Python-module.md | 195 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 24 | ||||
| -rw-r--r-- | docs/markdown/snippets/has-link-argument.md | 9 | ||||
| -rw-r--r-- | docs/markdown/snippets/openmp-dependency.md | 6 | ||||
| -rw-r--r-- | docs/markdown/snippets/python-module.md | 6 | ||||
| -rw-r--r-- | docs/sitemap.txt | 1 | ||||
| -rw-r--r-- | docs/theme/extra/templates/navbar_links.html | 1 |
7 files changed, 238 insertions, 4 deletions
diff --git a/docs/markdown/Python-module.md b/docs/markdown/Python-module.md new file mode 100644 index 0000000..cad74c9 --- /dev/null +++ b/docs/markdown/Python-module.md @@ -0,0 +1,195 @@ +--- +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) +``` + +Get a path as defined by the `sysconfig` module. + +For example: + +``` meson +purelib = py_installation.get_path('purelib') +``` + +This function accepts a single argument, `path_name`, which is expected to +be a non-empty string. + +**Returns**: A string + +#### `get_variable()` + +``` meson +string py_installation.get_variable(variable_name) +``` + +Get a variable as defined by the `sysconfig` module. + +For example: + +``` meson +py_bindir = py_installation.get_variable('BINDIR') +``` + +This function accepts a single argument, `variable_name`, which is expected to +be a non-empty string. + +**Returns**: A string + +## `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 diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index fad6a3c..42abe75 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1508,7 +1508,11 @@ the following methods: - `first_supported_argument(list_of_strings)`, given a list of strings, returns the first argument that passes the `has_argument` - test above or an empty array if none pass. + test or an empty array if none pass. + +- `first_supported_link_argument(list_of_strings)` *(added 0.46.0)*, given a + list of strings, returns the first argument that passes the + `has_link_argument` test or an empty array if none pass. - `get_define(definename)` returns the given preprocessor symbol's value as a string or empty string if it is not defined. @@ -1520,11 +1524,19 @@ the following methods: an array containing only the arguments supported by the compiler, as if `has_argument` were called on them individually. +- `get_supported_link_arguments(list_of_string)` *(added 0.46.0)* returns + an array containing only the arguments supported by the linker, + as if `has_link_argument` were called on them individually. + - `has_argument(argument_name)` returns true if the compiler accepts the specified command line argument, that is, can compile code - without erroring out or printing a warning about an unknown flag, - you can specify external dependencies to use with `dependencies` - keyword argument. + without erroring out or printing a warning about an unknown flag. + +- `has_link_argument(argument_name)` *(added 0.46.0)* returns true if the linker + accepts the specified command line argument, that is, can compile and link + code without erroring out or printing a warning about an unknown flag. Link + arguments will be passed to the compiler, so should usually have the `-Wl,` + prefix. On VisualStudio a `/link` argument will be prepended. - `has_function(funcname)` returns true if the given function is provided by the standard library or a library passed in with the @@ -1559,6 +1571,10 @@ the following methods: `has_argument` but takes multiple arguments and uses them all in a single compiler invocation, available since 0.37.0. +- `has_multi_link_arguments(arg1, arg2, arg3, ...)` *(added 0.46.0)* is the same + as `has_link_argument` but takes multiple arguments and uses them all in a + single compiler invocation. + - `has_type(typename)` returns true if the specified token is a type, you can specify external dependencies to use with `dependencies` keyword argument. diff --git a/docs/markdown/snippets/has-link-argument.md b/docs/markdown/snippets/has-link-argument.md new file mode 100644 index 0000000..7beda63 --- /dev/null +++ b/docs/markdown/snippets/has-link-argument.md @@ -0,0 +1,9 @@ +## has_link_argument() and friends + +A new set of methods has been added on compiler objects to test if the linker +supports given arguments. + +- `has_link_argument()` +- `has_multi_link_arguments()` +- `get_supported_link_arguments()` +- `first_supported_link_argument()` diff --git a/docs/markdown/snippets/openmp-dependency.md b/docs/markdown/snippets/openmp-dependency.md new file mode 100644 index 0000000..ad70011 --- /dev/null +++ b/docs/markdown/snippets/openmp-dependency.md @@ -0,0 +1,6 @@ +## Addition of OpenMP dependency + +An OpenMP dependency (`openmp`) has been added that encapsulates the various +flags used by compilers to enable OpenMP and checks for the existence of the +`omp.h` header. The `language` keyword may be passed to force the use of a +specific compiler for the checks. diff --git a/docs/markdown/snippets/python-module.md b/docs/markdown/snippets/python-module.md new file mode 100644 index 0000000..c2e8138 --- /dev/null +++ b/docs/markdown/snippets/python-module.md @@ -0,0 +1,6 @@ +## Generic python module + +This is a revamped and generic (python 2 and 3) version of the python3 +module. With this new interface, projects can now fully specify the version +of python they want to build against / install sources to, and can do so +against multiple major or minor versions in parallel. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 844b600..b439b69 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -32,6 +32,7 @@ index.md i18n-module.md Icestorm-module.md Pkgconfig-module.md + Python-module.md Python-3-module.md Qt4-module.md Qt5-module.md diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html index 8f3da63..2edce24 100644 --- a/docs/theme/extra/templates/navbar_links.html +++ b/docs/theme/extra/templates/navbar_links.html @@ -8,6 +8,7 @@ @for tup in (("Gnome-module.html","GNOME"), \ ("i18n-module.html","i18n"), \ ("Pkgconfig-module.html","Pkgconfig"), \ + ("Python-module.html","Python"), \ ("Python-3-module.html","Python 3"), \ ("Qt4-module.html","Qt4"), \ ("Qt5-module.html","Qt5"), \ |