native bool, default: false, since 0.48.0

Like add_global_arguments but the arguments are passed to the linker.

native bool, default: false, since 0.48.0

This is equivalent to having them in the `project` declaration. This function is usually used to add languages that are only used under some conditions.

Returns `true` if all languages specified were found and `false` otherwise.

If `native` is omitted, the languages may be used for either build or host machine, but are never required for the build machine. (i.e. it is equivalent to `add_languages(langs, native: false, required: required) and add_languages(langs, native: true, required: false)`. This default behaviour may change to `native: false` in a future Meson version.

required bool | feature, default: true

This function behaves in the same way as add_global_arguments except that the arguments are only used for the current project, they won't be used in any other subproject.

native bool, default: false, since 0.48.0

since 0.63.0

native bool, default: false, since 0.48.0

Like add_project_arguments but the arguments are passed to the linker.

native bool, default: false, since 0.48.0

To use the test setup, run `meson test --setup=name` inside the build dir.

Note that all these options are also available while running the `meson test` script for running tests instead of `ninja test` or `msbuild RUN_TESTS.vcxproj`, etc depending on the backend.

exclude_suites list[str], since 0.57.0

exe_wrapper list[str | external_program]

gdb bool, default: false

is_default bool, default: false, since 0.49.0

timeout_multiplier int, default: 1

since 0.52.0

* benchmark() has no `is_parallel` keyword because benchmarks are not run in parallel
* benchmark() does not automatically add the `MALLOC_PERTURB_` environment variable

Defined benchmarks can be run in a backend-agnostic way by calling `meson test --benchmark` inside the build dir, or by using backend-specific commands, such as `ninja benchmark` or `msbuild RUN_TESTS.vcxproj`.

executable exe | jar | external_program | file | custom_tgt | custom_idx, required

depends list[build_tgt | custom_tgt], since 0.46.0

env env | list[str] | dict[str]

priority int, default: 0, since 0.52.0

protocol str, default: 'exitcode', since 0.50.0

should_fail bool, default: false

suite str | list[str]

timeout int, default: 30

verbose bool, default: false, since 0.62.0

workdir str

since 0.46.0

<lang>_pch str

<lang>_shared_args list[str], since 1.3.0

<lang>_static_args list[str], since 1.3.0

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

darwin_versions str | int | list[str], since 0.48.0

dependencies list[dep]

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

pic bool, since 0.36.0

prelink bool, since 0.57.0

rust_abi str, since 1.3.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

soversion str | int

vala_args list[str | file]

vala_shared_args list[str | file], since 1.3.0

vala_static_args list[str | file], since 1.3.0

version str

vs_module_defs str | file | custom_tgt | custom_idx

win_subsystem str, default: 'console', since 0.56.0

`target_type` may be set to one of:

- `executable` (see executable)
- `shared_library` (see shared_library)
- `shared_module` (see shared_module)
- `static_library` (see static_library)
- `both_libraries` (see both_libraries)
- `library` (see library)
- `jar` (see jar)*

This declaration:

The returned object also has methods that are documented in build_tgt.

*"jar" is deprecated because it is fundementally a different thing than the other build_target types.

<lang>_pch str

<lang>_shared_args list[str], since 1.3.0

<lang>_static_args list[str], since 1.3.0

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

darwin_versions str | int | list[str], since 0.48.0

dependencies list[dep]

export_dynamic bool, since 0.45.0

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implib bool | str, since 0.42.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

java_resources structured_src, since 0.62.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

main_class str

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

pic bool, since 0.36.0

pie bool, since 0.49.0

prelink bool, since 0.57.0

rust_abi str, since 1.3.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

soversion str | int

target_type str

vala_args list[str | file]

vala_shared_args list[str | file], since 1.3.0

vala_static_args list[str | file], since 1.3.0

version str

vs_module_defs str | file | custom_tgt | custom_idx, since 1.3.0

win_subsystem str, default: 'console', since 0.56.0

When a cfg_data object is passed to the `configuration:` keyword argument, it takes a template file as the `input:` (optional) and produces the `output:` (required) by substituting values from the configuration data as detailed in the configuration file documentation[10]. (since 0.49.0) A dictionary can be passed instead of a cfg_data object.

When a list of strings is passed to the `command:` keyword argument, it takes any source or configured file as the `input:` and assumes that the `output:` is produced when the specified command is run.

(since 0.47.0) When the `copy:` keyword argument is set to `true`, this function will copy the file provided in `input:` to a file in the build directory with the name `output:` in the current directory.

command list[str | file]

configuration cfg_data | dict[str | int | bool]

copy bool, default: false, since 0.47.0

depfile str, since 0.52.0

encoding str, default: 'utf-8', since 0.47.0

format str, default: 'meson', since 0.46.0

input str | file

install bool, default: false, since 0.50.0

install_dir str

install_mode list[str | int], since 0.47.0

install_tag str, since 0.60.0

macro_name str, since 1.3.0

output str

output_format str, since 0.47.0

The list of strings passed to the `command` keyword argument accept the following special string substitutions:

- `@INPUT@`: the full path to the input passed to `input`. If more than one input is specified, all of them will be substituted as separate arguments only if the command uses `'@INPUT@'` as a standalone-argument. For instance, this would not work: `command : ['cp', './@INPUT@']`, but this would: `command : ['cp', '@INPUT@']`.
- `@OUTPUT@`: the full path to the output passed to `output`. If more than one outputs are specified, the behavior is the same as `@INPUT@`.
- `@INPUT0@` `@INPUT1@` `...`: the full path to the input with the specified array index in `input`
- `@OUTPUT0@` `@OUTPUT1@` `...`: the full path to the output with the specified array index in `output`
- `@OUTDIR@`: the full path to the directory where the output(s) must be written
- `@DEPFILE@`: the full path to the dependency file passed to `depfile`
- `@PLAINNAME@`: the input filename, without a path
- `@BASENAME@`: the input filename, with extension removed
- `@PRIVATE_DIR@` (since 0.50.1): path to a directory where the custom target must store all its intermediate files.
- `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend, this may be an absolute or a relative to current workdir path.
- `@BUILD_ROOT@`: the path to the root of the build tree. Depending on the backend, this may be an absolute or a relative to current workdir path.
- `@CURRENT_SOURCE_DIR@`: this is the directory where the currently processed meson.build is located in. Depending on the backend, this may be an absolute or a relative to current workdir path.

(since 0.47.0) The `depfile` keyword argument also accepts the `@BASENAME@` and `@PLAINNAME@` substitutions.

The returned object also has methods that are documented in custom_tgt.

build_always_stale bool, default: false, since 0.47.0

build_by_default bool, since 0.38.0

capture bool, default: false

command list[str | file | exe | external_program]

console bool, since 0.48.0

depend_files list[str | file]

depends list[build_tgt | custom_tgt]

depfile str

env env | list[str] | dict[str], since 0.57.0

feed bool, default: false, since 0.59.0

input list[str | file]

install bool

install_dir str | list[str | bool]

install_mode list[str | int], since 0.47.0

install_tag list[str], since 0.60.0

output list[str]

since 0.63.0

d_import_dirs list[inc | str], since 0.62.0

d_module_versions str | int | list[str | int], since 0.62.0

dependencies list[dep]

extra_files list[str | file], since 1.2.0

include_directories list[inc | str]

link_args list[str]

link_whole list[lib], since 0.46.0

link_with list[lib]

objects list[extracted_obj], since 1.1.0

sources list[str | file | custom_tgt | custom_idx | generated_list]

variables dict[str] | list[str], since 0.54.0

version str

Since 0.60.0 more than one name can be provided, they will be tried in order and the first name to be found will be used. The fallback subproject will be used only if none of the names are found on the system. Once one of the name has been found, all other names are added into the cache so subsequent calls for any of those name will return the same value. This is useful in case a dependency could have different names, such as `png` and `libpng`.

Since 0.64.0* a dependency fallback can be provided by WrapDB. Simply download the database locally using `meson wrap update-db` command and Meson will automatically fallback to subprojects provided by WrapDB if the dependency is not found on the system and the project does not ship their own `.wrap` file.

Dependencies can also be resolved in two other ways:

* if the same name was used in a `meson.override_dependency` prior to the call to `dependency`, the overriding dependency will be returned unconditionally; that is, the overriding dependency will be used independent of whether an external dependency is installed in the system. Typically, `meson.override_dependency` will have been used by a subproject.

* by a fallback subproject which, if needed, will be brought into the current build specification as if `subproject()` had been called. The subproject can be specified with the `fallback` argument. Alternatively, if the `fallback` argument is absent, since 0.55.0 Meson can automatically identify a subproject as a fallback if a wrap file provides[15] the dependency, or if a subproject has the same name as the dependency. In the latter case, the subproject must use `meson.override_dependency` to specify the replacement, or Meson will report a hard error. See the Wrap documentation[14] for more details. This automatic search can be controlled using the `allow_fallback` keyword argument.

If `dependency_name` is `''`, the dependency is always not found. So with `required: false`, this always returns a dependency object for which the `found()` method returns `false`, and which can be passed like any other dependency to the `dependencies:` keyword argument of a `build_target`. This can be used to implement a dependency which is sometimes not required e.g. in some branches of a conditional, or with a `fallback:` kwarg, can be used to declare an optional dependency that only looks in the specified subproject, and only if that's allowed by `--wrap-mode`.

The returned object dep also has additional methods.

default_options list[str] | dict[str | bool | int | list[str]], since 0.38.0

disabler bool, default: false, since 0.49.0

fallback list[str] | str

include_type str, default: 'preserve', since 0.52.0

language str, since 0.42.0

method str, default: 'auto', since 0.40.0

native bool, default: false

not_found_message str, since 0.50.0

required bool | feature, default: true

static bool, default: false

version list[str] | str, since 0.37.0

since 0.44.0

since 0.35.0

separator str, since 0.62.0

The lists for the kwargs (such as `sources`, `objects`, and `dependencies`) are always flattened, which means you can freely nest and add lists while creating the final list.

The returned object also has methods that are documented in exe.

Since 1.3.0 executable names can be the same across multiple targets as long as they each have a different `name_suffix`.

<lang>_pch str

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

dependencies list[dep]

export_dynamic bool, since 0.45.0

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implib bool | str, since 0.42.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

pie bool, since 0.49.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

vala_args list[str | file]

vs_module_defs str | file | custom_tgt | custom_idx, since 1.3.0

win_subsystem str, default: 'console', since 0.56.0

1. Program overrides set via meson.override_find_program 1. `[provide]` sections[14]
in subproject wrap files, if `wrap_mode`[17] is
set to `forcefallback` 1. `[binaries]` section[18] 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[14] in
subproject wrap files, if `wrap_mode`[16] 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. 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.

The returned external_program object also has documented methods.

dirs list[str], since 0.53.0

disabler bool, default: false, since 0.49.0

native bool, default: false, since 0.43.0

required bool | feature, default: true

version str | list[str], since 0.52.0

This function creates a generator object that can be used to run custom compilation commands. The only positional argument is the executable to use. It can either be a self-built executable or one returned by find_program.

The template strings passed to all the keyword arguments accept the following special substitutions:

- `@PLAINNAME@`: the complete input file name, e.g: `foo.c` becomes `foo.c` (unchanged)
- `@BASENAME@`: the base of the input filename, e.g.: `foo.c.y` becomes `foo.c` (extension is removed)

Each string passed to the `output` keyword argument must be constructed using one or both of these two substitutions.

In addition to the above substitutions, the `arguments` keyword argument also accepts the following:

- `@OUTPUT@`: the full path to the output file
- `@INPUT@`: the full path to the input file
- `@DEPFILE@`: the full path to the depfile
- `@SOURCE_DIR@`: the full path to the root of the source tree
- `@CURRENT_SOURCE_DIR@`: this is the directory where the currently processed meson.build is located in
- `@BUILD_DIR@`: the full path to the root of the build dir where the output will be placed

NOTE: Generators should only be used for outputs that will only be used as inputs for a build_target or a custom_target. When you use the processed output of a generator in multiple targets, the generator will be run multiple times to create outputs for each target. Each output will be created in a target-private directory `@BUILD_DIR@`.

If you want to generate files for general purposes such as for generating headers to be used by several sources, or data that will be installed, and so on, use a custom_target instead.

capture bool, default: false, since 0.43.0

depends list[build_tgt | custom_tgt], since 0.51.0

depfile str

output list[str]

Note that the value returned for built-in options that end in `dir` such as `bindir` and `libdir` is usually a path relative to (and inside) the `prefix` but you should not rely on that, as it can also be an absolute path in some cases[20]. `install_dir` arguments[21] handle that as expected but if you need an absolute path, e.g. to use in a define etc., you should use the path concatenation operator like this: `get_option('prefix') / get_option('localstatedir')`. Never manually join paths as if they were strings.

For options of type `feature` a feature option object is returned instead of a string. See `feature` options[0] documentation for more details.

required bool | feature, default: true, since 0.59.0

Note that this function call itself does not add the directories into the search path, since there is no global search path. For something like that, see `add_project_arguments()`.

See also `implicit_include_directories` parameter of executable, which adds current source and build directories to include path.

Each directory given is converted to two include paths: one that is relative to the source root and one relative to the build root.

`meson.build`:

See Installing[20] for more examples.

install_dir str

install_mode list[str | int], since 0.38.0

install_tag str, since 0.60.0

preserve_path bool, default: false, since 0.64.0

rename list[str], since 0.46.0

sources list[file | str]

since 0.60.0

install_tag str

install_dir str

install_mode list[str | int], since 0.47.0

preserve_path bool, default: false, since 0.63.0

subdir str

(since 0.49.0) [manpages are no longer compressed implicitly][install_man_49].

[install_man_49]: https://mesonbuild.com/Release-notes-for-0-49-0.html#manpages-are-no-longer-compressed-implicitly

install_mode list[str | int], since 0.47.0

locale str, since 0.58.0

(since 0.45.0, deprecated since 0.60.0) If the subdirectory does not exist in the source tree, an empty directory is created in the specified location. A newly created subdirectory may only be created in the keyword argument `install_dir`. There are a number of flaws with this method, and it was never intentionally designed to work this way, please use install_emptydir instead.

exclude_files list[str]

follow_symlinks bool, default: true, since 1.3.0

install_dir str

install_mode list[str | int], since 0.47.0

install_tag str, since 0.60.0

strip_directory bool, default: false, since 0.45.0

since 0.61.0

install_tag str

pointing_to str, required

since 0.52.0

since 0.52.0

<lang>_pch str

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

dependencies list[dep]

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

java_resources structured_src, since 0.62.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

main_class str

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

vala_args list[str | file]

win_subsystem str, default: 'console', since 0.56.0

since 0.36.0

(since 0.49.0) Using the `/` operator on strings is equivalent to calling join_paths.

The keyword arguments for this are the same as for build_target

<lang>_pch str

<lang>_shared_args list[str], since 1.3.0

<lang>_static_args list[str], since 1.3.0

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

darwin_versions str | int | list[str], since 0.48.0

dependencies list[dep]

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

pic bool, since 0.36.0

prelink bool, since 0.57.0

rust_abi str, since 1.3.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

soversion str | int

vala_args list[str | file]

vala_shared_args list[str | file], since 1.3.0

vala_static_args list[str | file], since 1.3.0

version str

vs_module_defs str | file | custom_tgt | custom_idx

win_subsystem str, default: 'console', since 0.56.0

The first argument to this function must be a string defining the name of this project.

The project name can be any string you want, it's not used for anything except descriptive purposes. However since it is written to e.g. the dependency manifest is usually makes sense to have it be the same as the project tarball or pkg-config name. So for example you would probably want to use the name _libfoobar_ instead of _The Foobar Library_.

It may be followed by the list of programming languages that the project uses.

(since 0.40.0) The list of languages is optional.

These languages may be used both for `native: false` (the default) (host machine) targets and for `native: true` (build machine) targets. (since 0.56.0) The build machine compilers for the specified languages are not required.

Supported values for languages are `c`, `cpp` (for `C++`), `cuda`, `cython`, `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), `vala` and `rust`.

