<commit_before># Reference manual

## Functions

The following functions are available in build files. Click on each to
see the description and usage. The objects returned by them are [list
afterwards](#returned-objects).


### add_global_arguments()

``` meson
  void add_global_arguments(arg1, arg2, ...)
```

Adds the positional arguments to the compiler command line. This
function has two keyword arguments:

- `language` 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` is 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. Available since 0.48.0

The arguments are used in all compiler invocations with the exception
of compile tests, because you might need to run a compile test with
and without the argument in question. For this reason only the
arguments explicitly specified are used during compile tests.

**Note:** Usually you should use `add_project_arguments` instead,
  because that works even when you project is used as a subproject.

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

### add_global_link_arguments()

``` meson
    void add_global_link_arguments(*arg1*, *arg2*, ...)
```

Like `add_global_arguments` but the arguments are passed to the linker.

### add_languages()

``` meson
  bool add_languages(*langs*)
```

Add support for new programming languages. Equivalent to having them
in the `project` declaration. This function is usually used to add
languages that are only used on some platforms like this:

```meson
project('foobar', 'c')
if compiling_for_osx
  add_languages('objc')
endif
if add_languages('cpp', required : false)
  executable('cpp-app', 'main.cpp')
endif
```

Takes one keyword argument, `required`. It defaults to `true`, which
means that if any of the languages specified is not found, Meson will
halt. Returns true if all languages specified were found and false
otherwise. Since *0.47.0* the value of a
[`feature`](Build-options.md#features) option can also be passed to
the `required` keyword argument.

### add_project_arguments()

``` meson
  void add_project_arguments(arg1, arg2, ...)
```

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.

### add_project_link_arguments()

``` meson
  void add_project_link_arguments(*arg1*, *arg2*, ...)
```

Like `add_project_arguments` but the arguments are passed to the linker.

### add_test_setup()

``` meson
  void add_test_setup(*name*, ...)
```

Add a custom test setup that can be used to run the tests with a
custom setup, for example under Valgrind. The keyword arguments are
the following:

- `env` an [environment object](#environment-object) to use a custom environment
- `exe_wrapper` a list containing the wrapper command or script followed by the arguments to it
- `gdb` if `true`, the tests are also run under `gdb`
- `timeout_multiplier` a number to multiply the test timeout with
- `is_default` a bool to set whether this is the default test setup.
  If `true`, the setup will be used whenever `meson test` is run
  without the `--setup` option. Since 0.49.0

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

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

### alias_target

``` meson
runtarget alias_target(target_name, dep1, ...)
```

Since *0.52.0*

This function creates a new top-level target. Like all top-level targets, this
integrates with the selected backend. For instance, with Ninja you can
run it as `ninja 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 (e.g. return value of [executable()](#executable), custom_target(), etc)

### assert()

``` meson
    void assert(*condition*, *message*)
```

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

### benchmark()

``` meson
    void benchmark(name, executable, ...)
```

Creates a benchmark item that will be run when the benchmark target is
run. The behavior of this function is identical to `test` with the
exception that there is no `is_parallel` keyword, because benchmarks
are never run in parallel.

### both_libraries()

``` meson
    buildtarget = both_libraries(library_name, list_of_sources, ...)
```

Builds both a static and shared library with the given
sources. Positional and keyword arguments are otherwise the same as
for [`library`](#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.

The returned [buildtarget](#build-target-object) always represents the
shared library. In addition it supports the following extra methods:

- `get_shared_lib()` returns the shared library build target
- `get_static_lib()` returns the static library build target

*Added 0.46.0*

### build_target()

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`
- `shared_library`
- `shared_module`
- `static_library`
- `both_libraries`
- `library`
- `jar`

This declaration:

```meson
executable(<arguments and keyword arguments>)
```

is equivalent to this:

```meson
build_target(<arguments and keyword arguments>, target_type : 'executable')
```

The object returned by `build_target` and all convenience wrappers for
`build_target` such as [`executable`](#executable) and
[`library`](#library) has methods that are documented in the [object
methods section](#build-target-object) below.

### configuration_data()

``` meson
    configuration_data_object = configuration_data(...)
```

Creates an empty configuration object. You should add your
configuration with [its method calls](#configuration-data-object) and
finally use it in a call to `configure_file`.

Since *0.49.0* takes an optional dictionary as first argument. If
provided, each key/value pair is added into the `configuration_data`
as if `set()` method was called for each of them.

### configure_file()

``` meson
    generated_file = configure_file(...)
```

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

When a [`configuration_data()`](#configuration_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](Configuration.md). Since *0.49.0* a
dictionary can be passed instead of a
[`configuration_data()`](#configuration_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.

These are all the supported keyword arguments:

- `capture` when this argument is set to true, Meson captures `stdout`
  of the `command` and writes it to the target file specified as
  `output`. Available since v0.41.0.
- `command` 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()`](#custom_target) for details about string
  substitutions.
- `copy` *(added 0.47.0)* as explained above, if specified Meson only
  copies the file from input to output.
- `format` *(added 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` 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` *(added 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` 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` *(added 0.47.0)* specify the file mode in symbolic format
  and optionally the owner/uid and group/gid for the installed files.
- `output` the output file name (since v0.41.0, may contain
  `@PLAINNAME@` or `@BASENAME@` substitutions). In configuration mode,
  the permissions of the input file (if it is specified) are copied to
  the output file.
- `output_format` *(added 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 `%`.
- `encoding` *(added v0.47.0)* set the file encoding for the input and output file,
  defaults to utf-8. The supported encodings are those of python3, see
  [standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings).

### custom_target()

``` meson
    customtarget custom_target(*name*, ...)
```

Create a custom top level build target. The only positional argument
is the name of this target and the keyword arguments are the
following.

- `build_by_default` *(added 0.38)* causes, when set to true, to
  have this target be built by default, that is, when invoking plain
  `ninja`; the default value is false
  *(changed in 0.50)* 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.
- `build_always` (deprecated) 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` *(added 0.47)* 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.
- `capture`, 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.
- `console` *(added 0.48)* 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](https://ninja-build.org/manual.html#_the_literal_console_literal_pool),
  which has special properties such as not buffering stdout and
  serializing all targets in this pool.
- `command` 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()`](#find_program),
  [`executable()`](#executable), [`configure_file()`](#configure_file),
  [`files()`](#files), [`custom_target()`](#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.
- `depend_files` files ([`string`](#string-object),
  [`files()`](#files), or [`configure_file()`](#configure_file)) that
  this target depends on but are not listed in the `command` keyword
  argument. Useful for adding regen dependencies.
- `depends` 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.
- `depfile` is 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
- `input` list of source files. As of 0.41.0 the list will be flattened.
- `install` when true, this target is installed during the install step
- `install_dir` directory to install to
- `install_mode` *(added 0.47.0)* the file mode and optionally the
  owner/uid and group/gid
- `output` list of output files

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

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

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

The returned object also has methods that are documented in the
[object methods section](#custom-target-object) below.

### declare_dependency()

``` meson
    dependency_object declare_dependency(...)
```

This function returns a [dependency object](#dependency-object) that
behaves like the return value of [`dependency`](#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. This function has the following
keyword arguments.

  - `compile_args`, compile arguments to use
  - `dependencies`, other dependencies needed to use this dependency
  - `include_directories`, the directories to add to header search path,
    must be include_directories objects or, since 0.50.0, plain strings
  - `link_args`, link arguments to use
  - `link_with`, libraries to link against
  - `link_whole`, libraries to link fully, same as [`executable`](#executable)
    Since 0.46.0
  - `sources`, sources to add to targets (or generated header files
    that should be built before sources including them are built)
  - `version`, the version of this dependency, such as `1.2.3`

### dependency()

``` meson
    dependency_object dependency(*dependency_name*, ...)
```

Finds an external dependency (usually a library installed on your
system) with the given name with `pkg-config` and [with
CMake](Dependencies.md#CMake) if `pkg-config` fails. Additionally,
frameworks (OSX only) and [library-specific fallback detection
logic](Dependencies.md#dependencies-with-custom-lookup-functionality)
are also supported. This function supports the following keyword
arguments:

- `default_options` *(added 0.37.0)* an array of default option values
  that override those set in the subproject's `meson_options.txt`
  (like `default_options` in [`project()`](#project), they only have
  effect when Meson is run for the first time, and command line
  arguments override any default options in build files)
- `fallback` specifies a subproject fallback to use in case the
  dependency is not found in the system. The value is an array
  `['subproj_name', 'subproj_dep']` where 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`](#declare_dependency) or
  [`dependency()`](#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.
- `language` *(added 0.42.0)* defines what language-specific
  dependency to find if it's available for multiple languages.
- `method` 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](
  Dependencies.md#dependencies-with-custom-lookup-functionality)
  for this (though `auto` will work on all of them)
- `native` 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` *(added 0.50.0)* is an optional string that will
  be printed as a `message()` if the dependency was not found.
- `required`, when set to false, Meson will proceed with the build
  even if the dependency is not found. Since *0.47.0* the value of a
  [`feature`](Build-options.md#features) option can also be passed.
- `static` tells the dependency provider to try to get static
  libraries instead of dynamic ones (note that this is not supported
  by all dependency backends)
- `version` 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. *(Added 0.37.0)*
  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.
- other
[library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality)
keywords may also be accepted (e.g. `modules` specifies submodules to use for
dependencies such as Qt5 or Boost. )
- `disabler` if `true` and the dependency couldn't be found, return a
  [disabler object](#disabler-object) instead of a not-found dependency.
  *Since 0.49.0*

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 also has methods that are documented in the
[object methods section](#dependency-object) below.

### disabler()

Returns a [disabler object](#disabler-object). Added in 0.44.0.

### error()

``` meson
    void error(message)
```

Print the argument string and halts the build process.

### environment()

``` meson
    environment_object environment()
```

Returns an empty [environment variable
object](#environment-object). Added in 0.35.0.

### executable()

``` meson
    buildtarget executable(*exe_name*, *sources*, ...)
```

Creates a new executable. The first argument specifies its name and
the remaining positional arguments define the input files to use. They
can be of the following types:

- Strings relative to the current source directory
- [`files()`](#files) objects defined in any preceding build file
- The return value of configure-time generators such as [`configure_file()`](#configure_file)
- The return value of build-time generators such as
  [`custom_target()`](#custom_target) or
  [`generator.process()`](#generator-object)

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](https://ninja-build.org/manual.html#ref_dependencies) on
all generated input files, including unknown files. For all input
files (generated and non-generated), Meson uses the [dependency
file](https://ninja-build.org/manual.html#ref_headers) generated by
your compiler to determine when to rebuild sources. The behavior is
similar for other backends.

Executable supports the following keyword arguments. Note that just
like the positional arguments above, these keyword arguments can also
be passed to [shared and static libraries](#library).

- `<languagename>_pch` precompiled header file to use for the given language
- `<languagename>_args` compiler flags to use for the given language;
  eg: `cpp_args` for C++
- `build_by_default` causes, when set to true, to have this target be
  built by default, that is, when invoking plain `ninja`, the default
  value is true for all built target types, since 0.38.0
- `build_rpath` a string to add to target's rpath definition in the
  build dir, but which will be removed on install
- `dependencies` one or more objects created with
  [`dependency`](#dependency) or [`find_library`](#compiler-object)
  (for external deps) or [`declare_dependency`](#declare_dependency)
  (for deps built by the project)
- `extra_files` are not used for the build itself but are shown as
  source files in IDEs that group files by targets (such as Visual
  Studio)
- `gui_app` when set to true flags this target as a GUI application on
  platforms where this makes a difference (e.g. Windows)
- `link_args` flags to use during linking. You can use UNIX-style
  flags here for all platforms.
- `link_depends` 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` since 0.51.0 makes the linker for this target
  be for the specified language. This is helpful for multi-language targets.
- `link_whole` links all contents of the given static libraries
  whether they are used by not, equivalent to the
  `-Wl,--whole-archive` argument flag of GCC, available since 0.40.0.
  As of 0.41.0 if passed a list that list will be flattened. Starting
  from version 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`, one or more shared or static libraries (built by this
  project) that this target should be linked with, If passed a list
  this list will be flattened as of 0.41.0. Starting with version
  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.
- `export_dynamic` when set to true causes the target's symbols to be
  dynamically exported, allowing modules built using the
  [`shared_module`](#shared_module) function to refer to functions,
  variables and other symbols defined in the executable itself. Implies
  the `implib` argument.  Since 0.45.0
- `implib` 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.  Since 0.42.0
- `implicit_include_directories` is a boolean telling whether Meson
  adds the current source and build directories to the include path,
  defaults to `true`, since 0.42.0
- `include_directories` 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`, when set to true, this executable should be installed, defaults to `false`
- `install_dir` override install directory for this file. The value is
  relative to the `prefix` specified. F.ex, 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` *(added 0.47.0)* specify the file mode in symbolic format
  and optionally the owner/uid and group/gid for the installed files.
- `install_rpath` a string to set the target's rpath to after install
  (but *not* before that)
- `objects` list of prebuilt object files (usually for third party
  products you don't have source to) that should be linked in this
  target, **never** use this for object files that you build yourself.
- `name_suffix` the string that will be used as the extension for the
  target by overriding the default. By default on Windows this is
  `exe` and on other platforms it is omitted. Set this to `[]`, or omit
  the keyword argument for the default behaviour.
- `override_options` 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 0.40.0.
- `gnu_symbol_visibility` specifies how symbols should be exported, see
  e.g [the GCC Wiki](https://gcc.gnu.org/wiki/Visibility) 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. Available since 0.48.0.
- `d_import_dirs` list of directories to look in for string imports used
  in the D programming language
- `d_unittest`, when set to true, the D modules are compiled in debug mode
- `d_module_versions` list of module version identifiers set when compiling D sources
- `d_debug` list of module debug identifiers set when compiling D sources
- `pie` *(added 0.49.0)* build a position-independent executable
- `native`, is a boolean controlling whether the target is compiled for the
  build or host machines. Defaults to false, building for the host machine.

The list of `sources`, `objects`, and `dependencies` is always
flattened, which means you can freely nest and add lists while
creating the final list.
<commit_msg>Add Windows behavior to executable()'s install_rpath arg doc [skip ci]<commit_after># Reference manual

## Functions

The following functions are available in build files. Click on each to
see the description and usage. The objects returned by them are [list
afterwards](#returned-objects).


### add_global_arguments()

``` meson
  void add_global_arguments(arg1, arg2, ...)
```

Adds the positional arguments to the compiler command line. This
function has two keyword arguments:

- `language` 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` is 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. Available since 0.48.0

The arguments are used in all compiler invocations with the exception
of compile tests, because you might need to run a compile test with
and without the argument in question. For this reason only the
arguments explicitly specified are used during compile tests.

**Note:** Usually you should use `add_project_arguments` instead,
  because that works even when you project is used as a subproject.

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

### add_global_link_arguments()

``` meson
    void add_global_link_arguments(*arg1*, *arg2*, ...)
```

Like `add_global_arguments` but the arguments are passed to the linker.

### add_languages()

``` meson
  bool add_languages(*langs*)
```

Add support for new programming languages. Equivalent to having them
in the `project` declaration. This function is usually used to add
languages that are only used on some platforms like this:

```meson
project('foobar', 'c')
if compiling_for_osx
  add_languages('objc')
endif
if add_languages('cpp', required : false)
  executable('cpp-app', 'main.cpp')
endif
```

Takes one keyword argument, `required`. It defaults to `true`, which
means that if any of the languages specified is not found, Meson will
halt. Returns true if all languages specified were found and false
otherwise. Since *0.47.0* the value of a
[`feature`](Build-options.md#features) option can also be passed to
the `required` keyword argument.

### add_project_arguments()

``` meson
  void add_project_arguments(arg1, arg2, ...)
```

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.

### add_project_link_arguments()

``` meson
  void add_project_link_arguments(*arg1*, *arg2*, ...)
```

Like `add_project_arguments` but the arguments are passed to the linker.

### add_test_setup()

``` meson
  void add_test_setup(*name*, ...)
```

Add a custom test setup that can be used to run the tests with a
custom setup, for example under Valgrind. The keyword arguments are
the following:

- `env` an [environment object](#environment-object) to use a custom environment
- `exe_wrapper` a list containing the wrapper command or script followed by the arguments to it
- `gdb` if `true`, the tests are also run under `gdb`
- `timeout_multiplier` a number to multiply the test timeout with
- `is_default` a bool to set whether this is the default test setup.
  If `true`, the setup will be used whenever `meson test` is run
  without the `--setup` option. Since 0.49.0

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

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

### alias_target

``` meson
runtarget alias_target(target_name, dep1, ...)
```

Since *0.52.0*

This function creates a new top-level target. Like all top-level targets, this
integrates with the selected backend. For instance, with Ninja you can
run it as `ninja 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 (e.g. return value of [executable()](#executable), custom_target(), etc)

### assert()

``` meson
    void assert(*condition*, *message*)
```

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

### benchmark()

``` meson
    void benchmark(name, executable, ...)
```

Creates a benchmark item that will be run when the benchmark target is
run. The behavior of this function is identical to `test` with the
exception that there is no `is_parallel` keyword, because benchmarks
are never run in parallel.

### both_libraries()

``` meson
    buildtarget = both_libraries(library_name, list_of_sources, ...)
```

Builds both a static and shared library with the given
sources. Positional and keyword arguments are otherwise the same as
for [`library`](#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.

The returned [buildtarget](#build-target-object) always represents the
shared library. In addition it supports the following extra methods:

- `get_shared_lib()` returns the shared library build target
- `get_static_lib()` returns the static library build target

*Added 0.46.0*

### build_target()

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`
- `shared_library`
- `shared_module`
- `static_library`
- `both_libraries`
- `library`
- `jar`

This declaration:

```meson
executable(<arguments and keyword arguments>)
```

is equivalent to this:

```meson
build_target(<arguments and keyword arguments>, target_type : 'executable')
```

The object returned by `build_target` and all convenience wrappers for
`build_target` such as [`executable`](#executable) and
[`library`](#library) has methods that are documented in the [object
methods section](#build-target-object) below.

### configuration_data()

``` meson
    configuration_data_object = configuration_data(...)
```

Creates an empty configuration object. You should add your
configuration with [its method calls](#configuration-data-object) and
finally use it in a call to `configure_file`.

Since *0.49.0* takes an optional dictionary as first argument. If
provided, each key/value pair is added into the `configuration_data`
as if `set()` method was called for each of them.

### configure_file()

``` meson
    generated_file = configure_file(...)
```

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

When a [`configuration_data()`](#configuration_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](Configuration.md). Since *0.49.0* a
dictionary can be passed instead of a
[`configuration_data()`](#configuration_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.

These are all the supported keyword arguments:

- `capture` when this argument is set to true, Meson captures `stdout`
  of the `command` and writes it to the target file specified as
  `output`. Available since v0.41.0.
- `command` 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()`](#custom_target) for details about string
  substitutions.
- `copy` *(added 0.47.0)* as explained above, if specified Meson only
  copies the file from input to output.
- `format` *(added 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` 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` *(added 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` 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` *(added 0.47.0)* specify the file mode in symbolic format
  and optionally the owner/uid and group/gid for the installed files.
- `output` the output file name (since v0.41.0, may contain
  `@PLAINNAME@` or `@BASENAME@` substitutions). In configuration mode,
  the permissions of the input file (if it is specified) are copied to
  the output file.
- `output_format` *(added 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 `%`.
- `encoding` *(added v0.47.0)* set the file encoding for the input and output file,
  defaults to utf-8. The supported encodings are those of python3, see
  [standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings).

### custom_target()

``` meson
    customtarget custom_target(*name*, ...)
```

Create a custom top level build target. The only positional argument
is the name of this target and the keyword arguments are the
following.

- `build_by_default` *(added 0.38)* causes, when set to true, to
  have this target be built by default, that is, when invoking plain
  `ninja`; the default value is false
  *(changed in 0.50)* 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.
- `build_always` (deprecated) 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` *(added 0.47)* 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.
- `capture`, 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.
- `console` *(added 0.48)* 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](https://ninja-build.org/manual.html#_the_literal_console_literal_pool),
  which has special properties such as not buffering stdout and
  serializing all targets in this pool.
- `command` 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()`](#find_program),
  [`executable()`](#executable), [`configure_file()`](#configure_file),
  [`files()`](#files), [`custom_target()`](#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.
- `depend_files` files ([`string`](#string-object),
  [`files()`](#files), or [`configure_file()`](#configure_file)) that
  this target depends on but are not listed in the `command` keyword
  argument. Useful for adding regen dependencies.
- `depends` 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.
- `depfile` is 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
- `input` list of source files. As of 0.41.0 the list will be flattened.
- `install` when true, this target is installed during the install step
- `install_dir` directory to install to
- `install_mode` *(added 0.47.0)* the file mode and optionally the
  owner/uid and group/gid
- `output` list of output files

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

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

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

The returned object also has methods that are documented in the
[object methods section](#custom-target-object) below.

### declare_dependency()

``` meson
    dependency_object declare_dependency(...)
```

This function returns a [dependency object](#dependency-object) that
behaves like the return value of [`dependency`](#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. This function has the following
keyword arguments.

  - `compile_args`, compile arguments to use
  - `dependencies`, other dependencies needed to use this dependency
  - `include_directories`, the directories to add to header search path,
    must be include_directories objects or, since 0.50.0, plain strings
  - `link_args`, link arguments to use
  - `link_with`, libraries to link against
  - `link_whole`, libraries to link fully, same as [`executable`](#executable)
    Since 0.46.0
  - `sources`, sources to add to targets (or generated header files
    that should be built before sources including them are built)
  - `version`, the version of this dependency, such as `1.2.3`

### dependency()

``` meson
    dependency_object dependency(*dependency_name*, ...)
```

Finds an external dependency (usually a library installed on your
system) with the given name with `pkg-config` and [with
CMake](Dependencies.md#CMake) if `pkg-config` fails. Additionally,
frameworks (OSX only) and [library-specific fallback detection
logic](Dependencies.md#dependencies-with-custom-lookup-functionality)
are also supported. This function supports the following keyword
arguments:

- `default_options` *(added 0.37.0)* an array of default option values
  that override those set in the subproject's `meson_options.txt`
  (like `default_options` in [`project()`](#project), they only have
  effect when Meson is run for the first time, and command line
  arguments override any default options in build files)
- `fallback` specifies a subproject fallback to use in case the
  dependency is not found in the system. The value is an array
  `['subproj_name', 'subproj_dep']` where 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`](#declare_dependency) or
  [`dependency()`](#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.
- `language` *(added 0.42.0)* defines what language-specific
  dependency to find if it's available for multiple languages.
- `method` 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](
  Dependencies.md#dependencies-with-custom-lookup-functionality)
  for this (though `auto` will work on all of them)
- `native` 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` *(added 0.50.0)* is an optional string that will
  be printed as a `message()` if the dependency was not found.
- `required`, when set to false, Meson will proceed with the build
  even if the dependency is not found. Since *0.47.0* the value of a
  [`feature`](Build-options.md#features) option can also be passed.
- `static` tells the dependency provider to try to get static
  libraries instead of dynamic ones (note that this is not supported
  by all dependency backends)
- `version` 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. *(Added 0.37.0)*
  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.
- other
[library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality)
keywords may also be accepted (e.g. `modules` specifies submodules to use for
dependencies such as Qt5 or Boost. )
- `disabler` if `true` and the dependency couldn't be found, return a
  [disabler object](#disabler-object) instead of a not-found dependency.
  *Since 0.49.0*

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 also has methods that are documented in the
[object methods section](#dependency-object) below.

### disabler()

Returns a [disabler object](#disabler-object). Added in 0.44.0.

### error()

``` meson
    void error(message)
```

Print the argument string and halts the build process.

### environment()

``` meson
    environment_object environment()
```

Returns an empty [environment variable
object](#environment-object). Added in 0.35.0.

### executable()

``` meson
    buildtarget executable(*exe_name*, *sources*, ...)
```

Creates a new executable. The first argument specifies its name and
the remaining positional arguments define the input files to use. They
can be of the following types:

- Strings relative to the current source directory
- [`files()`](#files) objects defined in any preceding build file
- The return value of configure-time generators such as [`configure_file()`](#configure_file)
- The return value of build-time generators such as
  [`custom_target()`](#custom_target) or
  [`generator.process()`](#generator-object)

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](https://ninja-build.org/manual.html#ref_dependencies) on
all generated input files, including unknown files. For all input
files (generated and non-generated), Meson uses the [dependency
file](https://ninja-build.org/manual.html#ref_headers) generated by
your compiler to determine when to rebuild sources. The behavior is
similar for other backends.

Executable supports the following keyword arguments. Note that just
like the positional arguments above, these keyword arguments can also
be passed to [shared and static libraries](#library).

- `<languagename>_pch` precompiled header file to use for the given language
- `<languagename>_args` compiler flags to use for the given language;
  eg: `cpp_args` for C++
- `build_by_default` causes, when set to true, to have this target be
  built by default, that is, when invoking plain `ninja`, the default
  value is true for all built target types, since 0.38.0
- `build_rpath` a string to add to target's rpath definition in the
  build dir, but which will be removed on install
- `dependencies` one or more objects created with
  [`dependency`](#dependency) or [`find_library`](#compiler-object)
  (for external deps) or [`declare_dependency`](#declare_dependency)
  (for deps built by the project)
- `extra_files` are not used for the build itself but are shown as
  source files in IDEs that group files by targets (such as Visual
  Studio)
- `gui_app` when set to true flags this target as a GUI application on
  platforms where this makes a difference (e.g. Windows)
- `link_args` flags to use during linking. You can use UNIX-style
  flags here for all platforms.
- `link_depends` 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` since 0.51.0 makes the linker for this target
  be for the specified language. This is helpful for multi-language targets.
- `link_whole` links all contents of the given static libraries
  whether they are used by not, equivalent to the
  `-Wl,--whole-archive` argument flag of GCC, available since 0.40.0.
  As of 0.41.0 if passed a list that list will be flattened. Starting
  from version 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`, one or more shared or static libraries (built by this
  project) that this target should be linked with, If passed a list
  this list will be flattened as of 0.41.0. Starting with version
  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.
- `export_dynamic` when set to true causes the target's symbols to be
  dynamically exported, allowing modules built using the
  [`shared_module`](#shared_module) function to refer to functions,
  variables and other symbols defined in the executable itself. Implies
  the `implib` argument.  Since 0.45.0
- `implib` 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.  Since 0.42.0
- `implicit_include_directories` is a boolean telling whether Meson
  adds the current source and build directories to the include path,
  defaults to `true`, since 0.42.0
- `include_directories` 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`, when set to true, this executable should be installed, defaults to `false`
- `install_dir` override install directory for this file. The value is
  relative to the `prefix` specified. F.ex, 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` *(added 0.47.0)* specify the file mode in symbolic format
  and optionally the owner/uid and group/gid for the installed files.
- `install_rpath` a string to set the target's rpath to after install
  (but *not* before that). On Windows, this argument has no effect.
- `objects` list of prebuilt object files (usually for third party
  products you don't have source to) that should be linked in this
  target, **never** use this for object files that you build yourself.
- `name_suffix` the string that will be used as the extension for the
  target by overriding the default. By default on Windows this is
  `exe` and on other platforms it is omitted. Set this to `[]`, or omit
  the keyword argument for the default behaviour.
- `override_options` 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 0.40.0.
- `gnu_symbol_visibility` specifies how symbols should be exported, see
  e.g [the GCC Wiki](https://gcc.gnu.org/wiki/Visibility) 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. Available since 0.48.0.
- `d_import_dirs` list of directories to look in for string imports used
  in the D programming language
- `d_unittest`, when set to true, the D modules are compiled in debug mode
- `d_module_versions` list of module version identifiers set when compiling D sources
- `d_debug` list of module debug identifiers set when compiling D sources
- `pie` *(added 0.49.0)* build a position-independent executable
- `native`, is a boolean controlling whether the target is compiled for the
  build or host machines. Defaults to false, building for the host machine.

The list of `sources`, `objects`, and `dependencies` is always
flattened, which means you can freely nest and add lists while
creating the final list.

{'fraction_non_alphanumeric': 0.0830929024812464, 'fraction_numerical': 0.008428194233156727, 'mean_word_length': 4.423423423423423, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5504640', 'n_tokens_mistral': 15967, 'n_tokens_neox': 15131, 'n_words': 7872}