Ubuntu Manpage: meson-reference v1.5.1 - a reference for meson functions and objects

NAME

       meson-reference v1.5.1 - a reference for meson functions and objects

DESCRIPTION

       This  manual is divided into two sections, FUNCTIONS and OBJECTS.  FUNCTIONS contains a reference for all
       meson functions and  methods.   Methods  are  denoted  by  object_name.method_name().   OBJECTS  contains
       additional information about each object.

FUNCTIONS

add_global_arguments()
SYNOPSIS
void add_global_arguments(
Compiler argument...,
language:,
native: false,
)

DESCRIPTION
Adds global arguments to the compiler command line.

VARARGS
Compiler argument str, 0...N times
The compiler arguments to add

KWARGS
language list[str], required
Specifies the language(s) that the arguments should be applied to. If a list of languages is given,
the arguments are added to each of the corresponding compiler command lines. Note that there is no
way to remove an argument set in this way. If you have an argument that is only used in a subset of
targets, you have to specify it in per-target flags.

native bool, default: false, since 0.48.0
A boolean specifying whether the arguments should be applied to the native or cross compilation. If
`true` the arguments will only be used for native compilations. If `false` the arguments will only
be used in cross compilations. If omitted, the flags are added to native compilations if compiling
natively and cross compilations (only) when cross compiling.

NOTES
Usually you should use add_project_arguments instead, because that works even when you project is
used as a subproject. You must pass always arguments individually `arg1, arg2, ...` rather than as a
string `'arg1 arg2', ...`

add_global_link_arguments()
SYNOPSIS
void add_global_link_arguments(
Linker argument...,
language:,
native: false,
)

DESCRIPTION
Adds global arguments to the linker command line.

Like add_global_arguments but the arguments are passed to the linker.

VARARGS
Linker argument str, 0...N times
The linker arguments to add

NOTES
Usually you should use add_project_link_arguments instead, because that works even when you project
is used as a subproject. You must pass always arguments individually `arg1, arg2, ...` rather than
as a string `'arg1 arg2', ...`

add_languages()
SYNOPSIS
bool add_languages(Language..., native:, required: true)

DESCRIPTION
Add programming languages used by the project.

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.

VARARGS
Language str, 0...N times
The languages to add

KWARGS
native bool, since 0.54.0
If set to `true`, the language will be used to compile for the build machine, if `false`, for the
host machine.

required bool | feature, default: true
If set to `true`, Meson will halt if any of the languages specified are not found. (since 0.47.0)
The value of a `feature`[1] option can also be passed.

EXAMPLE

project('foobar', 'c')

if compiling_for_osx
add_languages('objc')
endif
if add_languages('cpp', required : false)
executable('cpp-app', 'main.cpp')
endif

# More code...

add_project_arguments()
SYNOPSIS
void add_project_arguments(
Compiler argument...,
language:,
native: false,
)

DESCRIPTION
Adds project specific arguments to the compiler command line.

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.

VARARGS
Compiler argument str, 0...N times
The compiler arguments to add

NOTES
You must pass always arguments individually `arg1, arg2, ...` rather than as a string `'arg1 arg2',
...`

add_project_dependencies()
SYNOPSIS
void add_project_dependencies(
dependencies...,
language:,
native: false,
)

since 0.63.0

DESCRIPTION
Adds arguments to the compiler and linker command line, so that the given set of dependencies is
included in all build products for this project.

VARARGS
dependencies dep, 0...N times
The dependencies to add; if internal dependencies are included, they must not include any built
object.

add_project_link_arguments()
SYNOPSIS
void add_project_link_arguments(
Linker argument...,
language:,
native: false,
)

DESCRIPTION
Adds project specific arguments to the linker command line.

Like add_project_arguments but the arguments are passed to the linker.

VARARGS
Linker argument str, 0...N times
The linker arguments to add

NOTES
You must pass always arguments individually `arg1, arg2, ...` rather than as a string `'arg1 arg2',
...`

add_test_setup()
SYNOPSIS
void add_test_setup(
name,
env:,
exclude_suites:,
exe_wrapper:,
gdb: false,
is_default: false,
timeout_multiplier: 1,
)

DESCRIPTION
Add a custom test setup. This setup can be used to run the tests with a custom setup, for example
under Valgrind.

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.

POSARGS
name str, required
The name of the test setup

KWARGS
env env | list[str] | dict[str]
environment variables to set , such as `['NAME1=value1', 'NAME2=value2']`, or an env object which
allows more sophisticated environment juggling. (Since 0.52.0) A dictionary is also accepted.

exclude_suites list[str], since 0.57.0
A list of test suites that should be excluded when using this setup. Suites specified in the
`--suite` option to `meson test` will always run, overriding `add_test_setup` if necessary.

exe_wrapper list[str | external_program]
The command or script followed by the arguments to it

gdb bool, default: false
If `true`, the tests are also run under `gdb`

is_default bool, default: false, since 0.49.0
Set whether this is the default test setup. If `true`, the setup will be used whenever `meson
test` is run without the `--setup` option.

timeout_multiplier int, default: 1
A number to multiply the test timeout with. Since 0.57 if timeout_multiplier is `<= 0` the test
has infinite duration, in previous versions of Meson the test would fail with a timeout
immediately.

alias_target()
SYNOPSIS
alias_tgt alias_target(target_name, Dep...)

since 0.52.0

DESCRIPTION
This function creates a new top-level target. Like all top-level targets, this integrates with the
selected backend. For instance, with you can run it as `meson compile target_name`. This is a dummy
target that does not execute any command, but ensures that all dependencies are built. Dependencies
can be any build target. Since 0.60.0, this includes run_tgt.

