Merge pull request #3218 from mesonbuild/findoverrider

Make it possible to override find_program [skip ci]

1 files changed, 37 insertions, 0 deletions

diff --git a/docs/markdown/snippets/find-override.md b/docs/markdown/snippets/find-override.md
new file mode 100644
index 0000000..ef3a4a2
--- /dev/null
+++ b/docs/markdown/snippets/find-override.md
@@ -0,0 +1,37 @@
+## Can override find_program
+
+It is now possible to override the result of `find_program` to point
+to a custom program you want. The overriding is global and applies to
+every subproject from there on. Here is how you would use it.
+
+In master project
+
+```meson
+subproject('mydep')
+```
+
+In the called subproject:
+
+```meson
+prog = find_program('my_custom_script')
+meson.override_find_program('mycodegen', prog)
+```
+
+In master project (or, in fact, any subproject):
+
+```meson
+genprog = find_program('mycodegen')
+```
+
+Now `genprog` points to the custom script. If the dependency had come
+from the system, then it would point to the system version.
+
+You can also use the return value of `configure_file()` to override
+a program in the same way as above:
+
+```meson
+prog_script = configure_file(input : 'script.sh.in',
+                             output : 'script.sh',
+                             configuration : cdata)
+meson.override_find_program('mycodegen', prog_script)
+```