| 1 |
name: dependency |
| 2 |
returns: dep |
| 3 |
description: | |
| 4 |
Finds an external dependency (usually a library installed on your |
| 5 |
system) with the given name with `pkg-config` and [with |
| 6 |
CMake](Dependencies.md#cmake) if `pkg-config` fails. Additionally, |
| 7 |
frameworks (OSX only) and [library-specific fallback detection |
| 8 |
logic](Dependencies.md#dependencies-with-custom-lookup-functionality) |
| 9 |
are also supported. |
| 10 |
|
| 11 |
*Since 0.60.0* more than one name can be provided, they will be tried in order |
| 12 |
and the first name to be found will be used. The fallback subproject will be |
| 13 |
used only if none of the names are found on the system. Once one of the name has |
| 14 |
been found, all other names are added into the cache so subsequent calls for any |
| 15 |
of those name will return the same value. This is useful in case a dependency |
| 16 |
could have different names, such as `png` and `libpng`. |
| 17 |
|
| 18 |
* Since *0.64.0* a dependency fallback can be provided by WrapDB. Simply download |
| 19 |
the database locally using `meson wrap update-db` command and Meson will |
| 20 |
automatically fallback to subprojects provided by WrapDB if the dependency is |
| 21 |
not found on the system and the project does not ship their own `.wrap` file. |
| 22 |
|
| 23 |
Dependencies can also be resolved in two other ways: |
| 24 |
|
| 25 |
* if the same name was used in a `meson.override_dependency` prior to |
| 26 |
the call to `dependency`, the overriding dependency will be returned |
| 27 |
unconditionally; that is, the overriding dependency will be used |
| 28 |
independent of whether an external dependency is installed in the system. |
| 29 |
Typically, `meson.override_dependency` will have been used by a |
| 30 |
subproject. |
| 31 |
|
| 32 |
* by a fallback subproject which, if needed, will be brought into the current |
| 33 |
build specification as if [`subproject()`](#subproject) had been called. |
| 34 |
The subproject can be specified with the `fallback` argument. Alternatively, |
| 35 |
if the `fallback` argument is absent, *since 0.55.0* Meson can |
| 36 |
automatically identify a subproject as a fallback if a wrap file |
| 37 |
[provides](Wrap-dependency-system-manual.md#provide-section) the |
| 38 |
dependency, or if a subproject has the same name as the dependency. |
| 39 |
In the latter case, the subproject must use `meson.override_dependency` to |
| 40 |
specify the replacement, or Meson will report a hard error. See the |
| 41 |
[Wrap documentation](Wrap-dependency-system-manual.md#provide-section) |
| 42 |
for more details. This automatic search can be controlled using the |
| 43 |
`allow_fallback` keyword argument. |
| 44 |
|
| 45 |
If `dependency_name` is `''`, the dependency is always not found. So |
| 46 |
with `required: false`, this always returns a dependency object for |
| 47 |
which the `found()` method returns `false`, and which can be passed |
| 48 |
like any other dependency to the `dependencies:` keyword argument of a |
| 49 |
`build_target`. This can be used to implement a dependency which is |
| 50 |
sometimes not required e.g. in some branches of a conditional, or with |
| 51 |
a `fallback:` kwarg, can be used to declare an optional dependency |
| 52 |
that only looks in the specified subproject, and only if that's |
| 53 |
allowed by `--wrap-mode`. |
| 54 |
|
| 55 |
The returned object [[@dep]] also has additional methods. |
| 56 |
|
| 57 |
notes: |
| 58 |
- This function supports additional [library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality) |
| 59 |
keyword arguments that may also be accepted (e.g. `modules` specifies submodules to use for |
| 60 |
dependencies such as Qt5 or Boost. `components` allows the user to manually |
| 61 |
add CMake `COMPONENTS` for the `find_package` lookup) |
| 62 |
|
| 63 |
varargs: |
| 64 |
name: names |
| 65 |
type: str |
| 66 |
since: 0.60.0 |
| 67 |
min_varargs: 1 |
| 68 |
description: | |
| 69 |
The names of the dependency to look up. The dependencies are looked up in |
| 70 |
the order they are provided here. The first found dependency will then be |
| 71 |
used. The fallback subproject will be used only if none of the names are |
| 72 |
found on the system. Once one of the name has been found, all other names |
| 73 |
are added into the cache so subsequent calls for any of those name will |
| 74 |
return the same value. This is useful in case a dependency could have |
| 75 |
different names, such as `png` and `libpng`. |
| 76 |
|
| 77 |
**NOTE:** Before *0.60.0* only a single dependency name was allowed. |
| 78 |
|
| 79 |
kwargs: |
| 80 |
default_options: |
| 81 |
type: list[str] | dict[str | bool | int | list[str]] |
| 82 |
since: 0.38.0 |
| 83 |
description: | |
| 84 |
An array of default option values |
| 85 |
that override those set in the subproject's `meson.options` |
| 86 |
(like `default_options` in [[project]], they only have |
| 87 |
effect when Meson is run for the first time, and command line |
| 88 |
arguments override any default options in build files) |
| 89 |
*(since 1.2.0)*: A dictionary may now be passed. |
| 90 |
|
| 91 |
allow_fallback: |
| 92 |
type: bool |
| 93 |
since: 0.56.0 |
| 94 |
description: | |
| 95 |
Specifies whether Meson should automatically pick a fallback subproject |
| 96 |
in case the dependency |
| 97 |
is not found in the system. If `true` and the dependency is not found |
| 98 |
on the system, Meson will fallback to a subproject that provides this |
| 99 |
dependency. If `false`, Meson will not fallback even if a subproject |
| 100 |
provides this dependency. By default, Meson will do so if `required` |
| 101 |
is `true` or [`enabled`](Build-options.md#features); see the [Wrap |
| 102 |
documentation](Wrap-dependency-system-manual.md#provide-section) |
| 103 |
for more details. |
| 104 |
|
| 105 |
fallback: |
| 106 |
type: list[str] | str |
| 107 |
description: | |
| 108 |
Manually specifies a subproject fallback |
| 109 |
to use in case the dependency is not found in the system. |
| 110 |
This is useful if the automatic search is not applicable or if you |
| 111 |
want to support versions of Meson older than 0.55.0. If the value is an |
| 112 |
array `['subproj_name', 'subproj_dep']`, the first value is the name |
| 113 |
of the subproject and the second is the variable name in that |
| 114 |
subproject that contains a dependency object such as the return |
| 115 |
value of [[declare_dependency]] or |
| 116 |
[[dependency]], etc. Note that this means the |
| 117 |
fallback dependency may be a not-found dependency, in which |
| 118 |
case the value of the `required:` kwarg will be obeyed. |
| 119 |
*Since 0.54.0* the value can be a single string, the subproject name; |
| 120 |
in this case the subproject must use |
| 121 |
`meson.override_dependency('dependency_name', subproj_dep)` |
| 122 |
to specify the dependency object used in the superproject. |
| 123 |
If the value is an empty list, it has the same effect as |
| 124 |
`allow_fallback: false`. |
| 125 |
|
| 126 |
language: |
| 127 |
type: str |
| 128 |
since: 0.42.0 |
| 129 |
description: | |
| 130 |
Defines what language-specific dependency to find |
| 131 |
if it's available for multiple languages. |
| 132 |
|
| 133 |
method: |
| 134 |
type: str |
| 135 |
since: 0.40.0 |
| 136 |
default: "'auto'" |
| 137 |
description: | |
| 138 |
Defines the way the dependency is detected, the default is |
| 139 |
`auto` but can be overridden to be e.g. `qmake` for Qt development, |
| 140 |
and [different dependencies support different values]( |
| 141 |
Dependencies.md#dependencies-with-custom-lookup-functionality) |
| 142 |
for this (though `auto` will work on all of them) |
| 143 |
|
| 144 |
native: |
| 145 |
type: bool |
| 146 |
default: false |
| 147 |
description: | |
| 148 |
If set to `true`, causes Meson to find the dependency on |
| 149 |
the build machine system rather than the host system (i.e. where the |
| 150 |
cross compiled binary will run on), usually only needed if you build |
| 151 |
a tool to be used during compilation. |
| 152 |
|
| 153 |
not_found_message: |
| 154 |
type: str |
| 155 |
since: 0.50.0 |
| 156 |
description: An optional string that will be printed as a [[message]] if the dependency was not found. |
| 157 |
|
| 158 |
required: |
| 159 |
type: bool | feature |
| 160 |
default: true |
| 161 |
description: | |
| 162 |
When set to `false`, Meson will proceed with the build |
| 163 |
even if the dependency is not found. |
| 164 |
|
| 165 |
When set to a [`feature`](Build-options.md#features) option, the feature |
| 166 |
will control if it is searched and whether to fail if not found. |
| 167 |
|
| 168 |
*(since 0.47.0)* The value of a `feature` option can also be passed. |
| 169 |
|
| 170 |
static: |
| 171 |
type: bool |
| 172 |
description: | |
| 173 |
Tells the dependency provider to try to get static |
| 174 |
libraries instead of dynamic ones (note that this is not supported |
| 175 |
by all dependency backends) |
| 176 |
|
| 177 |
*Since 0.60.0* it also sets `default_library` option accordingly on the fallback |
| 178 |
subproject if it was not set explicitly in `default_options` keyword argument. |
| 179 |
|
| 180 |
*Since 0.63.0* when the `prefer_static` option is set to `true` the default |
| 181 |
value is `true` otherwise the default value is `false`. |
| 182 |
|
| 183 |
version: |
| 184 |
type: list[str] | str |
| 185 |
since: 0.37.0 |
| 186 |
description: | |
| 187 |
Specifies the required version, |
| 188 |
a string containing a |
| 189 |
comparison operator followed by the version string, examples include |
| 190 |
`>1.0.0`, `<=2.3.5` or `3.1.4` for exact matching. |
| 191 |
You can also specify multiple restrictions by passing a list to this |
| 192 |
keyword argument, such as: `['>=3.14.0', '<=4.1.0']`. |
| 193 |
These requirements are never met if the version is unknown. |
| 194 |
|
| 195 |
include_type: |
| 196 |
type: str |
| 197 |
default: "'preserve'" |
| 198 |
since: 0.52.0 |
| 199 |
description: | |
| 200 |
An enum flag, marking how the dependency |
| 201 |
flags should be converted. Supported values are `'preserve'`, `'system'` and |
| 202 |
`'non-system'`. System dependencies may be handled differently on some |
| 203 |
platforms, for instance, using `-isystem` instead of `-I`, where possible. |
| 204 |
If `include_type` is set to `'preserve'`, no additional conversion will be |
| 205 |
performed. |
| 206 |
|
| 207 |
disabler: |
| 208 |
type: bool |
| 209 |
default: false |
| 210 |
since: 0.49.0 |
| 211 |
description: | |
| 212 |
Returns a [[disabler]] object instead of a not-found dependency |
| 213 |
if this kwarg is set to `true` and the dependency couldn't be found. |