| 1 |
# External Project module |
| 2 |
|
| 3 |
**Note**: the functionality of this module is governed by [Meson's |
| 4 |
rules on mixing build systems](Mixing-build-systems.md). |
| 5 |
|
| 6 |
*This is an experimental module, API could change.* |
| 7 |
|
| 8 |
*Added 0.56.0* |
| 9 |
|
| 10 |
This module allows building code that uses build systems other than |
| 11 |
Meson. This module is intended to be used to build Autotools |
| 12 |
subprojects as fallback if the dependency couldn't be found on the |
| 13 |
system (e.g. too old distro version). |
| 14 |
|
| 15 |
The project will be compiled out-of-tree inside Meson's build |
| 16 |
directory. The project will also be installed inside Meson's build |
| 17 |
directory using make's |
| 18 |
[`DESTDIR`](https://www.gnu.org/prep/standards/html_node/DESTDIR.html) |
| 19 |
feature. During project installation step, that DESTDIR will be copied |
| 20 |
verbatim into the desired location. |
| 21 |
|
| 22 |
External subprojects can use libraries built by Meson (main project, |
| 23 |
or other subprojects) using pkg-config, thanks to `*-uninstalled.pc` |
| 24 |
files generated by [`pkg.generate()`](Pkgconfig-module.md). |
| 25 |
|
| 26 |
External build system requirements: |
| 27 |
|
| 28 |
- Must support out-of-tree build. The configure script will be invoked with the |
| 29 |
current workdir inside Meson's build directory and not subproject's top source |
| 30 |
directory. |
| 31 |
- Configure script must generate a `Makefile` in the current workdir. |
| 32 |
- Configure script must take common directories like prefix, libdir, etc, as |
| 33 |
command line arguments. |
| 34 |
- Configure script must support common environment variable like CFLAGS, CC, etc. |
| 35 |
- Compilation step must detect when a reconfigure is needed, and do it |
| 36 |
transparently. |
| 37 |
|
| 38 |
Known limitations: |
| 39 |
|
| 40 |
- Executables from external projects cannot be used uninstalled, because they |
| 41 |
would need its libraries to be installed in the final location. This is why |
| 42 |
there is no `find_program()` method. |
| 43 |
- The configure script must generate a `Makefile`, other build systems are not |
| 44 |
yet supported. |
| 45 |
- When cross compiling, if `PKG_CONFIG_SYSROOT_DIR` is set in environment or |
| 46 |
`sys_root` in the cross file properties, the external subproject will not be |
| 47 |
able to find dependencies built by Meson using pkg-config. The reason is |
| 48 |
pkg-config and pkgconf both prepend the sysroot path to `-I` and `-L` arguments |
| 49 |
from `-uninstalled.pc` files. This is arguably a bug that could be fixed in |
| 50 |
future version of pkg-config/pkgconf. |
| 51 |
|
| 52 |
*Since 1.7.0* [Meson devenv][Commands.md#devenv] setup `PATH` and |
| 53 |
`LD_LIBRARY_PATH` to be able to run programs. |
| 54 |
|
| 55 |
## Functions |
| 56 |
|
| 57 |
### `add_project()` |
| 58 |
|
| 59 |
This function should be called at the root directory of a project |
| 60 |
using another build system. Usually in a `meson.build` file placed in |
| 61 |
the top directory of a subproject, but could be also in any subdir. |
| 62 |
|
| 63 |
Its first positional argument is the name of the configure script to |
| 64 |
be executed (e.g. `configure`), that file must be in the current |
| 65 |
directory and executable. Note that if a bootstrap script is required |
| 66 |
(e.g. `autogen.sh` when building from git instead of tarball), it can |
| 67 |
be done using `run_command()` before calling `add_project()` method. |
| 68 |
|
| 69 |
*Since 0.60.0* If the first positional argument is `'waf'`, special treatment |
| 70 |
is done for the [waf](https://waf.io/) build system. The waf executable must be |
| 71 |
found either in the current directory, or in system `PATH`. |
| 72 |
|
| 73 |
Keyword arguments: |
| 74 |
|
| 75 |
- `configure_options`: An array of strings to be passed as arguments to the |
| 76 |
configure script. Some special tags will be replaced by Meson before passing |
| 77 |
them to the configure script: `@PREFIX@`, `@LIBDIR@` and `@INCLUDEDIR@`. |
| 78 |
Note that `libdir` and `includedir` paths are relative to `prefix` in Meson |
| 79 |
but some configure scripts requires absolute path, in that case they can be |
| 80 |
passed as `'--libdir=@PREFIX@/@LIBDIR@'`. *Since 0.57.0* default arguments are |
| 81 |
added in case some tags are not found in `configure_options`: |
| 82 |
`'--prefix=@PREFIX@'`, `'--libdir=@PREFIX@/@LIBDIR@'`, and |
| 83 |
`'--includedir=@PREFIX@/@INCLUDEDIR@'`. It was previously considered a fatal |
| 84 |
error to not specify them. *Since 1.7.0* `@BINDIR@` and `'--bindir=@PREFIX@/@BINDIR@'` |
| 85 |
default argument have been added. |
| 86 |
- `cross_configure_options`: Extra options appended to `configure_options` only |
| 87 |
when cross compiling. special tag `@HOST@` will be replaced by |
| 88 |
`'{}-{}-{}'.format(host_machine.cpu_family(), build_machine.system(), host_machine.system()`. |
| 89 |
If omitted it defaults to `['--host=@HOST@']`. |
| 90 |
- `verbose`: If set to `true` the output of sub-commands ran to configure, build |
| 91 |
and install the project will be printed onto Meson's stdout. |
| 92 |
- `env` : environment variables to set, such as `['NAME1=value1', 'NAME2=value2']`, |
| 93 |
a dictionary, or an [[@env]] object. |
| 94 |
- `depends` : *Since 0.63.0* Specifies that this project depends on the specified |
| 95 |
target(s) that must be built before running `make` to build this external |
| 96 |
project. This should be used for example when the external project links to a |
| 97 |
Meson `library()` that the `configure` script will find using the |
| 98 |
`-uninstalled.pc` pkg-config file generated by Meson. |
| 99 |
|
| 100 |
Returns an [`ExternalProject`](#ExternalProject_object) object |
| 101 |
|
| 102 |
## `ExternalProject` object |
| 103 |
|
| 104 |
### Methods |
| 105 |
|
| 106 |
#### `dependency(libname)` |
| 107 |
|
| 108 |
Return a dependency object that can be used to build targets against a library |
| 109 |
from the external project. |
| 110 |
|
| 111 |
Keyword arguments: |
| 112 |
- `subdir` path relative to `includedir` to be added to the header search path. |
| 113 |
|
| 114 |
## Example `meson.build` file for a subproject |
| 115 |
|
| 116 |
```meson |
| 117 |
project('My Autotools Project', 'c', |
| 118 |
meson_version : '>=0.56.0', |
| 119 |
) |
| 120 |
|
| 121 |
mod = import('unstable-external_project') |
| 122 |
|
| 123 |
p = mod.add_project('configure', |
| 124 |
configure_options : ['--prefix=@PREFIX@', |
| 125 |
'--libdir=@LIBDIR@', |
| 126 |
'--incdir=@INCLUDEDIR@', |
| 127 |
'--enable-foo', |
| 128 |
], |
| 129 |
) |
| 130 |
|
| 131 |
mylib_dep = p.dependency('mylib') |
| 132 |
meson.override_dependency('mylib', mylib_dep) |
| 133 |
``` |
| 134 |
|
| 135 |
## Using wrap file |
| 136 |
|
| 137 |
Most of the time the project will be built as a subproject, and |
| 138 |
fetched using a `.wrap` file. In that case the simple `meson.build` |
| 139 |
file needed to build the subproject can be provided by adding |
| 140 |
`patch_directory=mysubproject` line in the wrap file, and place the |
| 141 |
build definition file at |
| 142 |
`subprojects/packagefiles/mysubproject/meson.build`. |