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