| 1 |
# Pkgconfig module |
| 2 |
|
| 3 |
This module is a simple generator for |
| 4 |
[pkg-config](https://pkg-config.freedesktop.org/) files. |
| 5 |
|
| 6 |
## Usage |
| 7 |
|
| 8 |
```meson |
| 9 |
pkg = import('pkgconfig') |
| 10 |
bar_dep = dependency('bar') |
| 11 |
lib = library('foo', dependencies : [bar]) |
| 12 |
pkg.generate(lib) |
| 13 |
``` |
| 14 |
|
| 15 |
### pkg.generate() |
| 16 |
|
| 17 |
The generated file's properties are specified with the following |
| 18 |
keyword arguments. |
| 19 |
|
| 20 |
- `description` a string describing the library, used to set the `Description:` field |
| 21 |
- `extra_cflags` a list of extra compiler flags to be added to the |
| 22 |
`Cflags` field after the header search path |
| 23 |
- `filebase` the base name to use for the pkg-config file; as an |
| 24 |
example, the value of `libfoo` would produce a pkg-config file called |
| 25 |
`libfoo.pc` |
| 26 |
- `install_dir` the directory to install to, defaults to the value of |
| 27 |
option `libdir` followed by `/pkgconfig` |
| 28 |
- `libraries` a list of built libraries (usually results of |
| 29 |
shared_library) that the user needs to link against. Arbitrary strings can |
| 30 |
also be provided and they will be added into the `Libs` field. Since 0.45.0 |
| 31 |
dependencies of built libraries will be automatically added, see the |
| 32 |
[Implicit dependencies](#implicit-dependencies) section below for the exact |
| 33 |
rules. Since 0.58.0 custom_target() objects are supported as long as they are |
| 34 |
linkable (has known extension such as `.a`, `.so`, etc). |
| 35 |
- `libraries_private` list of built libraries or strings to put in the |
| 36 |
`Libs.private` field. Since 0.45.0 dependencies of built libraries will be |
| 37 |
automatically added, see the [Implicit dependencies](#implicit-dependencies) |
| 38 |
section below for the exact rules. Since 0.58.0 custom_target() objects are |
| 39 |
supported as long as they are linkable (has known extension such as `.a`, |
| 40 |
`.so`, etc). |
| 41 |
- `name` the name of this library, used to set the `Name:` field |
| 42 |
- `subdirs` which subdirs of `include` should be added to the header |
| 43 |
search path, for example if you install headers into |
| 44 |
`${PREFIX}/include/foobar-1`, the correct value for this argument |
| 45 |
would be `foobar-1` |
| 46 |
- `requires` list of strings, pkgconfig-dependencies or libraries that |
| 47 |
`pkgconfig.generate()` was used on to put in the `Requires` field |
| 48 |
- `requires_private` the same as `requires` but for the `Requires.private` field |
| 49 |
- `url` a string with a url for the library |
| 50 |
- `variables` a list of strings with custom variables to add to the |
| 51 |
generated file. The strings must be in the form `name=value` and may |
| 52 |
reference other pkgconfig variables, |
| 53 |
e.g. `datadir=${prefix}/share`. The names `prefix`, `libdir` and |
| 54 |
`includedir` are reserved and may not be used. *Since 0.56.0* it can also be a |
| 55 |
dictionary but ordering of Meson dictionaries are not guaranteed, which could |
| 56 |
cause issues when some variables reference other variables. |
| 57 |
Spaces in values are escaped with `\`, this is required in the case the value is |
| 58 |
a path that and is used in `cflags` or `libs` arguments. *Since 0.59.0* if |
| 59 |
escaping is not desired (e.g. space separate list of values) `unescaped_variables` |
| 60 |
keyword argument should be used instead. *Since 0.62.0* builtin directory variables |
| 61 |
that are referenced are automatically created by default. |
| 62 |
- `uninstalled_variables` used instead of the `variables` keyword argument, when |
| 63 |
generating the uninstalled pkg-config file. Since *0.54.0* |
| 64 |
Spaces in values are escaped with `\`, this is required in the case the value is |
| 65 |
a path that and is used in `cflags` or `libs` arguments. *Since 0.59.0* if |
| 66 |
escaping is not desired (e.g. space separate list of values) |
| 67 |
`unescaped_uninstalled_variables` keyword argument should be used instead. |
| 68 |
- `version` a string describing the version of this library, used to set the |
| 69 |
`Version:` field. (*since 0.46.0*) Defaults to the project version if unspecified. |
| 70 |
- `d_module_versions` a list of module version flags used when compiling |
| 71 |
D sources referred to by this pkg-config file |
| 72 |
- `dataonly` field. (*since 0.54.0*) this is used for architecture-independent |
| 73 |
pkg-config files in projects which also have architecture-dependent outputs. |
| 74 |
- `conflicts` (*since 0.36.0, incorrectly issued a warning prior to 0.54.0*) list of strings to be put in the `Conflicts` field. |
| 75 |
|
| 76 |
Since 0.46 a `StaticLibrary` or `SharedLibrary` object can optionally |
| 77 |
be passed as first positional argument. If one is provided a default |
| 78 |
value will be provided for all required fields of the pc file: |
| 79 |
- `install_dir` is set to `pkgconfig` folder in the same location than the provided library. |
| 80 |
- `description` is set to the project's name followed by the library's name. |
| 81 |
- `name` is set to the library's name. |
| 82 |
|
| 83 |
Since 0.54.0 uninstalled pkg-config files are generated as well. They |
| 84 |
are located in `<build dir>/meson-uninstalled/`. It is sometimes |
| 85 |
useful to build projects against libraries built by Meson without |
| 86 |
having to install them into a prefix. In order to do so, just set |
| 87 |
`PKG_CONFIG_PATH=<builddir>/meson-uninstalled` before building your |
| 88 |
application. That will cause pkg-config to prefer those |
| 89 |
`-uninstalled.pc` files and find libraries and headers from the Meson |
| 90 |
builddir. This is an experimental feature provided on a best-effort |
| 91 |
basis, it might not work in all use-cases. |
| 92 |
|
| 93 |
### Implicit dependencies |
| 94 |
|
| 95 |
The exact rules followed to find dependencies that are implicitly |
| 96 |
added into the pkg-config file have evolved over time. Here are the |
| 97 |
rules as of Meson *0.49.0*, previous versions might have slightly |
| 98 |
different behaviour. |
| 99 |
|
| 100 |
- Not found libraries or dependencies are ignored. |
| 101 |
- Libraries and dependencies are private by default (i.e. added into |
| 102 |
`Requires.private:` or `Libs.private:`) unless they are explicitly added in |
| 103 |
`libraries` or `requires` keyword arguments, or is the main library (first |
| 104 |
positional argument). |
| 105 |
- Libraries and dependencies will be de-duplicated, if they are added in both |
| 106 |
public and private (e.g `Requires:` and `Requires.private:`) it will be removed |
| 107 |
from the private list. |
| 108 |
- Shared libraries (i.e. `shared_library()` and **NOT** `library()`) add only |
| 109 |
`-lfoo` into `Libs:` or `Libs.private:` but their dependencies are not pulled. |
| 110 |
This is because dependencies are only needed for static link. |
| 111 |
- Other libraries (i.e. `static_library()` or `library()`) add `-lfoo` into `Libs:` |
| 112 |
or `Libs.private:` and recursively add their dependencies into `Libs.private:` or |
| 113 |
`Requires.private:`. |
| 114 |
- Dependencies provided by pkg-config are added into `Requires:` or |
| 115 |
`Requires.private:`. If a version was specified when declaring that dependency |
| 116 |
it will be written into the generated file too. |
| 117 |
- The threads dependency (i.e. `dependency('threads')`) adds `-pthread` into |
| 118 |
`Libs:` or `Libs.private:`. |
| 119 |
- Internal dependencies (i.e. |
| 120 |
`declare_dependency(compiler_args : '-DFOO', link_args : '-Wl,something', link_with : foo)`) |
| 121 |
add `compiler_args` into `Cflags:` if public, `link_args` and `link_with` into |
| 122 |
`Libs:` if public or `Libs.private:` if private. |
| 123 |
- Other dependency types add their compiler arguments into `Cflags:` if public, |
| 124 |
and linker arguments into `Libs:` if public or `Libs.private:` if private. |
| 125 |
- Once a pkg-config file is generated for a library using `pkg.generate(mylib)`, |
| 126 |
any subsequent call to `pkg.generate()` where mylib appears, will generate a |
| 127 |
`Requires:` or `Requires.private` instead of a `Libs:` or `Libs.private:`. |
| 128 |
|
| 129 |
### Relocatable pkg-config files |
| 130 |
|
| 131 |
By default, the files generated by `pkg.generate` contain a hardcoded prefix path. |
| 132 |
In order to make them relocatable, a `pkgconfig.relocatable` builtin option is provided. |
| 133 |
See [Pkgconfig module options](Builtin-options.md#pkgconfig-module). |