license str | list[str]

license_files str | list[str], since 1.1.0

meson_version str

subproject_dir str, default: 'subprojects'

version str | file

since 0.58.0

<pre><code class="language-meson">range range(int <b>stop</b>) range range(int <b>start</b>, int <b>stop</b>[, int <b>step</b>])</code></pre>

- `start` must be integer greater or equal to 0. Defaults to 0.
- `stop` must be integer greater or equal to `start`.
- `step` must be integer greater or equal to 1. Defaults to 1.

It cause the `foreach` loop to be called with the value from `start` included to `stop` excluded with an increment of `step` after each loop.

stop int

step int, default: 1

Returns a runresult object containing the result of the invocation. The command is run from an unspecified directory, and Meson will set three environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` and `MESON_SUBDIR` that specify the source directory, build directory and subdirectory the target was defined in, respectively.

See also External commands[25].

check bool, default: false, since 0.47.0

env env | list[str] | dict[str], since 0.50.0

The command is run from an unspecified directory, and Meson will set three environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` and `MESON_SUBDIR` that specify the source directory, build directory and subdirectory the target was defined in, respectively.

Since 0.57.0 The template strings passed to `command` keyword arguments accept the following special substitutions: - `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend, this may be an absolute or a relative to current workdir path.
- `@BUILD_ROOT@`: the path to the root of the build tree. Depending on the backend, this may be an absolute or a relative to current workdir path.
- `@CURRENT_SOURCE_DIR@` Since 0.57.1: this is the directory where the currently processed meson.build is located in. Depending on the backend, this may be an absolute or a relative to current workdir path.

depends list[build_tgt | custom_tgt]

env env | list[str] | dict[str], since 0.57.0

(since 0.46.1) The `value` parameter can be an array type.

value any, required

<lang>_pch str

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

darwin_versions str | int | list[str], since 0.48.0

dependencies list[dep]

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

rust_abi str, since 1.3.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

soversion str | int

vala_args list[str | file]

version str

vs_module_defs str | file | custom_tgt | custom_idx

win_subsystem str, default: 'console', since 0.56.0

since 0.37.0

This is useful for building modules that will be `dlopen()`ed and hence may contain undefined symbols that will be provided by the library that is loading it.

If you want the shared module to be able to refer to functions and variables defined in the executable it is loaded by, you will need to set the `export_dynamic` argument of the executable to `true`.

<lang>_pch str

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

dependencies list[dep]

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

rust_abi str, since 1.3.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

vala_args list[str | file]

vs_module_defs str | file | custom_tgt | custom_idx, since 0.52.0

win_subsystem str, default: 'console', since 0.56.0

<lang>_pch str

build_by_default bool, default: true, since 0.38.0

build_rpath str, since 0.42.0

d_debug list[str]

d_import_dirs list[str]

d_module_versions list[str | int]

d_unittest bool, default: false

dependencies list[dep]

extra_files str | file | custom_tgt | custom_idx

gnu_symbol_visibility str, since 0.48.0

gui_app bool, default: false, deprecated since 0.56.0

implicit_include_directories bool, default: true, since 0.42.0

include_directories list[inc | str]

install bool, default: false

install_dir str

install_mode list[str | int], since 0.47.0

install_rpath str

install_tag str, since 0.60.0

link_args list[str]

link_depends str | file | custom_tgt | custom_idx

link_language str, since 0.51.0

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0

link_with list[lib | custom_tgt | custom_idx]

name_prefix str | list[void]

name_suffix str | list[void]

native bool, default: false

objects list[extracted_obj | file | str]

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0

pic bool, since 0.36.0

prelink bool, since 0.57.0

rust_abi str, since 1.3.0

rust_crate_type str, deprecated since 1.3.0, since 0.42.0

rust_dependency_map dict[str], since 1.2.0

sources str | file | custom_tgt | custom_idx | generated_list | structured_src

vala_args list[str | file]

win_subsystem str, default: 'console', since 0.56.0

since 0.62.0

Note that this means that each `meson.build` file in a source tree can and must only be executed once.

since 0.46.0

If the current script was called by `subdir` the execution returns to the calling directory and continues as if the script had reached the end. If the current script is the top level script Meson configures the project as defined up to this point.

- `default_options` (since 0.37.0): 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 0.54.0): `default_library` built-in option can also be overridden. (since 1.2.0): A dictionary may be passed instead of array.
- `version`: works just like the same as in `dependency`. It specifies what version the subproject should be, as an example `>=1.0.1`
- `required` (since 0.48.0): By default, `required` is `true` and Meson will abort if the subproject could not be setup. You can set this to `false` and then use the `.found()` method on the subproject object. You may also pass the value of a `feature`[0] option, same as dependency.

Note that you can use the returned subproject object to access any variable in the subproject. However, if you want to use a dependency object from inside a subproject, an easier way is to use the `fallback:` keyword argument to dependency.

See additional documentation[26].

required bool | feature, default: true, since 0.48.0

version str

since 0.53.0

The content is a series of key/value pairs grouped into sections. If the section keyword argument is omitted, those key/value pairs are implicitly grouped into a section with no title. key/value pairs can optionally be grouped into a dictionary, but keep in mind that dictionaries do not guarantee ordering. `key` must be string, `value` can be:

- an integer, boolean or string
- since 0.57.0 an external program or a dependency
- since 0.58.0 a feature option
- a list of those.

Instead of calling summary as `summary(key, value)`, it is also possible to directly pass a dictionary to the summary function, as seen in the example below.

`summary()` can be called multiple times as long as the same section/key pair doesn't appear twice. All sections will be collected and printed at the end of the configuration in the same order as they have been called.

list_sep str, since 0.54.0

section str

(since 0.55.0) When cross compiling, if an exe_wrapper is needed and defined the environment variable `MESON_EXE_WRAPPER` will be set to the string value of that wrapper (implementation detail: using `mesonlib.join_args`). Test scripts may use this to run cross built binaries. If your test needs `MESON_EXE_WRAPPER` in cross build situations it is your responsibility to return code 77 to tell the harness to report "skip".

By default, environment variable `MALLOC_PERTURB_`[27] is automatically set by `meson test` to a random value between 1..255. This can help find memory leaks on configurations using glibc, including with non-GCC compilers. However, this can have a performance impact, and may fail a test due to external libraries whose internals are out of the user's control. To check if this feature is causing an expected runtime crash, disable the feature by temporarily setting environment variable `MALLOC_PERTURB_=0`. While it's preferable to only temporarily disable this check, if a project requires permanent disabling of this check in meson.build do like:

In addition to running individual executables as test cases, `test()` can also be used to invoke an external test harness. In this case, it is best to use `verbose: true` (since 0.62.0) and, if supported by the external harness, `protocol: 'tap'` (since 0.50.0). This will ensure that Meson logs each subtest as it runs, instead of including the whole log at the end of the run.

Defined tests can be run in a backend-agnostic way by calling `meson test` inside the build dir, or by using backend-specific commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`.