POSARGS
target_name str, required
The name of the alias target

VARARGS
Dep tgt, 1...N times
The targets to depend on

assert()
SYNOPSIS
void assert(condition, [message])

DESCRIPTION
Abort with an error message if `condition` evaluates to `false`.

POSARGS
condition bool, required
Abort if this evaluates to `false`

OPTARGS
message str
The error message to print.

NOTES
The `message` argument is optional since 0.53.0 and defaults to print the condition statement.

benchmark()
SYNOPSIS
void benchmark(
name,
executable,
args:,
depends:,
env:,
priority: 0,
protocol: 'exitcode',
should_fail: false,
suite:,
timeout: 30,
verbose: false,
workdir:,
)

DESCRIPTION
Creates a benchmark item that will be run when the benchmark target is run. The behavior of this
function is identical to test except for:

* 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`.

POSARGS
name str, required
The unique test id

KWARGS
args list[str | file | build_tgt | custom_tgt | custom_idx]
Arguments to pass to the executable

depends list[build_tgt | custom_tgt], since 0.46.0
specifies that this test depends on the specified target(s), even though it does not take any of
them as a command line argument. This is meant for cases where test finds those targets internally,
e.g. plugins or globbing. Those targets are built before test is executed even if they have
`build_by_default : false`.

env env | list[str] | dict[str]
environment variables to set, such as `['NAME1=value1', ´NAME2=value2']`, or an env object which
allows more sophisticated environment juggling. (Since 0.52.0) A dictionary is also accepted.

priority int, default: 0, since 0.52.0
specifies the priority of a test. Tests with a higher priority are started before tests with a
lower priority. The starting order of tests with identical priorities is implementation-defined.
The default priority is 0, negative numbers are permitted.

protocol str, default: 'exitcode', since 0.50.0
specifies how the test results are parsed and can be one of `exitcode`, `tap`, or `gtest`. For more
information about test harness protocol read Unit Tests[2]. The following values are accepted:

- `exitcode`: the executable's exit code is used by the test harness to record the outcome of the
test).
- `tap`: Test Anything Protocol[3].
- `gtest` (since 0.55.0): for Google Tests.
- `rust` (since 0.56.0): for native rust tests

should_fail bool, default: false
when true the test is considered passed if the executable returns a non-zero return value (i.e.
reports an error)

suite str | list[str]
`'label'` (or list of labels `['label1', 'label2']`) attached to this test. The suite name is
qualified by a (sub)project name resulting in `(sub)project_name:label`. In the case of a list of
strings, the suite names will be `(sub)project_name:label1`, `(sub)project_name:label2`, etc.

timeout int, default: 30
the amount of seconds the test is allowed to run, a test that exceeds its time limit is always
considered failed, defaults to 30 seconds. Since 0.57 if timeout is `<= 0` the test has infinite
duration, in previous versions of Meson the test would fail with a timeout immediately.

verbose bool, default: false, since 0.62.0
if true, forces the test results to be logged as if `--verbose` was passed to `meson test`.

workdir str
absolute path that will be used as the working directory for the test

NOTES
Prior to 0.52.0 benchmark would warn that `depends` and `priority` were unsupported, this is
incorrect.

both_libraries()
SYNOPSIS
both_libs both_libraries(
target_name,
source...,
<lang>_args:,
<lang>_pch:,
<lang>_shared_args:,
<lang>_static_args:,
build_by_default: true,
build_rpath:,
d_debug:,
d_import_dirs:,
d_module_versions:,
d_unittest: false,
darwin_versions:,
dependencies:,
extra_files:,
gnu_symbol_visibility:,
gui_app: false,
implicit_include_directories: true,
include_directories:,
install: false,
install_dir:,
install_mode:,
install_rpath:,
install_tag:,
link_args:,
link_depends:,
link_language:,
link_whole:,
link_with:,
name_prefix:,
name_suffix:,
native: false,
objects:,
override_options:,
pic:,
prelink:,
rust_abi:,
rust_crate_type:,
rust_dependency_map:,
sources:,
soversion:,
vala_args:,
vala_shared_args:,
vala_static_args:,
version:,
vs_module_defs:,
win_subsystem: 'console',
)

since 0.46.0

DESCRIPTION
Builds both a static and shared library with the given sources. Positional and keyword arguments are
otherwise the same as for library. Source files will be compiled only once and object files will be
reused to build both shared and static libraries, unless `b_staticpic` user option or `pic` argument
are set to false in which case sources will be compiled twice.

POSARGS
target_name str, required
The unique name of the build target

VARARGS
source str | file | custom_tgt | custom_idx | generated_list, 0...N times
Input source to compile. The following types are supported:

- Strings relative to the current source directory
- file objects defined in any preceding build file
- The return value of configure-time generators such as configure_file
- The return value of build-time generators such as custom_target or generator.process

These input files can be sources, objects, libraries, or any other file. Meson will automatically
categorize them based on the extension and use them accordingly. For instance, sources (`.c`,
`.cpp`, `.vala`, `.rs`, etc) will be compiled and objects (`.o`, `.obj`) and libraries (`.so`,
`.dll`, etc) will be linked.

With the Ninja backend, Meson will create a build-time order-only dependency[4] on all generated
input files, including unknown files. This is needed to bootstrap the generation of the real
dependencies in the depfile[5] generated by your compiler to determine when to rebuild sources.
Ninja relies on this dependency file for all input files, generated and non-generated. The
behavior is similar for other backends.

KWARGS
<lang>_args list[str]
compiler flags to use for the given language; eg: `cpp_args` for C++

<lang>_pch str
precompiled header file to use for the given language

