find_program()

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()
2. [provide] sections in subproject wrap files, if wrap_mode is set to forcefallback
3. [binaries] section in your machine files
4. 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
5. Directories provided using the dirs: kwarg (see below)
6. PATH environment variable
7. [provide] sections in subproject wrap files, if wrap_mode is set to anything other than nofallback

More precisely, program overrides and forced subproject fallbacks are checked first. If neither provides a program, Meson tries the names in the order given. Only after trying all names does it consider the remaining subproject fallbacks.

Until 1.12.x Meson looked first in the machine files for any name; then searched for the program in the project's source tree, the directories listed in dirs:, and PATH, as described above. Machine-file entries took precedence over system lookup, even if their version did not satisfy the requirement. Likewise, the first program found in the system was used even if its version did not satisfy the requirement, without trying later names.

Since 1.13.0, the search is conducted separately for each name:

• If the first name is defined in a machine file, Meson uses that entry.

• Otherwise, Meson searches for the first name in the project's source tree, the directories listed in dirs:, and PATH, as described above.

• If the program is not found or does not satisfy the requested version, Meson tries the next name.

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 an array of commands. Since 0.50.0 if the "python3" program is requested and it is not found in the system, Meson will return its current interpreter.

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)

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:

setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false)

Since 1.2.0 find_program('meson') is automatically overridden to the Meson command used to execute the build script.

The returned program object also has documented methods.

# `program_name` here is a string that can be an executable or script
program find_program(
  str | file program_name,     # The name of the program to search, or a file object to be used
  str | file fallback...,      # These parameters are used as fallback names to search for

  # Keyword arguments:
  default_options  : array[str] | dict[str | bool | int | array[str]]  # An array of default option values
  dirs             : array[str]                                      # extra array of absolute paths where to look for program names
  disabler         : bool                                            # If `true` and the program couldn't be found, return a disabler object
  native           : bool                                            # Defines how this executable should be searched
  required         : bool | feature                                  # When `true`, Meson will abort if no program can be found
  version          : str | array[str]                                # Specifies the required version, see
  version_argument : str                                             # Specifies the argument to pass when trying to find the version of the program
)

Arguments

The function find_program() accepts the following positional arguments:

Name	Type	Description	Tags
program_name	str | file	The name of the program to search, or a file object to be used without searching.

Additionally, the function accepts between 0 and infinity variadic arguments (fallback...) of type str | file.

These parameters are used as fallback names 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. Since 1.13.0, programs that do not satisfy the requested version can fall back to subsequent names.

Finally, find_program() accepts the following keyword arguments:

Name	Type	Description	Tags
default_options	array[str] | dict[str | bool | int | array[str]]	An array of default option values that override those set in the subproject's meson.options (like default_options in project(), they only have effect when Meson is run for the first time, and command line arguments override any default options in build files)	(since 1.3.0)
dirs	array[str]	extra array of absolute paths where to look for program names.	(since 0.53.0)
disabler	bool	If true and the program couldn't be found, return a disabler object instead of a not-found object.	(since 0.49.0) default = false
native	bool	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.	(since 0.43.0) default = false
required	bool | feature	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 program to check whether it was found or not. (since 0.47.0) The value of a feature option can also be passed to the required keyword argument.	default = true
version	str | array[str]	Specifies the required version, see dependency() for argument format. By default, 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().	(since 0.52.0)
version_argument	str	Specifies the argument to pass when trying to find the version of the program. If this is unspecified, program_name --version will be used.	(since 1.5.0)