| 1 |
name: find_program |
| 2 |
returns: external_program | exe |
| 3 |
description: | |
| 4 |
`program_name` here is a string that can be an executable or script |
| 5 |
to be searched for in `PATH` or other places inside the project. |
| 6 |
The search order is: |
| 7 |
|
| 8 |
1. Program overrides set via [[meson.override_find_program]] |
| 9 |
1. [`[provide]` sections](Wrap-dependency-system-manual.md#provide-section) |
| 10 |
in subproject wrap files, if [`wrap_mode`](Builtin-options.md#core-options) is |
| 11 |
set to `forcefallback` |
| 12 |
1. [`[binaries]` section](Machine-files.md#binaries) in your machine files |
| 13 |
1. Directories provided using the `dirs:` kwarg (see below) |
| 14 |
1. Project's source tree relative to the current subdir |
| 15 |
- If you use the return value of [[configure_file]], the |
| 16 |
current subdir inside the build tree is used instead |
| 17 |
1. `PATH` environment variable |
| 18 |
1. [`[provide]` sections](Wrap-dependency-system-manual.md#provide-section) in |
| 19 |
subproject wrap files, if [`wrap_mode`](Builtin-options.md#core-options) is |
| 20 |
set to anything other than `nofallback` |
| 21 |
|
| 22 |
Meson will also autodetect scripts with a shebang line and run them |
| 23 |
with the executable/interpreter specified in it both on Windows |
| 24 |
(because the command invocator will reject the command otherwise) and |
| 25 |
Unixes (if the script file does not have the executable bit set). |
| 26 |
Hence, you *must not* manually add the interpreter while using this |
| 27 |
script as part of a list of commands. Since *0.50.0* if the "python3" |
| 28 |
program is requested and it is not found in the system, Meson will return |
| 29 |
its current interpreter. |
| 30 |
|
| 31 |
If you need to check for a program in a non-standard location, you can |
| 32 |
just pass an absolute path to `find_program`, e.g. |
| 33 |
|
| 34 |
```meson |
| 35 |
setcap = find_program('setcap', '/usr/sbin/setcap', '/sbin/setcap', required : false) |
| 36 |
``` |
| 37 |
|
| 38 |
It is also possible to pass an array to `find_program` in case you |
| 39 |
need to construct the set of paths to search on the fly: |
| 40 |
|
| 41 |
```meson |
| 42 |
setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false) |
| 43 |
``` |
| 44 |
|
| 45 |
*Since 1.2.0* `find_program('meson')` is automatically overridden to the Meson |
| 46 |
command used to execute the build script. |
| 47 |
|
| 48 |
The returned [[@external_program]] object also has documented methods. |
| 49 |
|
| 50 |
posargs: |
| 51 |
program_name: |
| 52 |
type: str | file |
| 53 |
description: | |
| 54 |
The name of the program to search, or a [[@file]] object to be used |
| 55 |
without searching. |
| 56 |
|
| 57 |
varargs: |
| 58 |
name: fallback |
| 59 |
type: str | file |
| 60 |
since: 0.37.0 |
| 61 |
description: | |
| 62 |
These parameters are used as fallback names to search for. |
| 63 |
This is meant to be used for cases where the |
| 64 |
program may have many alternative names, such as `foo` and |
| 65 |
`foo.py`. The function will check for the arguments one by one and the |
| 66 |
first one that is found is returned. |
| 67 |
|
| 68 |
kwargs: |
| 69 |
required: |
| 70 |
type: bool | feature |
| 71 |
default: true |
| 72 |
description: | |
| 73 |
When `true`, Meson will abort if no program can be found. |
| 74 |
If `required` is set to `false`, |
| 75 |
Meson continue even if none of the programs can be found. You can |
| 76 |
then use the `.found()` method on the returned [[@external_program]] to check |
| 77 |
whether it was found or not. *(since 0.47.0)* The value of a |
| 78 |
[`feature`](Build-options.md#features) option can also be passed to the |
| 79 |
`required` keyword argument. |
| 80 |
|
| 81 |
native: |
| 82 |
type: bool |
| 83 |
default: false |
| 84 |
since: 0.43.0 |
| 85 |
description: | |
| 86 |
Defines how this executable should be searched. By default |
| 87 |
it is set to `false`, which causes Meson to first look for the |
| 88 |
executable in the cross file (when cross building) and if it is not |
| 89 |
defined there, then from the system. If set to `true`, the cross |
| 90 |
file is ignored and the program is only searched from the system. |
| 91 |
|
| 92 |
disabler: |
| 93 |
type: bool |
| 94 |
since: 0.49.0 |
| 95 |
default: false |
| 96 |
description: | |
| 97 |
If `true` and the program couldn't be found, return a [[@disabler]] object |
| 98 |
instead of a not-found object. |
| 99 |
|
| 100 |
version: |
| 101 |
type: list[str] |
| 102 |
since: 0.52.0 |
| 103 |
description: | |
| 104 |
Specifies the required version, see |
| 105 |
[[dependency]] for argument format. By default, the version of the program |
| 106 |
is determined by running `program_name --version` command. If stdout is empty |
| 107 |
it fallbacks to stderr. If the output contains more text than simply a version |
| 108 |
number, only the first occurrence of numbers separated by dots is kept. |
| 109 |
If the output is more complicated than that, the version checking will have to |
| 110 |
be done manually using [[run_command]]. |
| 111 |
|
| 112 |
version_argument: |
| 113 |
type: str |
| 114 |
since: 1.5.0 |
| 115 |
description: | |
| 116 |
Specifies the argument to pass when trying to find the version of the program. |
| 117 |
If this is unspecified, `program_name --version` will be used. |
| 118 |
|
| 119 |
dirs: |
| 120 |
type: list[str] |
| 121 |
since: 0.53.0 |
| 122 |
description: extra list of absolute paths where to look for program names. |
| 123 |
|
| 124 |
default_options: |
| 125 |
type: list[str] | dict[str | bool | int | list[str]] |
| 126 |
since: 1.3.0 |
| 127 |
description: | |
| 128 |
An array of default option values |
| 129 |
that override those set in the subproject's `meson.options` |
| 130 |
(like `default_options` in [[project]], they only have |
| 131 |
effect when Meson is run for the first time, and command line |
| 132 |
arguments override any default options in build files) |