<lang>_shared_args list[str], since 1.3.0
Arguments that are only passed to a shared library

<lang>_static_args list[str], since 1.3.0
Arguments that are only passed to a static library

build_by_default bool, default: true, since 0.38.0
Causes, when set to `true`, to have this target be built by default. This means it will be built
when `meson compile` is called without any arguments. The default value is `true` for all built
target types.

build_rpath str, since 0.42.0
A string to add to target's rpath definition in the build dir, but which will be removed on install

d_debug list[str]
The D version identifiers[6] to add during the compilation of D source files.

d_import_dirs list[str]
List of directories to look in for string imports used in the D programming language.

d_module_versions list[str | int]
List of module version identifiers set when compiling D sources.

d_unittest bool, default: false
When set to true, the D modules are compiled in debug mode.

darwin_versions str | int | list[str], since 0.48.0
Defines the `compatibility version` and `current version` for the dylib on macOS. If a list is
specified, it must be either zero, one, or two elements. If only one element is specified or if
it's not a list, the specified value will be used for setting both compatibility version and
current version. If unspecified, the `soversion` will be used as per the aforementioned rules.

dependencies list[dep]
one or more dependency objects created with dependency or compiler.find_library (for external deps)
or declare_dependency (for deps built by the project)

extra_files str | file | custom_tgt | custom_idx
Not used for the build itself but are shown as source files in IDEs that group files by targets
(such as Visual Studio)

gnu_symbol_visibility str, since 0.48.0
Specifies how symbols should be exported, see e.g the GCC Wiki[7] for more information. This value
can either be an empty string or one of `default`, `internal`, `hidden`, `protected` or
`inlineshidden`, which is the same as `hidden` but also includes things like C++ implicit
constructors as specified in the GCC manual. Ignored on compilers that do not support GNU
visibility arguments.

gui_app bool, default: false, deprecated since 0.56.0
When set to true flags this target as a GUI application on platforms where this makes a difference,
deprecated since 0.56.0, use `win_subsystem` instead.

implicit_include_directories bool, default: true, since 0.42.0
Controls whether Meson adds the current source and build directories to the include path

include_directories list[inc | str]
one or more objects created with the include_directories function, or (since 0.50.0) strings, which
will be transparently expanded to include directory objects

install bool, default: false
When set to true, this executable should be installed.

install_dir str
override install directory for this file. If the value is a relative path, it will be considered
relative the `prefix` option. For example, if you want to install plugins into a subdir, you'd use
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.

install_mode list[str | int], since 0.47.0
Specify the file mode in symbolic format and optionally the owner/uid and group/gid for the
installed files.

See the `install_mode` kwarg of install_data for more information.

install_rpath str
A string to set the target's rpath to after install (but not before that). On Windows, this
argument has no effect.

install_tag str, since 0.60.0
A string used by the `meson install --tags` command to install only a subset of the files. By
default all build targets have the tag `runtime` except for static libraries that have the `devel`
tag.

link_args list[str]
Flags to use during linking. You can use UNIX-style flags here for all platforms.

link_depends str | file | custom_tgt | custom_idx
Strings, files, or custom targets the link step depends on such as a symbol visibility map. The
purpose is to automatically trigger a re-link (but not a re-compile) of the target when this file
changes.

link_language str, since 0.51.0
Makes the linker for this target be for the specified language. It is generally unnecessary to set
this, as Meson will detect the right linker to use in most cases. There are only two cases where
this is needed. One, your main function in an executable is not in the language Meson picked, or
second you want to force a library to use only one ABI.

(broken until 0.55.0)

link_whole list[lib | custom_tgt | custom_idx], since 0.40.0
Links all contents of the given static libraries whether they are used or not, equivalent to the
`-Wl,--whole-archive` argument flag of GCC, or the ´/WHOLEARCHIVE' MSVC linker option. This allows
the linked target to re-export symbols from all objects in the static libraries.

(since 0.41.0) If passed a list that list will be flattened.

(since 0.51.0) This argument also accepts outputs produced by custom targets. The user must ensure
that the output is a library in the correct format.

link_with list[lib | custom_tgt | custom_idx]
One or more shared or static libraries (built by this project) that this target should be linked
with. (since 0.41.0) If passed a list this list will be flattened. (since 0.51.0) The arguments can
also be custom targets. In this case Meson will assume that merely adding the output file in the
linker command line is sufficient to make linking work. If this is not sufficient, then the build
system writer must write all other steps manually.

name_prefix str | list[void]
The string that will be used as the prefix for the target output filename by overriding the default
(only used for libraries). By default this is `lib` on all platforms and compilers, except for MSVC
shared libraries where it is omitted to follow convention, and Cygwin shared libraries where it is
`cyg`.

Set this to `[]`, or omit the keyword argument for the default behaviour.

name_suffix str | list[void]
The string that will be used as the extension for the target by overriding the default. By default
on Windows this is `exe` for executables and on other platforms it is omitted.

For shared libraries, the default value is `dylib` on macOS, `dll` on Windows, and `so` everywhere
else. For static libraries, it is `a` everywhere. By convention MSVC static libraries use the
`lib` suffix, but we use `a` to avoid a potential name clash with shared libraries which also
generate import libraries with a `lib` suffix.

Set this to `[]`, or omit the keyword argument for the default behaviour.

native bool, default: false
Controls whether the target is compiled for the build or host machines.

objects list[extracted_obj | file | str]
List of object files that should be linked in this target.

Since 1.1.0 this can include generated files in addition to object files that you don't have source
to or that object files produced by other build targets. In earlier release, generated object
files had to be placed in `sources`.

