docs/prebuilt: Add an example of how to use a wrap file

When using a pre-built library

1 files changed, 27 insertions, 0 deletions

diff --git a/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md b/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md
index e8adb44..13cd0c0 100644
--- a/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md
+++ b/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md
@@ -42,6 +42,33 @@ compiler flags) might not be compatible. If you do this, then you are
 responsible for verifying that your libraries are compatible, Meson
 will not check things for you.
 
+## Using a wrap file
+
+To make this all work automatically, a project will need a
+[wrap file](Wrap-dependency-system-manual.md#wrap-format), as well as the
+meson.build definition from above. For this example our dependency is called
+`bob`.
+
+The wrap ini (subprojects/bob.wrap):
+```ini
+[wrap-file]
+directory = libbob-1.0
+source_url = https://libbob.example.com/libbob-1.0.zip
+source_filename = libbob-1.0.zip
+source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663
+patch_directory = libbob
+
+[provide]
+dependency_names = bob
+```
+
+Then create `subprojects/packagefiles/libbob/`, and place the `meson.build` from
+above in that directory. With these in place a call to `dependency('bob')` will
+first try standard discovery methods for your system (such as pkg-config, cmake,
+and any built-in meson find methods), and then fall back to using the binary
+wrap if it cannot find the dependency on the system. Meson provides the
+`--force-fallback-for=bob` command line option to force the use of the fallback.
+
 ## Note for Linux libraries
 
 A precompiled linux shared library (.so) requires a soname field to be properly installed. If the soname field is missing, binaries referencing the library will require a hard link to the location of the library at install time (`/path/to/your/project/subprojects/precompiledlibrary/lib.so` instead of `$INSTALL_PREFIX/lib/lib.so`) after installation.