Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/dependency.yaml

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