override_options list[str] | dict[str | bool | int | list[str]], since 0.40.0
takes an array of strings in the same format as `project`'s `default_options` overriding the values
of these options for this target only. (since 1.2.0): A dictionary may now be passed.

pic bool, since 0.36.0
Builds the library as positional independent code (so it can be linked into a shared library). This
option has no effect on Windows and OS X since it doesn't make sense on Windows and PIC cannot be
disabled on OS X.

prelink bool, since 0.57.0
If `true` the object files in the target will be prelinked, meaning that it will contain only one
prelinked object file rather than the individual object files.

rust_abi str, since 1.3.0
Set the specific ABI to compile (when compiling rust). - 'rust' (default): Create a "rlib" or
"dylib" crate depending on the library type being build.
- 'c': Create a "cdylib" or "staticlib" crate depending on the library type being build.

rust_crate_type str, deprecated since 1.3.0, since 0.42.0
Set the specific type of rust crate to compile (when compiling rust).

If the target is an executable this defaults to "bin", the only allowed value.

If it is a static_library it defaults to "lib", and may be "lib", "staticlib", or "rlib". If "lib"
then Rustc will pick a default, "staticlib" means a C ABI library, "rlib" means a Rust ABI.

If it is a shared_library it defaults to "lib", and may be "lib", "dylib", "cdylib", or "proc-
macro". If "lib" then Rustc will pick a default, "cdylib" means a C ABI library, "dylib" means a
Rust ABI, and "proc-macro" is a special rust procedural macro crate.

"proc-macro" is new in 0.62.0.

Since 1.3.0 this is deprecated and replaced by "rust_abi" keyword argument. `proc_macro` crates
are now handled by the `rust.proc_macro()`[8] method.

rust_dependency_map dict[str], since 1.2.0
On rust targets this provides a map of library names to the crate name with which it would be
available inside the rust code.

This allows renaming similar to the dependency renaming feature of cargo or `extern crate foo as
bar` inside rust code.

soversion str | int
A string or integer specifying the soversion of this shared library, such as `0`. On Linux and
Windows this is used to set the soversion (or equivalent) in the filename. For example, if
`soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one of the aliases of the Linux
shared library would be `libfoo.so.4`. If this is not specified, the first part of `version` is
used instead (see below). For example, if `version` is `3.6.0` and `soversion` is not defined, it
is set to `3`.

vala_args list[str | file]
Compiler flags for Vala. Unlike other languages this may contain Files

vala_shared_args list[str | file], since 1.3.0
Arguments that are only passed to a shared library Like `vala_args`, files is allowed in addition
to string

vala_static_args list[str | file], since 1.3.0
Arguments that are only passed to a static library Like `vala_args`, files is allowed in addition
to string

version str
A string specifying the version of this shared library, such as `1.1.0`. On Linux and OS X, this is
used to set the shared library version in the filename, such as `libfoo.so.1.1.0` and
`libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used instead (see above).

vs_module_defs str | file | custom_tgt | custom_idx
Specify a Microsoft module definition file for controlling symbol exports, etc., on platforms where
that is possible (e.g. Windows).

(Since 1.3.0) custom_idx are supported

win_subsystem str, default: 'console', since 0.56.0
Specifies the subsystem type to use on the Windows platform. Typical values include `console` for
text mode programs and `windows` for gui apps. The value can also contain version specification
such as `windows,6.0`. See MSDN documentation[9] for the full list.

build_target()
SYNOPSIS
build_tgt build_target(
target_name,
source...,
<lang>_args:,
<lang>_pch:,
<lang>_shared_args:,
<lang>_static_args:,
build_by_default: true,
build_rpath:,
d_debug:,
d_import_dirs:,
d_module_versions:,
d_unittest: false,
darwin_versions:,
dependencies:,
export_dynamic:,
extra_files:,
gnu_symbol_visibility:,
gui_app: false,
implib:,
implicit_include_directories: true,
include_directories:,
install: false,
install_dir:,
install_mode:,
install_rpath:,
install_tag:,
java_resources:,
link_args:,
link_depends:,
link_language:,
link_whole:,
link_with:,
main_class:,
name_prefix:,
name_suffix:,
native: false,
objects:,
override_options:,
pic:,
pie:,
prelink:,
rust_abi:,
rust_crate_type:,
rust_dependency_map:,
sources:,
soversion:,
target_type:,
vala_args:,
vala_shared_args:,
vala_static_args:,
version:,
vs_module_defs:,
win_subsystem: 'console',
)

DESCRIPTION
Creates a build target whose type can be set dynamically with the `target_type` keyword argument.