executable exe | jar | external_program | file | custom_tgt | custom_idx, required

depends list[build_tgt | custom_tgt], since 0.46.0

env env | list[str] | dict[str]

is_parallel bool, default: true

priority int, default: 0, since 0.52.0

protocol str, default: 'exitcode', since 0.50.0

should_fail bool, default: false

suite str | list[str]

timeout int, default: 30

verbose bool, default: false, since 0.62.0

workdir str

since 0.60.0

Meson will read the contents of `input`, substitute the `replace_string` with the detected revision number, and write the result to `output`. This method returns a custom_tgt object that (as usual) should be used to signal dependencies if other targets use the file outputted by this.

For example, if you generate a header with this and want to use that in a build target, you must add the return value to the sources of that build target. Without that, Meson will not know the order in which to build the targets.

If you desire more specific behavior than what this command provides, you should use custom_target.

fallback str, default: [[meson.project_version]]

input str, required

output str, required

replace_string str, default: '@VCS_TAG@'

since 0.44.0

false_str str, default: 'false'

By default only objects built for this target are returned to maintain backward compatibility with previous versions. The default value for the `recursive` kwarg will eventually be changed to `true` in a future version.

since 0.59.0

since 0.54.0

deprecated since 0.59.0, since 0.59.0

since 0.38.0

