From a4f1caa405a378c36cf856fd6e0e4769f3bc856d Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 14 Sep 2020 22:39:32 +0200 Subject: docs: improve documentation of subproject fallback Automatic fallback to subprojects is complicated and should be pointed out outside the "fallback" keyword argument. It is also surprising that fallback to a subproject will not happen if override_dependency has already been used with the request dependency. Document all this. --- docs/markdown/Reference-manual.md | 49 +++++++++++++++++++++++++++------------ 1 file changed, 34 insertions(+), 15 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index c1e509e..b6ca743 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -440,33 +440,52 @@ 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. This function supports the following keyword -arguments: +are also supported. + +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 and `required` is `true` or + [`enabled`](Build-options.md#features), *since 0.55.0* Meson will + 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 function supports the following keyword arguments: - `default_options` *(since 0.37.0)*: an array of default option values that override those set in the subproject's `meson_options.txt` (like `default_options` in [`project()`](#project), they only have effect when Meson is run for the first time, and command line arguments override any default options in build files) -- `fallback`: specifies a subproject fallback to use in case the - dependency is not found in the system. The value is an array - `['subproj_name', 'subproj_dep']` where the first value is the name +- `fallback`: 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`](#declare_dependency) or [`dependency()`](#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)* `'subproj_dep'` argument can be omitted in the case the - subproject used `meson.override_dependency('dependency_name', subproj_dep)`. - In that case, the `fallback` keyword argument can be a single string instead - of a list of 2 strings. *Since 0.55.0* the `fallback` keyword argument can be - omitted when there is a wrap file or a directory with the same `dependency_name`, - and subproject registered the dependency using - `meson.override_dependency('dependency_name', subproj_dep)`, or when the wrap - file has `dependency_name` in its `[provide]` section. - See [Wrap documentation](Wrap-dependency-system-manual.md#provide-section) - for more details. + *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. - `language` *(since 0.42.0)*: defines what language-specific dependency to find if it's available for multiple languages. - `method`: defines the way the dependency is detected, the default is -- cgit v1.1