`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:
executable(<arguments and keyword arguments>)
is equivalent to this:
build_target(<arguments and keyword arguments>, target_type : 'executable')
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 build_tgt.

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

POSARGS
target_name str, required
The unique name of the build target

VARARGS
source str | file | custom_tgt | custom_idx | generated_list, 0...N times
Input source to compile. The following types are supported:

With the Ninja backend, Meson will create a build-time order-only dependency[3] on all generated
input files, including unknown files. This is needed to bootstrap the generation of the real
dependencies in the depfile[4] generated by your compiler to determine when to rebuild sources.
Ninja relies on this dependency file for all input files, generated and non-generated. The
behavior is similar for other backends.

KWARGS
<lang>_args list[str]
compiler flags to use for the given language; eg: `cpp_args` for C++

<lang>_pch str
precompiled header file to use for the given language

<lang>_shared_args list[str], since 1.3.0
Arguments that are only passed to a shared library

<lang>_static_args list[str], since 1.3.0
Arguments that are only passed to a static library

build_rpath str, since 0.42.0
A string to add to target's rpath definition in the build dir, but which will be removed on install

d_debug list[str]
The D version identifiers[5] to add during the compilation of D source files.

d_import_dirs list[str]
List of directories to look in for string imports used in the D programming language.

d_module_versions list[str | int]
List of module version identifiers set when compiling D sources.

d_unittest bool, default: false
When set to true, the D modules are compiled in debug mode.

dependencies list[dep]
one or more dependency objects created with dependency or compiler.find_library (for external deps)
or declare_dependency (for deps built by the project)

export_dynamic bool, since 0.45.0
when set to true causes the target's symbols to be
dynamically exported, allowing modules built using the
shared_module function to refer to functions,
variables and other symbols defined in the executable itself. Implies
the `implib` argument.

extra_files str | file | custom_tgt | custom_idx
Not used for the build itself but are shown as source files in IDEs that group files by targets
(such as Visual Studio)

gnu_symbol_visibility str, since 0.48.0
Specifies how symbols should be exported, see e.g the GCC Wiki[6] for more information. This value
can either be an empty string or one of `default`, `internal`, `hidden`, `protected` or
`inlineshidden`, which is the same as `hidden` but also includes things like C++ implicit
constructors as specified in the GCC manual. Ignored on compilers that do not support GNU
visibility arguments.

implib bool | str, since 0.42.0
When set to true, an import library is generated for the executable (the name of the import library
is based on exe_name). Alternatively, when set to a string, that gives the base name for the
import library. The import library is used when the returned build target object appears in
`link_with:` elsewhere. Only has any effect on platforms where that is meaningful (e.g. Windows).
Implies the `export_dynamic` argument.

implicit_include_directories bool, default: true, since 0.42.0
Controls whether Meson adds the current source and build directories to the include path

include_directories list[inc | str]
one or more objects created with the include_directories function, or (since 0.50.0) strings, which
will be transparently expanded to include directory objects

install bool, default: false
When set to true, this executable should be installed.

install_mode list[str | int], since 0.47.0
Specify the file mode in symbolic format and optionally the owner/uid and group/gid for the
installed files.

See the `install_mode` kwarg of install_data for more information.

install_rpath str
A string to set the target's rpath to after install (but not before that). On Windows, this
argument has no effect.

java_resources structured_src, since 0.62.0
Resources to be added to the jar

link_args list[str]
Flags to use during linking. You can use UNIX-style flags here for all platforms.

(broken until 0.55.0)

(since 0.41.0) If passed a list that list will be flattened.

(since 0.51.0) This argument also accepts outputs produced by custom targets. The user must ensure
that the output is a library in the correct format.

main_class str
Main class for running the built jar

Set this to `[]`, or omit the keyword argument for the default behaviour.

native bool, default: false
Controls whether the target is compiled for the build or host machines.

objects list[extracted_obj | file | str]
List of object files that should be linked in this target.

pie bool, since 0.49.0
Build a position-independent executable.

prelink bool, since 0.57.0
If `true` the object files in the target will be prelinked, meaning that it will contain only one
prelinked object file rather than the individual object files.

rust_crate_type str, deprecated since 1.3.0, since 0.42.0
Set the specific type of rust crate to compile (when compiling rust).

If the target is an executable this defaults to "bin", the only allowed value.

If it is a static_library it defaults to "lib", and may be "lib", "staticlib", or "rlib". If "lib"
then Rustc will pick a default, "staticlib" means a C ABI library, "rlib" means a Rust ABI.

"proc-macro" is new in 0.62.0.

Since 1.3.0 this is deprecated and replaced by "rust_abi" keyword argument. `proc_macro` crates
are now handled by the `rust.proc_macro()`[7] method.

rust_dependency_map dict[str], since 1.2.0
On rust targets this provides a map of library names to the crate name with which it would be
available inside the rust code.

This allows renaming similar to the dependency renaming feature of cargo or `extern crate foo as
bar` inside rust code.

target_type str
The actual target type to build

vala_args list[str | file]
Compiler flags for Vala. Unlike other languages this may contain Files

vala_shared_args list[str | file], since 1.3.0
Arguments that are only passed to a shared library Like `vala_args`, files is allowed in addition
to string

vala_static_args list[str | file], since 1.3.0
Arguments that are only passed to a static library Like `vala_args`, files is allowed in addition
to string

vs_module_defs str | file | custom_tgt | custom_idx, since 1.3.0
Specify a Microsoft module definition file for controlling symbol exports, etc., on platforms where
that is possible (e.g. Windows).

This can be used to expose which functions a shared_module loaded by an executable will be allowed
to use.

configuration_data()
SYNOPSIS
cfg_data configuration_data([data])

DESCRIPTION
Creates an empty configuration object. You should add your configuration with the cfg_data method
calls and finally use it in a call to configure_file.

OPTARGS
data dict[str | bool | int], since 0.49.0
Optional dictionary to specify an initial data set. If provided, each key/value pair is added into
the cfg_data object as if the cfg_data.set method was called for each of them.

configure_file()
SYNOPSIS
file configure_file(
capture: false,
command:,
configuration:,
copy: false,
depfile:,
encoding: 'utf-8',
format: 'meson',
input:,
install: false,
install_dir:,
install_mode:,
install_tag:,
macro_name:,
output:,
output_format:,
)

DESCRIPTION
This function can run in three modes depending on the keyword arguments passed to it.

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.

KWARGS
capture bool, default: false, since 0.41.0
When this argument is set to true, Meson captures `stdout` of the `command` and writes it to the
target file specified as `output`.

command list[str | file | compiler | external_program | exe]
As explained above, if specified, Meson does not create the file itself but rather runs the
specified command, which allows you to do fully custom file generation. (since 0.52.0) The command
can contain file objects and more than one file can be passed to the `input` keyword argument, see
custom_target for details about string substitutions.

configuration cfg_data | dict[str | int | bool]
As explained above, when passed this will provide the replacement data for the input file (if
provided) or key value pairs to be written to the output.

copy bool, default: false, since 0.47.0
As explained above, if specified Meson only copies the file from input to output.

depfile str, since 0.52.0
A dependency file that the command can write listing all the additional files this target depends
on. A change in any one of these files triggers a reconfiguration.

encoding str, default: 'utf-8', since 0.47.0
Set the file encoding for the input and output file. The supported encodings are those of python3,
see standard-encodings[11].

format str, default: 'meson', since 0.46.0
The format of defines. It defaults to `'meson'`, and so substitutes `#mesondefine` statements and
variables surrounded by `@` characters, you can also use `'cmake'` to replace `#cmakedefine`
statements and variables with the `${variable}` syntax. Finally you can use `'cmake@'` in which
case substitutions will apply on `#cmakedefine` statements and variables with the `@variable@`
syntax.

