diff options
Diffstat (limited to 'docs/yaml/functions/dependency.yaml')
| -rw-r--r-- | docs/yaml/functions/dependency.yaml | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/docs/yaml/functions/dependency.yaml b/docs/yaml/functions/dependency.yaml new file mode 100644 index 0000000..dcb696d --- /dev/null +++ b/docs/yaml/functions/dependency.yaml @@ -0,0 +1,200 @@ +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`. + + 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. |