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