input str | file
The input file name. If it's not specified in configuration mode, all the variables in the
`configuration:` object (see above) are written to the `output:` file.

install bool, default: false, since 0.50.0
When true, this generated file is installed during the install step, and `install_dir` must be set
and not empty. When false, this generated file is not installed regardless of the value of
`install_dir`. When omitted it defaults to true when `install_dir` is set and not empty, false
otherwise.

install_dir str | bool
The subdirectory to install the generated file to (e.g. `share/myproject`), if omitted or given the
value of empty string, the file is not installed.

install_mode list[str | int | bool], since 0.47.0
Specify the file mode in symbolic format and optionally the owner/uid and group/gid for the
installed files.

See the `install_mode` kwarg of install_data for more information.

install_tag str, since 0.60.0
A string used by the `meson install --tags` command to install only a subset of the files. By
default the file has no install tag which means it is not being installed when `--tags` argument is
specified.

macro_name str, since 1.3.0
When specified, macro guards will be used instead of '#pragma once'. The macro guard name will be
the specified name.

output str
The output file name. (since 0.41.0) may contain `@PLAINNAME@` or `@BASENAME@` substitutions, as
well as (since 1.5.0) their indexed versions, like `@PLAINNAME0@` or `@BASENAME0@`. In
configuration mode, the permissions of the input file (if it is specified) are copied to the output
file.

output_format str, since 0.47.0
The format of the output to generate when no input was specified. It defaults to `c`, in which case
preprocessor directives will be prefixed with `#`, you can also use `nasm`, in which case the
prefix will be `%`. (since 1.3.0) `json` format can also be used.

WARNINGS
the `install_mode` kwarg ignored integer values between 0.62 -- 1.1.0.

custom_target()
SYNOPSIS
custom_tgt custom_target(
[name],
build_always:,
build_always_stale: false,
build_by_default:,
capture: false,
command:,
console:,
depend_files:,
depends:,
depfile:,
env:,
feed: false,
input:,
install:,
install_dir:,
install_mode:,
install_tag:,
output:,
)

DESCRIPTION
Create a custom top level build target. The only positional argument is the name of this target and
cannot contain path separators (`/` or ``). The name of custom target might not be used by every
backends, for instance with the Ninja backend, `subdir/meson.build` containing the example below,
`ninja -C builddir foo` or `ninja -C builddir subdir/foo` won't work, it is instead `ninja -C
builddir subdir/file.txt`. However, `meson compile subdir/foo` is accepted.
custom_target('foo', output: 'file.txt', ...)
Since 0.60.0 the name argument is optional and defaults to the basename of the first output
(`file.txt` in the example above).

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
- `@PLAINNAME0@` `@PLAINNAME1@` `...` (since 1.5.0): the input filename without a path, with the
specified array index in `input`
- `@BASENAME@`: the input filename, with extension removed
- `@BASENAME0@` `@BASENAME1@` `...` (since 1.5.0): the input filename with extension removed, with
the specified array index in `input`
- `@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.

OPTARGS
name str
The unique id of the custom target

This posarg is optional since 0.60.0. It defaults to the basename of the first output.

KWARGS
build_always bool, deprecated since 0.47.0
If `true` this target is always considered out of date and is rebuilt every time. Equivalent to
setting both `build_always_stale` and `build_by_default` to true.

build_always_stale bool, default: false, since 0.47.0
If `true` the target is always considered out of date. Useful for things such as build timestamps
or revision control tags. The associated command is run even if the outputs are up to date.

build_by_default bool, since 0.38.0
Causes, when set to true, to have this target be built by default. This means it will be built when
`meson compile` is called without any arguments. The default value is `false`.

(since 0.50.0) If `build_by_default` is explicitly set to false, `install` will no longer override
it. If `build_by_default` is not set, `install` will still determine its default.

capture bool, default: false
There are some compilers that can't be told to write their output to a file but instead write it to
standard output. When this argument is set to true, Meson captures `stdout` and writes it to the
target file. Note that your command argument list may not contain `@OUTPUT@` when capture mode is
active.

command list[str | file | exe | external_program | custom_tgt | build_tgt | custom_idx]
Command to run to create outputs from inputs. The command may be strings or the return value of
functions that return file-like objects such as find_program, executable, configure_file, files,
custom_target, etc. Meson will automatically insert the appropriate dependencies on targets and
files listed in this keyword argument. Note: always specify commands in array form
`['commandname', ´-arg1', '-arg2']` rather than as a string `'commandname -arg1 -arg2'` as the
latter will not work.

console bool, since 0.48.0
Keyword argument conflicts with `capture`, and is meant for commands that are resource-intensive
and take a long time to finish. With the Ninja backend, setting this will add this target to
Ninja's `console` pool[12], which has special properties such as not buffering stdout and
serializing all targets in this pool.

depend_files list[str | file]
files (str, file, or the return value of configure_file that this target depends on but are not
listed in the `command` keyword argument. Useful for adding regen dependencies.

depends list[build_tgt | custom_tgt | custom_idx]
Specifies that this target depends on the specified target(s), even though it does not take any of
them as a command line argument. This is meant for cases where you have a tool that e.g. does
globbing internally. Usually you should just put the generated sources as inputs and Meson will set
up all dependencies automatically (custom_idx was unavailable as a type between 0.60 and 1.4.0).

depfile str
A dependency file that the command can write listing all the additional files this target depends
on, for example a C compiler would list all the header files it included, and a change in any one
of these files triggers a recompilation.

(since 0.47.0) the `@BASENAME@` and `@PLAINNAME@` substitutions are also accepted.

env env | list[str] | dict[str], since 0.57.0
environment variables to set, such as `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1',
'NAME2=value2']`, or an env object which allows more sophisticated environment juggling.

feed bool, default: false, since 0.59.0
There are some compilers that can't be told to read their input from a file and instead read it
from standard input. When this argument is set to `true`, Meson feeds the input file to `stdin`.
Note that your argument list may not contain `@INPUT@` when feed mode is active.

install bool
When true, one or more files of this target are installed during the install step (see
`install_dir` for details).

install_dir bool | str | list[bool | str]
If only one install_dir is provided, all outputs are installed there. Since 0.40.0 Allows you to
specify the installation directory for each corresponding output. For example:
custom_target('different-install-dirs',
output : ['first.file', 'second.file'],
install : true,
install_dir : ['somedir', 'otherdir'])
This would install `first.file` to `somedir` and `second.file` to `otherdir`.

To only install some outputs, pass `false` for the outputs that you don't want installed. For
example:
custom_target('only-install-second',
output : ['first.file', 'second.file'],
install : true,
install_dir : [false, 'otherdir'])
This would install `second.file` to `otherdir` and not install `first.file`.

install_mode list[str | int | bool], since 0.47.0
The file mode and optionally the owner/uid and group/gid. See the `install_mode` kwarg of
install_data for more information.

install_tag list[str | bool], since 0.60.0
A list of strings, one per output, used by the `meson install --tags` command to install only a
subset of the files.

By default all outputs have no install tag which means they are not being installed when `--tags`
argument is specified. If only one tag is specified, it is assumed that all outputs have the same
tag. `false` can be used for outputs that have no tag or are not installed.

output list[str]
List of output files.

NOTES
Assuming that `command:` is executed by a POSIX `sh` shell is not portable, notably to Windows.
Instead, consider using a `native: true` executable, or a python script.
WARNINGS
the `install_mode` kwarg ignored integer values between 0.60.0 -- 1.1.0.

debug()
SYNOPSIS
void debug(message, msg...)

since 0.63.0

DESCRIPTION
Write the argument string to the meson build log.

declare_dependency()
SYNOPSIS
dep declare_dependency(
compile_args:,
d_import_dirs:,
d_module_versions:,
dependencies:,
extra_files:,
include_directories:,
link_args:,
link_whole:,
link_with:,
objects:,
sources:,
variables:,
version:,
)

DESCRIPTION
This function returns a dep object that behaves like the return value of dependency but is internal
to the current build. The main use case for this is in subprojects. This allows a subproject to
easily specify how it should be used. This makes it interchangeable with the same dependency that is
provided externally by the system.

KWARGS
compile_args list[str]
Compile arguments to use.

d_import_dirs list[inc | str], since 0.62.0
the directories to add to the string search path (i.e. `-J` switch for DMD). Must be inc objects
or plain strings.

d_module_versions str | int | list[str | int], since 0.62.0
The D version identifiers[5] to add during the compilation of D source files.

dependencies list[dep]
Other dependencies needed to use this dependency.

extra_files list[str | file], since 1.2.0
extra files to add to targets. mostly used for IDE integration.

include_directories list[inc | str]
the directories to add to header search path, must be inc objects or (since 0.50.0) plain strings.

link_args list[str]
Link arguments to use.

link_whole list[lib], since 0.46.0
Libraries to link fully, same as executable.

link_with list[lib]
Libraries to link against.

objects list[extracted_obj], since 1.1.0
a list of object files, to be linked directly into the targets that use the dependency.

sources list[str | file | custom_tgt | custom_idx | generated_list]
sources to add to targets (or generated header files that should be built before sources including
them are built)

variables dict[str] | list[str], since 0.54.0
a dictionary of arbitrary strings, this is meant to be used in subprojects where special variables
would be provided via cmake or pkg-config. since 0.56.0 it can also be a list of `'key=value'`
strings.

version str
the version of this dependency, such as `1.2.3`. Defaults to the project version.

dependency()
SYNOPSIS
dep dependency(
names...,
allow_fallback:,
default_options:,
disabler: false,
fallback:,
include_type: 'preserve',
language:,
method: 'auto',
native: false,
not_found_message:,
required: true,
static: false,
version:,
)

DESCRIPTION
Finds an external dependency (usually a library installed on your system) with the given name with
`pkg-config` and with CMake[13] if `pkg-config` fails. Additionally, frameworks (OSX only) and
library-specific fallback detection logic[14] are also supported.

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.

VARARGS
names str, 1...N times, since 0.60.0
The names of the dependency to look up. The dependencies are looked up in the order they are
provided here. The first found dependency will then 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`.

NOTE: Before 0.60.0 only a single dependency name was allowed.

KWARGS
allow_fallback bool, since 0.56.0
Specifies whether Meson should automatically pick a fallback subproject in case the dependency is
not found in the system. If `true` and the dependency is not found on the system, Meson will
fallback to a subproject that provides this dependency. If `false`, Meson will not fallback even if
a subproject provides this dependency. By default, Meson will do so if `required` is `true` or
`enabled`[0]; see the Wrap documentation[14] for more details.

default_options list[str] | dict[str | bool | int | list[str]], since 0.38.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 1.2.0): A dictionary may
now be passed.

disabler bool, default: false, since 0.49.0
Returns a disabler object instead of a not-found dependency if this kwarg is set to `true` and the
dependency couldn't be found.

fallback list[str] | str
Manually specifies a subproject fallback to use in case the dependency is not found in the system.
This is useful if the automatic search is not applicable or if you want to support versions of
Meson older than 0.55.0. If the value is an array `['subproj_name', 'subproj_dep']`, the first
value is the name of the subproject and the second is the variable name in that subproject that
contains a dependency object such as the return value of declare_dependency or dependency, etc.
Note that this means the fallback dependency may be a not-found dependency, in which case the value
of the `required:` kwarg will be obeyed. Since 0.54.0 the value can be a single string, the
subproject name; in this case the subproject must use `meson.override_dependency('dependency_name',
subproj_dep)` to specify the dependency object used in the superproject. If the value is an empty
list, it has the same effect as `allow_fallback: false`.

include_type str, default: 'preserve', since 0.52.0
An enum flag, marking how the dependency flags should be converted. Supported values are
`'preserve'`, `'system'` and `'non-system'`. System dependencies may be handled differently on some
platforms, for instance, using `-isystem` instead of `-I`, where possible. If `include_type` is
set to `'preserve'`, no additional conversion will be performed.

language str, since 0.42.0
Defines what language-specific dependency to find if it's available for multiple languages.

method str, default: 'auto', since 0.40.0
Defines the way the dependency is detected, the default is `auto` but can be overridden to be e.g.
`qmake` for Qt development, and different dependencies support different values[16] for this
(though `auto` will work on all of them)

native bool, default: false
If set to `true`, causes Meson to find the dependency on the build machine system rather than the
host system (i.e. where the cross compiled binary will run on), usually only needed if you build a
tool to be used during compilation.

not_found_message str, since 0.50.0
An optional string that will be printed as a message if the dependency was not found.

required bool | feature, default: true
When set to `false`, Meson will proceed with the build even if the dependency is not found.

When set to a `feature`[0] option, the feature will control if it is searched and whether to fail
if not found.

(since 0.47.0) The value of a `feature` option can also be passed.

static bool, default: false
Tells the dependency provider to try to get static libraries instead of dynamic ones (note that
this is not supported by all dependency backends)

Since 0.60.0 it also sets `default_library` option accordingly on the fallback subproject if it was
not set explicitly in `default_options` keyword argument.

version list[str] | str, since 0.37.0
Specifies the required version, a string containing a comparison operator followed by the version
string, examples include `>1.0.0`, `<=2.3.5` or `3.1.4` for exact matching. You can also specify
multiple restrictions by passing a list to this keyword argument, such as: `['>=3.14.0',
'<=4.1.0']`. These requirements are never met if the version is unknown.

NOTES
This function supports additional library-specific[13] keyword arguments that may also be accepted
(e.g. `modules` specifies submodules to use for dependencies such as Qt5 or Boost. `components`
allows the user to manually add CMake `COMPONENTS` for the `find_package` lookup)

disabler()
SYNOPSIS
disabler disabler()

since 0.44.0

DESCRIPTION
Returns a disabler object.

environment()
SYNOPSIS
env environment([env], method:, separator:)

since 0.35.0

DESCRIPTION
Returns an empty env object.

OPTARGS
env str | list[str] | dict[str] | dict[list[str]], since 0.52.0
If provided, each key/value pair is added into the env object as if env.set method was called for
each of them. Since 0.62.0 list of strings is allowed in dictionary values. In that case values
are joined using the separator.

KWARGS
method str, since 0.62.0
Must be one of 'set', 'prepend', or 'append' (defaults to 'set'). Controls if initial values
defined in the first positional argument are prepended, appended or replace the current value of
the environment variable.

separator str, since 0.62.0
The separator to use for the initial values defined in the first positional argument. If not
explicitly specified, the default path separator for the host operating system will be used, i.e.
';' for Windows and ':' for UNIX/POSIX systems.

error()
SYNOPSIS
void error(message, msg...)

DESCRIPTION
Print the argument string and halts the build process.

POSARGS
message str, required
The message to print

VARARGS
msg str, 0...N times, since 0.58.0
Additional parameters will be separated by spaces

executable()
SYNOPSIS
exe executable(
target_name,
source...,
<lang>_args:,
<lang>_pch:,
build_by_default: true,
build_rpath:,
d_debug:,
d_import_dirs:,
d_module_versions:,
d_unittest: false,
dependencies:,
export_dynamic:,
extra_files:,
gnu_symbol_visibility:,
gui_app: false,
implib:,
implicit_include_directories: true,
include_directories:,
install: false,
install_dir:,
install_mode:,
install_rpath:,
install_tag:,
link_args:,
link_depends:,
link_language:,
link_whole:,
link_with:,
name_prefix:,
name_suffix:,
native: false,
objects:,
override_options:,
pie:,
rust_crate_type:,
rust_dependency_map:,
sources:,
vala_args:,
vs_module_defs:,
win_subsystem: 'console',
)

DESCRIPTION
Creates a new executable. The first argument specifies its name and the remaining positional
arguments define the input files to use.

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`.