docs: Add the YAML Reference manual

1 files changed, 108 insertions, 0 deletions

diff --git a/docs/yaml/functions/find_program.yaml b/docs/yaml/functions/find_program.yaml
new file mode 100644
index 000000000..5e147eb13
--- /dev/null
+++ b/docs/yaml/functions/find_program.yaml
@@ -0,0 +1,108 @@
+name: find_program
+returns: external_program
+description: |
+  `program_name` here is a string that can be an executable or script
+  to be searched for in `PATH` or other places inside the project.
+  The search order is:
+
+  1. Program overrides set via [[meson.override_find_program]]
+  1. [`[provide]` sections](Wrap-dependency-system-manual.md#provide-section)
+    in subproject wrap files, if [`wrap_mode`](Builtin-options.md#core-options) is
+    set to `forcefallback`
+  1. [`[binaries]` section](Machine-files.md#binaries) in your machine files
+  1. Directories provided using the `dirs:` kwarg (see below)
+  1. Project's source tree relative to the current subdir
+    - If you use the return value of [[configure_file]], the
+      current subdir inside the build tree is used instead
+  1. `PATH` environment variable
+  1. [`[provide]` sections](Wrap-dependency-system-manual.md#provide-section) in
+    subproject wrap files, if [`wrap_mode`](Builtin-options.md#core-options) is
+    set to anything other than `nofallback`
+
+  Meson will also autodetect scripts with a shebang line and run them
+  with the executable/interpreter specified in it both on Windows
+  (because the command invocator will reject the command otherwise) and
+  Unixes (if the script file does not have the executable bit set).
+  Hence, you *must not* manually add the interpreter while using this
+  script as part of a list of commands.
+
+  If you need to check for a program in a non-standard location, you can
+  just pass an absolute path to `find_program`, e.g.
+
+  ```meson
+  setcap = find_program('setcap', '/usr/sbin/setcap', '/sbin/setcap', required : false)
+  ```
+
+  It is also possible to pass an array to `find_program` in case you
+  need to construct the set of paths to search on the fly:
+
+  ```meson
+  setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false)
+  ```
+
+  The returned [[@external_program]] object also has documented methods.
+
+posargs:
+  program_name:
+    type: str
+    description: The name of the program to search
+
+varargs:
+  name: fallback
+  type: str
+  since: 0.37.0
+  description: |
+    These parameters are used as fallback strings to search for.
+    This is meant to be used for cases where the
+    program may have many alternative names, such as `foo` and
+    `foo.py`. The function will check for the arguments one by one and the
+    first one that is found is returned.
+
+kwargs:
+  required:
+    type: bool | feature
+    default: true
+    description: |
+      When `true`, Meson will abort if no program can be found.
+      If `required` is set to `false`,
+      Meson continue even if none of the programs can be found. You can
+      then use the `.found()` method on the returned [[@external_program]] to check
+      whether it was found or not. *(since 0.47.0)* The value of a
+      [`feature`](Build-options.md#features) option can also be passed to the
+      `required` keyword argument.
+
+  native:
+    type: bool
+    default: false
+    since: 0.43.0
+    description: |
+      Defines how this executable should be searched. By default
+      it is set to `false`, which causes Meson to first look for the
+      executable in the cross file (when cross building) and if it is not
+      defined there, then from the system. If set to `true`, the cross
+      file is ignored and the program is only searched from the system.
+
+  disabler:
+    type: bool
+    since: 0.49.0
+    default: false
+    description: |
+      If `true` and the program couldn't be found, return a [[@disabler]] object
+      instead of a not-found object.
+
+  version:
+    type: str
+    since: 0.52.0
+    description: |
+      specifies the required version, see
+      [[dependency]] for argument format. The version of the program
+      is determined by running `program_name --version` command. If stdout is empty
+      it fallbacks to stderr. If the output contains more text than simply a version
+      number, only the first occurrence of numbers separated by dots is kept.
+      If the output is more complicated than that, the version checking will have to
+      be done manually using [[run_command]].
+
+  dirs:
+    type: list[str]
+    since: 0.53.0
+    description: extra list of absolute paths where to look for program names.