From 73494c992761a528bf98c8dd48fbdd2f71d4b521 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Fri, 5 May 2017 09:31:13 +1000 Subject: [PATCH] docs: make the required argument for find_program stick out more --- docs/markdown/Reference-manual.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index c64419b8d..b20c14ae8 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -262,10 +262,14 @@ This function is deprecated and in the 0.31.0 release it was moved to [the compi `program_name1` here is a string that can be an executable or script to be searched for in `PATH`, or a script in the current source directory. -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. - `program_name2` and later positional arguments 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. Meson versions earlier than 0.37.0 only accept one argument. +Keyword arguments are the following: + +- `required` By default, `required` is set to `true` and 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 object to check whether it was found or not. + +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. ``` setcap = find_program('setcap', '/usr/sbin/setcap', '/sbin/setcap', required : false) @@ -276,8 +280,6 @@ It is also possible to pass an array to `find_program` in case you need to const setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false) ``` -If none of the programs are found, Meson will abort. You can tell it not to by setting the keyword argument `required` to false, and then use the `.found()` method on the returned object to check whether it was found or not. - The returned object also has methods that are documented in the [object methods section](#external-program-object) below. ### files()