wrap: Add 'provide' section

3 files changed, 41 insertions, 2 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 293e41f..9bca74b 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -458,7 +458,9 @@ arguments:
   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 used `meson.override_dependency('dependency_name', subproj_dep)`.
+  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.
 - `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
diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md
index e59a6be..cb7c6d6 100644
--- a/docs/markdown/Wrap-dependency-system-manual.md
+++ b/docs/markdown/Wrap-dependency-system-manual.md
@@ -105,7 +105,7 @@ of downloading the file, even if `--wrap-mode` option is set to
   valid value (such as a git tag) for the VCS's `checkout` command, or
   (for git) `head` to track upstream's default branch. Required.
 
-## Specific to wrap-git
+### Specific to wrap-git
 - `depth` - shallowly clone the repository to X number of commits. Note
   that git always allow shallowly cloning branches, but in order to
   clone commit ids shallowly, the server must support
@@ -138,6 +138,36 @@ put them somewhere where you can download them.
 Meson build patches are only supported for wrap-file mode. When using
 wrap-git, the repository must contain all Meson build definitions.
 
+## `provide` section
+
+*Since *0.55.0*
+
+Wrap files can define the dependencies it provides in the `[provide]` section.
+When a wrap file provides the dependency `foo` any call do `dependency('foo')`
+will automatically fallback to that subproject even if no `fallback` keyword
+argument is given. Each entry in the format `dependency_name = variable_name`,
+where `dependency_name` usually match the corresponding pkg-config name and
+`variable_name` is the name of a variable defined in the subproject that should
+be returned for that dependency. In the case the subproject uses
+`meson.override_dependency('foo', foo_dep)` the `variable_name` can be left empty
+in the wrap file.
+
+For example `glib.wrap` provides `glib-2.0`, `gobject-2.0` and `gio-2.0`. A wrap
+file for glib would look like:
+```ini
+[wrap-git]
+url=https://gitlab.gnome.org/GNOME/glib.git
+revision=glib-2-62
+
+[provide]
+glib-2.0=glib_dep
+gobject-2.0=gobject_dep
+gio-2.0=gio_dep
+```
+
+With such wrap file, `dependency('glib-2.0')` will automatically fallback to use
+`glib.wrap` and return `glib_dep` variable from the subproject.
+
 ## Using wrapped projects
 
 Wraps provide a convenient way of obtaining a project into your subproject directory.
diff --git a/docs/markdown/snippets/implicit_fallback.md b/docs/markdown/snippets/implicit_fallback.md
index 87003d0..bad1c71 100644
--- a/docs/markdown/snippets/implicit_fallback.md
+++ b/docs/markdown/snippets/implicit_fallback.md
@@ -7,3 +7,10 @@ That means that simply adding `subprojects/foo.wrap` is enough to add fallback
 to any `dependency('foo')` call. It is however requires that the subproject call
 `meson.override_dependency('foo', foo_dep)` to specify which dependency object
 should be used for `foo`.
+
+## Wrap file `provide` section
+
+Wrap files can define the dependencies it provides in the `[provide]` section.
+When a wrap file provides the dependency `foo` any call do `dependency('foo')`
+will automatically fallback to that subproject even if no `fallback` keyword
+argument is given. See [Wrap documentation](Wrap-dependency-system-manual.md#provide_section).