Debian Codegraph @

subprojects/meson-docs/docs/markdown/Pkgconfig-module.md

raw
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).