Functions

This document lists all functions available in meson.build files. See the root manual document for an overview of all features.

add_global_arguments()

Adds global arguments to the compiler command line.

# Adds global arguments to the compiler command line
void add_global_arguments(
  str Compiler argument...,  # The compiler arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

Arguments

The function accepts between 0 and infinity variadic arguments (Compiler argument...) of type str.

The compiler arguments to add

The function add_global_arguments() accepts the following keyword arguments:

add_global_link_arguments()

Adds global arguments to the linker command line.

Like add_global_arguments() but the arguments are passed to the linker.

# Adds global arguments to the linker command line
void add_global_link_arguments(
  str Linker argument...,  # The linker arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

Arguments

The function accepts between 0 and infinity variadic arguments (Linker argument...) of type str.

The linker arguments to add

The function add_global_link_arguments() accepts the following keyword arguments:

add_languages()

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.

# Add programming languages used by the project
bool add_languages(
  str Language...,  # The languages to add

  # Keyword arguments:
  native   : bool            # If set to `true`, the language will be used to compile for the build
  required : bool | feature  # If set to `true`, Meson will halt if any of the languages
)

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

Arguments

The function accepts between 0 and infinity variadic arguments (Language...) of type str.

The languages to add

The function add_languages() accepts the following keyword arguments:

add_project_arguments()

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.

# Adds project specific arguments to the compiler command line
void add_project_arguments(
  str Compiler argument...,  # The compiler arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

Arguments

The function accepts between 0 and infinity variadic arguments (Compiler argument...) of type str.

The compiler arguments to add

The function add_project_arguments() accepts the following keyword arguments:

add_project_dependencies()

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.

# Adds arguments to the compiler and linker command line, so that the
void add_project_dependencies(
  dep dependencies...,  # The dependencies to add; if internal dependencies are included, they must not include any built object

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

Arguments

The function accepts between 0 and infinity variadic arguments (dependencies...) of type dep.

The dependencies to add; if internal dependencies are included, they must not include any built object.

The function add_project_dependencies() accepts the following keyword arguments:

add_project_link_arguments()

Adds project specific arguments to the linker command line.

Like add_project_arguments() but the arguments are passed to the linker.

# Adds project specific arguments to the linker command line
void add_project_link_arguments(
  str Linker argument...,  # The linker arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

Arguments

The function accepts between 0 and infinity variadic arguments (Linker argument...) of type str.

The linker arguments to add

The function add_project_link_arguments() accepts the following keyword arguments:

add_test_setup()

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.

# Add a custom test setup
void add_test_setup(
  str name,     # The name of the test setup

  # Keyword arguments:
  env                : env | list[str] | dict[str]   # environment variables to set
  exclude_suites     : list[str]                     # A list of test suites that should be excluded when using this setup
  exe_wrapper        : list[str | external_program]  # The command or script followed by the arguments to it
  gdb                : bool                          # If `true`, the tests are also run under `gdb`
  is_default         : bool                          # Set whether this is the default test setup
  timeout_multiplier : int                           # A number to multiply the test timeout with
)

Arguments

The function add_test_setup() accepts the following positional arguments:

Finally, add_test_setup() accepts the following keyword arguments:

alias_target()

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.

Since 1.6.0 passing a both_libs object builds both shared and static libraries.

# This function creates a new top-level target
alias_tgt alias_target(
  str target_name,     # The name of the alias target
  tgt Dep...,          # The targets to depend on
)

Arguments

The function alias_target() accepts the following positional arguments:

Additionally, the function accepts between 1 and infinity variadic arguments (Dep...) of type tgt.

The targets to depend on

assert()

Abort with an error message if condition evaluates to false.

# Abort with an error message if `condition` evaluates to `false`
void assert(
  bool condition,     # Abort if this evaluates to `false`
  str  [message],     # The error message to print
)

Arguments

The function assert() accepts the following positional arguments:

benchmark()

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.

# Creates a benchmark item that will be run when the benchmark target is
void benchmark(
  str                                                           name,           # The *unique* test id
  exe | jar | external_program | file | custom_tgt | custom_idx executable,     # The program to execute

  # Keyword arguments:
  args        : list[str | file | tgt | external_program]  # Arguments to pass to the executable
  depends     : list[build_tgt | custom_tgt]               # specifies that this test depends on the specified
  env         : env | list[str] | dict[str]                # environment variables to set, such as `['NAME1=value1',
  priority    : int                                        # specifies the priority of a test
  protocol    : str                                        # specifies how the test results are parsed and can
  should_fail : bool                                       # when true the test is considered passed if the
  suite       : str | list[str]                            # `'label'` (or list of labels `['label1', 'label2']`)
  timeout     : int                                        # the amount of seconds the test is allowed to run, a test
  verbose     : bool                                       # if true, forces the test results to be logged as if `--verbose` was passed
  workdir     : str                                        # absolute path that will be used as the working directory
)

Arguments

The function benchmark() accepts the following positional arguments:

Finally, benchmark() accepts the following keyword arguments:

both_libraries()

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.

# Builds both a static and shared library with the given sources
both_libs both_libraries(
  str                                                   target_name,     # The *unique* name of the build target
  str | file | custom_tgt | custom_idx | generated_list source...,       # Input source to compile

  # Keyword arguments:
  <lang>_args                  : list[str]                                                               # compiler flags to use for the given language;
  <lang>_pch                   : str                                                                     # precompiled header file to use for the given language
  <lang>_shared_args           : list[str]                                                               # Arguments that are only passed to a shared library
  <lang>_static_args           : list[str]                                                               # Arguments that are only passed to a static library
  build_by_default             : bool                                                                    # Causes, when set to `true`, to have this target be built by default
  build_rpath                  : str                                                                     # A string to add to target's rpath definition in the build dir,
  d_debug                      : list[str]                                                               # The [D version identifiers](https://dlang
  d_import_dirs                : list[inc | str]                                                         # the directories to add to the string search path (i
  d_module_versions            : list[str | int]                                                         # List of module version identifiers set when compiling D sources
  d_unittest                   : bool                                                                    # When set to true, the D modules are compiled in debug mode
  darwin_versions              : str | int | list[str]                                                   # Defines the `compatibility version` and `current version` for the dylib on macOS
  dependencies                 : list[dep]                                                               # one or more dependency objects
  extra_files                  : str | file | custom_tgt | custom_idx                                    # Not used for the build itself but are shown as source files in IDEs
  gnu_symbol_visibility        : str                                                                     # Specifies how symbols should be exported, see
  gui_app                      : bool                                                                    # When set to true flags this target as a GUI application
  implicit_include_directories : bool                                                                    # 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,
  install                      : bool                                                                    # When set to true, this executable should be installed
  install_dir                  : str                                                                     # override install directory for this file
  install_mode                 : list[str | int]                                                         # Specify the file mode in symbolic format
  install_rpath                : str                                                                     # A string to set the target's rpath to after install
  install_tag                  : str                                                                     # A string used by the `meson install --tags` command
  link_args                    : list[str]                                                               # Flags to use during linking
  link_depends                 : str | file | custom_tgt | custom_idx                                    # Strings, files, or custom targets the link step depends on
  link_language                : str                                                                     # Makes the linker for this target be for the specified language
  link_whole                   : list[lib | custom_tgt | custom_idx]                                     # Links all contents of the given static libraries whether they are used or
  link_with                    : list[lib | custom_tgt | custom_idx]                                     # One or more shared or static libraries
  name_prefix                  : str | list[void]                                                        # The string that will be used as the prefix for the
  name_suffix                  : str | list[void]                                                        # The string that will be used as the extension for the
  native                       : bool                                                                    # 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
  override_options             : list[str] | dict[str | bool | int | list[str]]                            # takes an array of strings in the same format as `project`'s `default_options`
  pic                          : bool                                                                    # Builds the library as positional independent code
  prelink                      : bool                                                                    # If `true` the object files in the target will be prelinked,
  rust_abi                     : str                                                                     # Set the specific ABI to compile (when compiling rust)
  rust_crate_type              : str                                                                     # Set the specific type of rust crate to compile (when compiling rust)
  rust_dependency_map          : dict[str]                                                               # On rust targets this provides a map of library names to the crate name
  sources                      : str | file | custom_tgt | custom_idx | generated_list | structured_src  # Additional source files
  soversion                    : str | int                                                               # A string or integer specifying the soversion of this shared library,
  vala_args                    : list[str | file]                                                        # Compiler flags for Vala
  vala_shared_args             : list[str | file]                                                        # Arguments that are only passed to a shared library
  vala_static_args             : list[str | file]                                                        # Arguments that are only passed to a static library
  version                      : str                                                                     # A string specifying the version of this shared library,
  vs_module_defs               : str | file | custom_tgt | custom_idx                                    # Specify a Microsoft module definition file for controlling symbol exports,
  win_subsystem                : str                                                                     # Specifies the subsystem type to use
)

Arguments

The function both_libraries() accepts the following positional arguments:

Additionally, the function accepts between 0 and infinity variadic arguments (source...) of type str | file | custom_tgt | custom_idx | generated_list.

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 on all generated input files, including unknown files. This is needed to bootstrap the generation of the real dependencies in the depfile 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.

Finally, both_libraries() accepts the following keyword arguments:

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 (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 fundamentally a different thing than the other build_target types.

# Creates a build target whose type can be set dynamically with the
build_tgt build_target(
  str                                                   target_name,     # The *unique* name of the build target
  str | file | custom_tgt | custom_idx | generated_list source...,       # Input source to compile

  # Keyword arguments:
  <lang>_args                  : list[str]                                                               # compiler flags to use for the given language;
  <lang>_pch                   : str                                                                     # precompiled header file to use for the given language
  <lang>_shared_args           : list[str]                                                               # Arguments that are only passed to a shared library
  <lang>_static_args           : list[str]                                                               # Arguments that are only passed to a static library
  build_by_default             : bool                                                                    # Causes, when set to `true`, to have this target be built by default
  build_rpath                  : str                                                                     # A string to add to target's rpath definition in the build dir,
  d_debug                      : list[str]                                                               # The [D version identifiers](https://dlang
  d_import_dirs                : list[inc | str]                                                         # the directories to add to the string search path (i
  d_module_versions            : list[str | int]                                                         # List of module version identifiers set when compiling D sources
  d_unittest                   : bool                                                                    # When set to true, the D modules are compiled in debug mode
  darwin_versions              : str | int | list[str]                                                   # Defines the `compatibility version` and `current version` for the dylib on macOS
  dependencies                 : list[dep]                                                               # one or more dependency objects
  export_dynamic               : bool                                                                    # when set to true causes the target's symbols to be
  extra_files                  : str | file | custom_tgt | custom_idx                                    # Not used for the build itself but are shown as source files in IDEs
  gnu_symbol_visibility        : str                                                                     # Specifies how symbols should be exported, see
  gui_app                      : bool                                                                    # When set to true flags this target as a GUI application
  implib                       : bool | str                                                              # When set to true, an import library is generated for the
  implicit_include_directories : bool                                                                    # 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,
  install                      : bool                                                                    # When set to true, this executable should be installed
  install_dir                  : str                                                                     # override install directory for this file
  install_mode                 : list[str | int]                                                         # Specify the file mode in symbolic format
  install_rpath                : str                                                                     # A string to set the target's rpath to after install
  install_tag                  : str                                                                     # A string used by the `meson install --tags` command
  java_resources               : structured_src                                                          # Resources to be added to the jar
  link_args                    : list[str]                                                               # Flags to use during linking
  link_depends                 : str | file | custom_tgt | custom_idx                                    # Strings, files, or custom targets the link step depends on
  link_language                : str                                                                     # Makes the linker for this target be for the specified language
  link_whole                   : list[lib | custom_tgt | custom_idx]                                     # Links all contents of the given static libraries whether they are used or
  link_with                    : list[lib | custom_tgt | custom_idx]                                     # One or more shared or static libraries
  main_class                   : str                                                                     # Main class for running the built jar
  name_prefix                  : str | list[void]                                                        # The string that will be used as the prefix for the
  name_suffix                  : str | list[void]                                                        # The string that will be used as the extension for the
  native                       : bool                                                                    # 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
  override_options             : list[str] | dict[str | bool | int | list[str]]                            # takes an array of strings in the same format as `project`'s `default_options`
  pic                          : bool                                                                    # Builds the library as positional independent code
  pie                          : bool                                                                    # Build a position-independent executable
  prelink                      : bool                                                                    # If `true` the object files in the target will be prelinked,
  rust_abi                     : str                                                                     # Set the specific ABI to compile (when compiling rust)
  rust_crate_type              : str                                                                     # Set the specific type of rust crate to compile (when compiling rust)
  rust_dependency_map          : dict[str]                                                               # On rust targets this provides a map of library names to the crate name
  sources                      : str | file | custom_tgt | custom_idx | generated_list | structured_src  # Additional source files
  soversion                    : str | int                                                               # A string or integer specifying the soversion of this shared library,
  target_type                  : str                                                                     # The actual target type to build
  vala_args                    : list[str | file]                                                        # Compiler flags for Vala
  vala_shared_args             : list[str | file]                                                        # Arguments that are only passed to a shared library
  vala_static_args             : list[str | file]                                                        # Arguments that are only passed to a static library
  version                      : str                                                                     # A string specifying the version of this shared library,
  vs_module_defs               : str | file | custom_tgt | custom_idx                                    # Specify a Microsoft module definition file for controlling symbol exports,
  win_subsystem                : str                                                                     # Specifies the subsystem type to use
)

Arguments

The function build_target() accepts the following positional arguments:

Additionally, the function accepts between 0 and infinity variadic arguments (source...) of type str | file | custom_tgt | custom_idx | generated_list.

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 on all generated input files, including unknown files. This is needed to bootstrap the generation of the real dependencies in the depfile 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.

Finally, build_target() accepts the following keyword arguments:

configuration_data()

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().

# Creates an empty configuration object
cfg_data configuration_data(
  dict[str | bool | int] [data],   # Optional dictionary to specify an initial data set
)

Arguments

The function configuration_data() accepts the following positional arguments:

configure_file()

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

# This function can run in three modes depending on the keyword arguments
file configure_file(
  capture       : bool                               # When this argument is set to true,
  command       : list[str | file]                   # As explained above, if specified, Meson does not create
  configuration : cfg_data | dict[str | int | bool]  # As explained above, when passed this will provide the replacement
  copy          : bool                               # As explained above, if specified Meson only
  depfile       : str                                # A dependency file that the command can write listing
  encoding      : str                                # Set the file encoding for the input and output file
  format        : str                                # The format of defines
  input         : str | file                         # The input file name
  install       : bool                               # When true, this generated file is installed during
  install_dir   : str                                # The subdirectory to install the generated file to
  install_mode  : list[str | int]                    # Specify the file mode in symbolic format
  install_tag   : str                                # A string used by the `meson install --tags` command
  macro_name    : str                                # When specified, macro guards will be used instead of '#pragma once'
  output        : str                                # The output file name
  output_format : str                                # The format of the output to generate when no input
)

Arguments

The function configure_file() accepts the following keyword arguments:

custom_target()

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.

# Create a custom top level build target
custom_tgt custom_target(
  str [name],   # The *unique* id of the custom target

  # Keyword arguments:
  build_always       : bool                                       # If `true` this target is always considered out of
  build_always_stale : bool                                       # If `true` the target is always considered out of date
  build_by_default   : bool                                       # Causes, when set to true, to
  capture            : bool                                       # There are some compilers that can't be told to write
  command            : list[str | file | exe | external_program]  # Command to run to create outputs from inputs
  console            : bool                                       # Keyword argument conflicts with `capture`, and is meant
  depend_files       : list[str | file]                           # files (str,
  depends            : list[build_tgt | custom_tgt | custom_idx]  # Specifies that this target depends on the specified
  depfile            : str                                        # A dependency file that the command can write listing
  env                : env | list[str] | dict[str]                # environment variables to set, such as
  feed               : bool                                       # There are some compilers that can't be told to read
  input              : list[str | file]                           # List of source files
  install            : bool                                       # When true, one or more files of this target are installed during the install step (see `install_dir` for details)
  install_dir        : str | list[str | bool]                     # If only one install_dir is provided, all outputs are installed there
  install_mode       : list[str | int]                            # The file mode and optionally the owner/uid and group/gid
  install_tag        : list[str]                                  # A list of strings, one per output, used by the `meson install --tags` command
  output             : list[str]                                  # List of output files
)

Arguments

The function custom_target() accepts the following positional arguments:

Finally, custom_target() accepts the following keyword arguments:

custom_target('different-install-dirs',
  output : ['first.file', 'second.file'],
  install : true,
  install_dir : ['somedir', 'otherdir'])

    custom_target('only-install-second',
      output : ['first.file', 'second.file'],
      install : true,
      install_dir : [false, 'otherdir'])

debug()

Write the argument string to the meson build log.

# Write the argument string to the meson build log
void debug(
  str | int | bool | list[str | int | bool] | dict[str | int | bool] message,     # The message to print
  str | int | bool | list[str | int | bool] | dict[str | int | bool] msg...,      # Additional parameters will be separated by spaces
)

Arguments

The function debug() accepts the following positional arguments:

Additionally, the function accepts between 0 and infinity variadic arguments (msg...) of type str | int | bool | list[str | int | bool] | dict[str | int | bool].

Additional parameters will be separated by spaces

declare_dependency()

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.

# This function returns a dep object that
dep declare_dependency(
  compile_args        : list[str]                                                    # Compile arguments to use
  d_import_dirs       : list[inc | str]                                              # the directories to add to the string search path (i
  d_module_versions   : str | int | list[str | int]                                  # The [D version identifiers](https://dlang
  dependencies        : list[dep]                                                    # Other dependencies needed to use this dependency
  extra_files         : list[str | file]                                             # extra files to add to targets
  include_directories : list[inc | str]                                              # the directories to add to header search path,
  link_args           : list[str]                                                    # Link arguments to use
  link_whole          : list[lib]                                                    # Libraries to link fully, same as executable().
  link_with           : list[lib]                                                    # Libraries to link against
  objects             : list[extracted_obj]                                          # a list of object files, to be linked directly into the targets that use the
  sources             : list[str | file | custom_tgt | custom_idx | generated_list]  # sources to add to targets
  variables           : dict[str] | list[str]                                        # a dictionary of arbitrary strings,
  version             : str                                                          # the version of this dependency,
)

Arguments

The function declare_dependency() accepts the following keyword arguments:

dependency()

Finds an external dependency (usually a library installed on your system) with the given name with pkg-config and with CMake if pkg-config fails. Additionally, frameworks (OSX only) and library-specific fallback detection logic 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 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 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.

# Finds an external dependency (usually a library installed on your
dep dependency(
  str names...,  # The names of the dependency to look up

  # Keyword arguments:
  allow_fallback    : bool                                          # Specifies whether Meson should automatically pick a fallback subproject
  default_options   : list[str] | dict[str | bool | int | list[str]]  # An array of default option values
  disabler          : bool                                          # Returns a disabler() object instead of a not-found dependency
  fallback          : list[str] | str                               # Manually specifies a subproject fallback
  include_type      : str                                           # An enum flag, marking how the dependency
  language          : str                                           # Defines what language-specific dependency to find
  method            : str                                           # Defines the way the dependency is detected, the default is
  native            : bool                                          # If set to `true`, causes Meson to find the dependency on
  not_found_message : str                                           # An optional string that will be printed as a message() if the dependency was not found.
  required          : bool | feature                                # When set to `false`, Meson will proceed with the build
  static            : bool                                          # Tells the dependency provider to try to get static
  version           : list[str] | str                               # Specifies the required version,
)

Arguments

The function accepts between 1 and infinity variadic arguments (names...) of type str.

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.

The function dependency() accepts the following keyword arguments:

disabler()

Returns a disabler object.

disabler disabler()

environment()

Returns an empty env object.

# Returns an empty env object.
env environment(
  str | list[str] | dict[str] | dict[list[str]] [env],   # If provided, each key/value pair is added into the env object

  # Keyword arguments:
  method    : str  # Must be one of 'set', 'prepend', or 'append'
  separator : str  # The separator to use for the initial values defined in
)

Arguments

Argument flattening is NOT SUPPORTED by this function.

The function environment() accepts the following positional arguments:

Finally, environment() accepts the following keyword arguments:

error()

Print the argument string and halts the build process.

# Print the argument string and halts the build process
void error(
  str message,     # The message to print
  str msg...,      # Additional parameters will be separated by spaces
)

Arguments

Argument flattening is NOT SUPPORTED by this function.

The function error() accepts the following positional arguments:

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

Additional parameters will be separated by spaces

executable()

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.

# Creates a new executable
exe executable(
  str                                                   target_name,     # The *unique* name of the build target
  str | file | custom_tgt | custom_idx | generated_list source...,       # Input source to compile

  # Keyword arguments:
  <lang>_args                  : list[str]                                                               # compiler flags to use for the given language;
  <lang>_pch                   : str                                                                     # precompiled header file to use for the given language
  build_by_default             : bool                                                                    # Causes, when set to `true`, to have this target be built by default
  build_rpath                  : str                                                                     # A string to add to target's rpath definition in the build dir,
  d_debug                      : list[str]                                                               # The [D version identifiers](https://dlang
  d_import_dirs                : list[inc | str]                                                         # the directories to add to the string search path (i
  d_module_versions            : list[str | int]                                                         # List of module version identifiers set when compiling D sources
  d_unittest                   : bool                                                                    # When set to true, the D modules are compiled in debug mode
  dependencies                 : list[dep]                                                               # one or more dependency objects
  export_dynamic               : bool                                                                    # when set to true causes the target's symbols to be
  extra_files                  : str | file | custom_tgt | custom_idx                                    # Not used for the build itself but are shown as source files in IDEs
  gnu_symbol_visibility        : str                                                                     # Specifies how symbols should be exported, see
  gui_app                      : bool                                                                    # When set to true flags this target as a GUI application
  implib                       : bool | str                                                              # When set to true, an import library is generated for the
  implicit_include_directories : bool                                                                    # 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,
  install                      : bool                                                                    # When set to true, this executable should be installed
  install_dir                  : str                                                                     # override install directory for this file
  install_mode                 : list[str | int]                                                         # Specify the file mode in symbolic format
  install_rpath                : str                                                                     # A string to set the target's rpath to after install
  install_tag                  : str                                                                     # A string used by the `meson install --tags` command
  link_args                    : list[str]                                                               # Flags to use during linking
  link_depends                 : str | file | custom_tgt | custom_idx                                    # Strings, files, or custom targets the link step depends on
  link_language                : str                                                                     # Makes the linker for this target be for the specified language
  link_whole                   : list[lib | custom_tgt | custom_idx]                                     # Links all contents of the given static libraries whether they are used or
  link_with                    : list[lib | custom_tgt | custom_idx]                                     # One or more shared or static libraries
  name_prefix                  : str | list[void]                                                        # The string that will be used as the prefix for the
  name_suffix                  : str | list[void]                                                        # The string that will be used as the extension for the
  native                       : bool                                                                    # 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
  override_options             : list[str] | dict[str | bool | int | list[str]]                            # takes an array of strings in the same format as `project`'s `default_options`
  pie                          : bool                                                                    # Build a position-independent executable
  rust_crate_type              : str                                                                     # Set the specific type of rust crate to compile (when compiling rust)
  rust_dependency_map          : dict[str]                                                               # On rust targets this provides a map of library names to the crate name
  sources                      : str | file | custom_tgt | custom_idx | generated_list | structured_src  # Additional source files
  vala_args                    : list[str | file]                                                        # Compiler flags for Vala
  vs_module_defs               : str | file | custom_tgt | custom_idx                                    # Specify a Microsoft module definition file for controlling symbol exports,
  win_subsystem                : str                                                                     # Specifies the subsystem type to use
)

Arguments

The function executable() accepts the following positional arguments:

Additionally, the function accepts between 0 and infinity variadic arguments (source...) of type str | file | custom_tgt | custom_idx | generated_list.

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 on all generated input files, including unknown files. This is needed to bootstrap the generation of the real dependencies in the depfile 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.

Finally, executable() accepts the following keyword arguments:

files()

This command takes the strings given to it in arguments and returns corresponding File objects that you can use as sources for build targets. The difference is that file objects remember the subdirectory they were defined in and can be used anywhere in the source tree.

# This command takes the strings given to it in arguments and returns
list[file] files(
  str file...,  # Path to the file
)

Example

As an example suppose you have source file foo.cpp in subdirectory bar1 and you would like to use it in a build target that is defined in bar2. To make this happen you first create the object in bar1 like this:

    foofile = files('foo.cpp')

Then you can use it in bar2 like this:

    executable('myprog', 'myprog.cpp', foofile, ...)

Meson will then do the right thing.

Arguments

The function accepts between 0 and infinity variadic arguments (file...) of type str.

Path to the file.

find_program()

program_name here is a string that can be an executable or script to be searched for in PATH or other places inside the project. The search order is:

1. Program overrides set via meson.override_find_program()
2. [provide] sections in subproject wrap files, if wrap_mode is set to forcefallback
3. [binaries] section in your machine files
4. Directories provided using the dirs: kwarg (see below)
5. Project's source tree relative to the current subdir
   • If you use the return value of configure_file(), the current subdir inside the build tree is used instead
6. PATH environment variable
7. [provide] sections in subproject wrap files, if wrap_mode is set to anything other than nofallback

Meson will also autodetect scripts with a shebang line and run them with the executable/interpreter specified in it both on Windows (because the command invocator will reject the command otherwise) and Unixes (if the script file does not have the executable bit set). Hence, you must not manually add the interpreter while using this script as part of a list of commands. Since 0.50.0 if the "python3" program is requested and it is not found in the system, Meson will return its current interpreter.

If you need to check for a program in a non-standard location, you can just pass an absolute path to find_program, e.g.

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

It is also possible to pass an array to find_program in case you need to construct the set of paths to search on the fly:

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

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

The returned external_program object also has documented methods.

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

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

Arguments

The function find_program() accepts the following positional arguments:

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

These parameters are used as fallback names to search for. This is meant to be used for cases where the program may have many alternative names, such as foo and foo.py. The function will check for the arguments one by one and the first one that is found is returned.

Finally, find_program() accepts the following keyword arguments:

generator()

See also: custom_target()

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

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

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

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

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

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

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

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

# See also: custom_target()
generator generator(
  exe | external_program exe,     # Executable for the command to run

  # Keyword arguments:
  arguments : list[str]                                  # A list of template strings that will be the command line arguments passed to the executable
  capture   : bool                                       # When this argument is set to true, Meson captures `stdout`
  depends   : list[build_tgt | custom_tgt | custom_idx]  # An array of build targets that must be built before
  depfile   : str                                        # A template string pointing to a dependency file that a
  output    : list[str]                                  # Template string (or list of template strings) defining
)

Arguments

The function generator() accepts the following positional arguments:

Finally, generator() accepts the following keyword arguments: