doc: Add warning about --force-fallback-for [skip ci]

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md
index 9c54d69..02a83e6 100644
--- a/docs/markdown/Subprojects.md
+++ b/docs/markdown/Subprojects.md
@@ -236,6 +236,28 @@ the following command-line options:
     but you only want to build against the library sources for a few
     of them.
 
+    **Warning**: This could lead to mixing system and subproject version of the
+    same library in the same process. Take this case as example:
+    - Libraries `glib-2.0` and `gstreamer-1.0` are installed on your system.
+    - `gstreamer-1.0` depends on `glib-2.0`, pkg-config file `gstreamer-1.0.pc`
+      has `Requires: glib-2.0`.
+    - In your application build definition you do:
+      ```meson
+      executable('app', ...,
+        dependencies: [
+          dependency('glib-2.0', fallback: 'glib'),
+          dependency('gstreamer-1.0', fallback: 'gstreamer')],
+      )
+      ```
+    - You configure with `--force-fallback-for=glib`.
+    This result in linking to two different versions of library `glib-2.0`
+    because `dependency('glib-2.0', fallback: 'glib')` will return the
+    subproject dependency, but `dependency('gstreamer-1.0', fallback: 'gstreamer')`
+    will not fallback and return the system dependency, including `glib-2.0`
+    library. To avoid that situation, every dependency that itself depend on
+    `glib-2.0` must also be forced to fallback, in this case with
+    `--force-fallback-for=glib,gsteamer`.
+
 ## Download subprojects
 
 *Since 0.49.0*