Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/find_program.yaml

raw
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)