aboutsummaryrefslogtreecommitdiff
path: root/docs/markdown/snippets
diff options
context:
space:
mode:
authorXavier Claessens <xavier.claessens@collabora.com>2018-12-19 20:56:07 -0500
committerXavier Claessens <xavier.claessens@collabora.com>2020-03-06 15:25:46 -0500
commit2fdedc4d0fc73c509669bf9f89863017e0f0989b (patch)
treefcb933a45797f7a1a1ef4516ba709dfd0888f781 /docs/markdown/snippets
parent74769617907f571d2099001d3a7443e23b4f6cda (diff)
downloadmeson-2fdedc4d0fc73c509669bf9f89863017e0f0989b.zip
meson-2fdedc4d0fc73c509669bf9f89863017e0f0989b.tar.gz
meson-2fdedc4d0fc73c509669bf9f89863017e0f0989b.tar.bz2
Add meson.override_dependency()
Similar to meson.override_find_program() but overrides the result of the dependency() function. Also ensure that dependency() always returns the same result when looking for the same dependency, this fixes cases where parts of the project could be using a system library and other parts use the library provided by a subproject.
Diffstat (limited to 'docs/markdown/snippets')
-rw-r--r--docs/markdown/snippets/override_dependency.md59
1 files changed, 59 insertions, 0 deletions
diff --git a/docs/markdown/snippets/override_dependency.md b/docs/markdown/snippets/override_dependency.md
new file mode 100644
index 0000000..875eef8
--- /dev/null
+++ b/docs/markdown/snippets/override_dependency.md
@@ -0,0 +1,59 @@
+## `dependency()` consistency
+
+The first time a dependency is found, using `dependency('foo', ...)`, the return
+value is now cached. Any subsequent call will return the same value as long as
+version requested match, otherwise not-found dependency is returned. This means
+that if a system dependency is first found, it won't fallback to a subproject
+in a subsequent call any more and will rather return not-found instead if the
+system version does not match. Similarly, if the first call returns the subproject
+fallback dependency, it will also return the subproject dependency in a subsequent
+call even if no fallback is provided.
+
+For example, if the system has `foo` version 1.0:
+```meson
+# d2 is set to foo_dep and not the system dependency, even without fallback argument.
+d1 = dependency('foo', version : '>=2.0', required : false,
+ fallback : ['foo', 'foo_dep'])
+d2 = dependency('foo', version : '>=1.0', required : false)
+```
+```meson
+# d2 is not-found because the first call returned the system dependency, but its version is too old for 2nd call.
+d1 = dependency('foo', version : '>=1.0', required : false)
+d2 = dependency('foo', version : '>=2.0', required : false,
+ fallback : ['foo', 'foo_dep'])
+```
+
+## Override `dependency()`
+
+It is now possible to override the result of `dependency()` to point
+to any dependency object you want. The overriding is global and applies to
+every subproject from there on.
+
+For example, this subproject provides 2 libraries with version 2.0:
+
+```meson
+project(..., version : '2.0')
+
+libfoo = library('foo', ...)
+foo_dep = declare_dependency(link_with : libfoo)
+meson.override_dependency('foo', foo_dep)
+
+libbar = library('bar', ...)
+bar_dep = declare_dependency(link_with : libbar)
+meson.override_dependency('bar', bar_dep)
+```
+
+Assuming the system has `foo` and `bar` 1.0 installed, and master project does this:
+```meson
+foo_dep = dependency('foo', version : '>=2.0', fallback : ['foo', 'foo_dep'])
+bar_dep = dependency('bar')
+```
+
+This used to mix system 1.0 version and subproject 2.0 dependencies, but thanks
+to the override `bar_dep` is now set to the subproject's version instead.
+
+Another case this can be useful is to force a subproject to use a specific dependency.
+If the subproject does `dependency('foo')` but the main project wants to provide
+its own implementation of `foo`, it can for example call
+`meson.override_dependency('foo', declare_dependency(...))` before configuring the
+subproject.