Document and test new WrapDB auto fallback

4 files changed, 44 insertions, 0 deletions

diff --git a/docs/markdown/Using-wraptool.md b/docs/markdown/Using-wraptool.md
index cabdc0e..edbceaa 100644
--- a/docs/markdown/Using-wraptool.md
+++ b/docs/markdown/Using-wraptool.md
@@ -82,3 +82,17 @@ straightforward:
 Wraptool can do other things besides these. Documentation for these
 can be found in the command line help, which can be accessed by
 `meson wrap --help`.
+
+## Automatic dependency fallback
+
+Since *0.64.0* Meson can use WrapDB to automatically find missing dependencies.
+
+The user simply needs to download latest database, the following command stores
+it in `subprojects/wrapdb.json`:
+    $ meson wrap update-db
+
+Once the database is available locally, any dependency not found on the system
+but available in WrapDB will automatically be downloaded.
+
+Automatic fetch of WrapDB subprojects can be disabled by removing the file
+`subprojects/wrapdb.json`, or by using `--wrap-mode=nodownload`.
diff --git a/docs/markdown/snippets/wrapdb.md b/docs/markdown/snippets/wrapdb.md
new file mode 100644
index 0000000..d5caf4f
--- /dev/null
+++ b/docs/markdown/snippets/wrapdb.md
@@ -0,0 +1,6 @@
+## Automatic fallback using WrapDB
+
+A new command has been added: `meson wrap update-db`. It downloads the list of
+wraps available in [WrapDB](wrapdb.mesonbuild.com) and stores it locally in
+`subprojects/wrapdb.json`. When that file exists and a dependency is not found
+on the system but is available in WrapDB, Meson will automatically download it.
diff --git a/docs/yaml/functions/dependency.yaml b/docs/yaml/functions/dependency.yaml
index dcb696d..3a4d2e8 100644
--- a/docs/yaml/functions/dependency.yaml
+++ b/docs/yaml/functions/dependency.yaml
@@ -15,6 +15,11 @@ description: |
   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
diff --git a/unittests/platformagnostictests.py b/unittests/platformagnostictests.py
index a2d6640..ed5d96b 100644
--- a/unittests/platformagnostictests.py
+++ b/unittests/platformagnostictests.py
@@ -14,7 +14,10 @@
 
 import os
 import tempfile
+import subprocess
+import textwrap
 from unittest import skipIf
+from pathlib import Path
 
 from .baseplatformtests import BasePlatformTests
 from .helpers import is_ci
@@ -94,3 +97,19 @@ class PlatformAgnosticTests(BasePlatformTests):
         # https://github.com/mesonbuild/meson/issues/10225.
         self.setconf('-Dfoo=enabled')
         self.build('reconfigure')
+
+    def test_update_wrapdb(self):
+        # Write the project into a temporary directory because it will add files
+        # into subprojects/ and we don't want to pollute meson source tree.
+        with tempfile.TemporaryDirectory() as testdir:
+            with Path(testdir, 'meson.build').open('w', encoding='utf-8') as f:
+                f.write(textwrap.dedent(
+                    '''
+                    project('wrap update-db',
+                      default_options: ['wrap_mode=forcefallback'])
+
+                    zlib_dep = dependency('zlib')
+                    assert(zlib_dep.type_name() == 'internal')
+                    '''))
+            subprocess.check_call(self.wrap_command + ['update-db'], cwd=testdir)
+            self.init(testdir, workdir=testdir)