since 0.44.0

since 0.57.0

You can iterate over this array with the `foreach` statement[30].

since 0.42.0

value str | int | bool, required

value bool | int, required

value str | int | bool, required

dependencies dep | list[dep]

prefix str | list[str]

since 0.47.0

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

required bool | feature, default: false, since 0.50.0

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

name str

no_builtin_args bool, default: false

werror bool, default: false, since 1.3.0

since 0.40.0

dependencies dep | list[dep]

guess int

high int, default: 1024

include_directories inc | list[inc], since 0.38.0

low int, default: -1024

no_builtin_args bool, default: false

prefix str | list[str]

disabler bool, default: false, since 0.49.0

has_headers list[str], since 0.50.0

header_args list[str], since 0.51.0

header_dependencies dep | list[dep], since 0.51.0

header_include_directories inc | list[inc], since 0.51.0

header_no_builtin_args bool, default: false, since 0.51.0

header_prefix str, since 0.51.0

required bool | feature, default: true

static bool, default: false, since 0.51.0

since 0.43.0

since 0.46.0

since 0.49.0

since 0.40.0

(since 0.47.0) This method will concatenate string literals as the compiler would. E.g. `"a" "b"` will become `"ab"`.

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

since 0.53.0

since 0.43.0

since 0.48.0

since 0.46.0

since 1.3.0

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

required bool | feature, default: false, since 1.3.0

since 0.48.0

This method is faster than compiler.check_header since it only does a pre-processor check.

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

required bool | feature, default: false, since 0.50.0

Symbols here include function, variable, `#define`, type definition, etc.

symbol str, required

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

required bool | feature, default: false, since 0.50.0

since 0.46.0

membername str, required

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

required bool | feature, default: false, since 1.3.0

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

required bool | feature, default: false, since 1.3.0

since 0.37.0

since 0.46.0

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

required bool | feature, default: false, since 1.3.0

Since 0.60.0, if the `file` object's suffix does not match the compiler object's language, the compiler corresponding to the suffix is used to compile the source, while the target of the `links` method is used to link the resulting object file.

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

name str

no_builtin_args bool, default: false

werror bool, default: false, since 1.3.0

since 0.64.0

dependencies dep | list[dep], since 1.1.0

depends list[build_tgt | custom_tgt], since 1.4.0

include_directories inc | list[inc], since 0.38.0

output str

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

name str

no_builtin_args bool, default: false

werror bool, default: false, since 1.3.0

dependencies dep | list[dep]

include_directories inc | list[inc], since 0.38.0

no_builtin_args bool, default: false

prefix str | list[str]

since 0.37.0

since 0.54.0

See custom_tgt.full_path

since 0.54.0

since 0.56.0

since 0.52.0

deprecated since 0.56.0, since 0.44.0

deprecated since 0.56.0, since 0.36.0

define_variable list[str], since 0.44.0

since 0.51.0

configtool str

default_value str

internal str, since 0.54.0

pkgconfig str

pkgconfig_define list[str]

since 0.52.0

since 0.48.0

since 0.46.0

If the parent has any dependencies, those will be applied to the new partial dependency with the same rules. So, given:

The following arguments will add the following attributes:

- compile_args: any arguments passed to the compiler
- link_args: any arguments passed to the linker
- links: anything passed via link_with or link_whole
- includes: any include_directories
- sources: any compiled or static sources the dependency has

includes bool, default: false

link_args bool, default: false

links bool, default: false

sources bool, default: false

since 1.4.0

since 0.55.0

NOTE: You should not usually need to use this method. Passing the object itself should work in most contexts where a program can appear, and allows Meson to setup inter-target dependencies correctly (for example in cases where a program might be overridden by a build_tgt). Only use this if you specifically need a string, such as when embedding a program path into a header file, or storing it into an environment variable.

For example:

deprecated since 0.55.0

Returns a string pointing to the script or executable.

NOTE: You should not usually need to use this method. Passing the object itself should work in most contexts where a program can appear, and allows Meson to setup inter-target dependencies correctly (for example in cases where a program might be overridden by a build_tgt). Only use this if you specifically need a string, such as when embedding a program path into a header file, or storing it into an environment variable.

For example:

since 0.62.0

`unknown` if the program cannot determine the version via a `--version` argument.

since 0.59.0

since 0.59.0

| Feature | `value = true` | `value = false` | | -------- | -------------- | --------------- | | Auto | Disabled | Auto | | Enabled | Enabled | Enabled | | Disabled | Disabled | Disabled |

since 1.1.0

| Feature | `value = true` | `value = false` | | -------- | -------------- | --------------- | | Auto | Disabled | Auto | | Enabled | Error | Enabled | | Disabled | Disabled | Disabled |

This is equivalent to `feature_opt.require(not condition)`, but may make code easier to reason about, especially when mixed with `enable_if`

since 1.1.0

| Feature | `value = true` | `value = false` | | -------- | -------------- | --------------- | | Auto | Enabled | Auto | | Enabled | Enabled | Enabled | | Disabled | Disabled | Disabled |

since 1.1.0

| Feature | `value = true` | `value = false` | | -------- | -------------- | --------------- | | Auto | Enabled | Auto | | Enabled | Enabled | Enabled | | Disabled | Error | Disabled |

since 0.59.0

| Feature | `value = true` | `value = false` | | -------- | -------------- | --------------- | | Auto | Auto | Disabled | | Enabled | Enabled | Error | | Disabled | Disabled | Disabled |

since 1.4.0