14322 lines
300 KiB
Groff
14322 lines
300 KiB
Groff
.P
|
|
.TH "meson-reference" "3" "2022-12-23"
|
|
.P
|
|
.SH NAME
|
|
.P
|
|
meson-reference v1.0.0 - a reference for meson functions and objects
|
|
.P
|
|
.SH DESCRIPTION
|
|
This manual is divided into two sections, \fBFUNCTIONS\fR and \fBOBJECTS\fR. \fBFUNCTIONS\fR contains a reference for all meson functions and methods. Methods are denoted by \fIobject_name\fR.\fImethod_name\fR(). \fBOBJECTS\fR contains additional information about each object.
|
|
.P
|
|
.SH FUNCTIONS
|
|
.P
|
|
.SS add_global_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR add_global_arguments(
|
|
.br
|
|
.RS 4
|
|
Compiler argument...,
|
|
.br
|
|
language:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Adds global arguments to the compiler command line.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBCompiler argument\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The compiler arguments to add
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBlanguage\fR
|
|
\fIlist[str]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
Usually you should use \fIadd_project_arguments\fR instead, because that works even when you project is used as a subproject.
|
|
You must pass always arguments individually `arg1, arg2, ...` rather than as a string `'arg1 arg2', ...`
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS add_global_link_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR add_global_link_arguments(
|
|
.br
|
|
.RS 4
|
|
Linker argument...,
|
|
.br
|
|
language:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Adds global arguments to the linker command line.
|
|
|
|
Like \fIadd_global_arguments\fR but the arguments are passed to the linker.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBLinker argument\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The linker arguments to add
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBlanguage\fR
|
|
\fIlist[str]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
Usually you should use \fIadd_project_link_arguments\fR instead, because that works even when you project is used as a subproject.
|
|
You must pass always arguments individually `arg1, arg2, ...` rather than as a string `'arg1 arg2', ...`
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS add_languages()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR add_languages(Language..., native:, required: \fBtrue\fR)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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(\fBlangs\fR, native: false, required: \fBrequired\fR) and
|
|
add_languages(\fBlangs\fR, native: true, required: false)`. This default behaviour
|
|
may change to `native: false` in a future Meson version.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBLanguage\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The languages to add
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBnative\fR
|
|
\fIbool\fR, since 0.54.0
|
|
.br
|
|
.RS 2
|
|
If set to `true`, the language will be used to compile for the build
|
|
machine, if `false`, for the host machine.
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool\fR, default: true
|
|
.br
|
|
.RS 2
|
|
If set to `true`, Meson will halt if any of the languages
|
|
specified are not found. \fB(since 0.47.0)\fR The value of a
|
|
\fI`feature`\fR[1] option can also be passed.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
project('foobar', 'c')
|
|
.br
|
|
|
|
.br
|
|
if compiling_for_osx
|
|
.br
|
|
add_languages('objc')
|
|
.br
|
|
endif
|
|
.br
|
|
if add_languages('cpp', required : false)
|
|
.br
|
|
executable('cpp-app', 'main.cpp')
|
|
.br
|
|
endif
|
|
.br
|
|
|
|
.br
|
|
# More code...
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS add_project_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR add_project_arguments(
|
|
.br
|
|
.RS 4
|
|
Compiler argument...,
|
|
.br
|
|
language:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Adds project specific arguments to the compiler command line.
|
|
|
|
This function behaves in the same way as \fIadd_global_arguments\fR except
|
|
that the arguments are only used for the current project, they won't
|
|
be used in any other subproject.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBCompiler argument\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The compiler arguments to add
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBlanguage\fR
|
|
\fIlist[str]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
You must pass always arguments individually `arg1, arg2, ...` rather than as a string `'arg1 arg2', ...`
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS add_project_dependencies()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR add_project_dependencies(
|
|
.br
|
|
.RS 4
|
|
dependencies...,
|
|
.br
|
|
language:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.63.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBdependencies\fR
|
|
\fIdep\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The dependencies to add; if internal dependencies are included, they must not include any built object.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBlanguage\fR
|
|
\fIlist[str]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS add_project_link_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR add_project_link_arguments(
|
|
.br
|
|
.RS 4
|
|
Linker argument...,
|
|
.br
|
|
language:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Adds global arguments to the linker command line.
|
|
|
|
Like \fIadd_global_arguments\fR but the arguments are passed to the linker.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBLinker argument\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The linker arguments to add
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBlanguage\fR
|
|
\fIlist[str]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
You must pass always arguments individually `arg1, arg2, ...` rather than as a string `'arg1 arg2', ...`
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS add_test_setup()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR add_test_setup(
|
|
.br
|
|
.RS 4
|
|
name,
|
|
.br
|
|
env:,
|
|
.br
|
|
exclude_suites:,
|
|
.br
|
|
exe_wrapper:,
|
|
.br
|
|
gdb: \fBfalse\fR,
|
|
.br
|
|
is_default: \fBfalse\fR,
|
|
.br
|
|
timeout_multiplier: \fB1\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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=\fBname\fR` 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.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the test setup
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBenv\fR
|
|
\fIenv | list[str] | dict[str]\fR
|
|
.br
|
|
.RS 2
|
|
environment variables to set
|
|
, such as `['NAME1=value1', 'NAME2=value2']`,
|
|
or an \fIenv\fR object which allows more sophisticated
|
|
environment juggling. \fB(Since 0.52.0)\fR A dictionary is also accepted.
|
|
.RE
|
|
|
|
\fBexclude_suites\fR
|
|
\fIlist[str]\fR, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
A list of test suites that should be excluded when using this setup. Suites specified in the `--suite` option to `meson test` will always run, overriding `add_test_setup` if necessary.
|
|
.RE
|
|
|
|
\fBexe_wrapper\fR
|
|
\fIlist[str | external_program]\fR
|
|
.br
|
|
.RS 2
|
|
The command or script followed by the arguments to it
|
|
.RE
|
|
|
|
\fBgdb\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
If `true`, the tests are also run under `gdb`
|
|
.RE
|
|
|
|
\fBis_default\fR
|
|
\fIbool\fR, default: false, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Set whether this is the default test setup.
|
|
If `true`, the setup will be used whenever `meson test` is run
|
|
without the `--setup` option.
|
|
.RE
|
|
|
|
\fBtimeout_multiplier\fR
|
|
\fIint\fR, default: 1
|
|
.br
|
|
.RS 2
|
|
A number to multiply the test timeout with.
|
|
\fBSince 0.57\fR if timeout_multiplier is `<= 0` the test has infinite duration,
|
|
in previous versions of Meson the test would fail with a timeout immediately.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS alias_target()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIalias_tgt\fR alias_target(target_name, Dep...)
|
|
|
|
since 0.52.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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 (e.g. return value of
|
|
\fIexecutable\fR, \fIcustom_target\fR, etc)
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the alias target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBDep\fR
|
|
\fItgt\fR, 1...N times
|
|
.br
|
|
.RS 2
|
|
The targets to depend on
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS assert()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR assert(condition, [message])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Abort with an error message if `condition` evaluates to `false`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBcondition\fR
|
|
\fIbool\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Abort if this evaluates to `false`
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBmessage\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The error message to print.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
The `message` argument is optional since 0.53.0 and defaults to print the condition statement.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS benchmark()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR benchmark(
|
|
.br
|
|
.RS 4
|
|
name,
|
|
.br
|
|
executable,
|
|
.br
|
|
args:,
|
|
.br
|
|
depends:,
|
|
.br
|
|
env:,
|
|
.br
|
|
priority: \fB0\fR,
|
|
.br
|
|
protocol: \fB'exitcode'\fR,
|
|
.br
|
|
should_fail: \fBfalse\fR,
|
|
.br
|
|
suite:,
|
|
.br
|
|
timeout: \fB30\fR,
|
|
.br
|
|
verbose: \fBfalse\fR,
|
|
.br
|
|
workdir:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Creates a benchmark item that will be run when the benchmark target is
|
|
run. The behavior of this function is identical to \fItest\fR
|
|
except for:
|
|
|
|
* benchmark() has no `is_parallel` keyword because benchmarks are not run in parallel
|
|
.br
|
|
* benchmark() does not automatically add the `MALLOC_PERTURB_` environment variable
|
|
|
|
Defined tests can be run in a backend-agnostic way by calling
|
|
`meson test` inside the build dir, or by using backend-specific
|
|
commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR test id
|
|
.RE
|
|
|
|
\fBexecutable\fR
|
|
\fIexe | jar | external_program | file\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The program to execute
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str | file | tgt]\fR
|
|
.br
|
|
.RS 2
|
|
Arguments to pass to the executable
|
|
.RE
|
|
|
|
\fBdepends\fR
|
|
\fIlist[build_tgt | custom_tgt]\fR, since 0.46.0
|
|
.br
|
|
.RS 2
|
|
specifies that this test depends on the specified
|
|
target(s), even though it does not take any of them as a command
|
|
line argument. This is meant for cases where test finds those
|
|
targets internally, e.g. plugins or globbing. Those targets are built
|
|
before test is executed even if they have `build_by_default : false`.
|
|
.RE
|
|
|
|
\fBenv\fR
|
|
\fIenv | list[str] | dict[str]\fR
|
|
.br
|
|
.RS 2
|
|
environment variables to set, such as `['NAME1=value1',
|
|
\'NAME2=value2']`, or an \fIenv\fR object which allows more sophisticated
|
|
environment juggling. \fB(Since 0.52.0)\fR A dictionary is also accepted.
|
|
.RE
|
|
|
|
\fBpriority\fR
|
|
\fIint\fR, default: 0, since 0.52.0
|
|
.br
|
|
.RS 2
|
|
specifies the priority of a test. Tests with a
|
|
higher priority are \fBstarted\fR before tests with a lower priority.
|
|
The starting order of tests with identical priorities is
|
|
implementation-defined. The default priority is 0, negative numbers are
|
|
permitted.
|
|
.RE
|
|
|
|
\fBprotocol\fR
|
|
\fIstr\fR, default: 'exitcode', since 0.50.0
|
|
.br
|
|
.RS 2
|
|
specifies how the test results are parsed and can
|
|
be one of `exitcode`, `tap`, or `gtest`. For more information about test
|
|
harness protocol read \fIUnit Tests\fR[2]. The following values are
|
|
accepted:
|
|
|
|
- `exitcode`: the executable's exit code is used by the test harness to record the outcome of the test).
|
|
.br
|
|
- `tap`: \fITest Anything Protocol\fR[3].
|
|
.br
|
|
- `gtest` \fB(since 0.55.0)\fR: for Google Tests.
|
|
.br
|
|
- `rust` \fB(since 0.56.0)\fR: for native rust tests
|
|
.RE
|
|
|
|
\fBshould_fail\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
when true the test is considered passed if the
|
|
executable returns a non-zero return value (i.e. reports an error)
|
|
.RE
|
|
|
|
\fBsuite\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
`'label'` (or list of labels `['label1', 'label2']`)
|
|
attached to this test. The suite name is qualified by a (sub)project
|
|
name resulting in `(sub)project_name:label`. In the case of a list
|
|
of strings, the suite names will be `(sub)project_name:label1`,
|
|
`(sub)project_name:label2`, etc.
|
|
.RE
|
|
|
|
\fBtimeout\fR
|
|
\fIint\fR, default: 30
|
|
.br
|
|
.RS 2
|
|
the amount of seconds the test is allowed to run, a test
|
|
that exceeds its time limit is always considered failed, defaults to
|
|
30 seconds. \fBSince 0.57\fR if timeout is `<= 0` the test has infinite duration,
|
|
in previous versions of Meson the test would fail with a timeout immediately.
|
|
.RE
|
|
|
|
\fBverbose\fR
|
|
\fIbool\fR, default: false, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
if true, forces the test results to be logged as if `--verbose` was passed
|
|
to `meson test`.
|
|
.RE
|
|
|
|
\fBworkdir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
absolute path that will be used as the working directory
|
|
for the test
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
Prior to 0.52.0 benchmark would warn that `depends` and `priority` were unsupported, this is incorrect.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS both_libraries()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIboth_libs\fR both_libraries(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
darwin_versions:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
pic:,
|
|
.br
|
|
prelink:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
soversion:,
|
|
.br
|
|
version:,
|
|
.br
|
|
vs_module_defs:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Builds both a static and shared library with the given sources.
|
|
Positional and keyword arguments are otherwise the same as for
|
|
\fIlibrary\fR. 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.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[4] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[5] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[6] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdarwin_versions\fR
|
|
\fIstr | int | list[str]\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Defines the `compatibility version` and `current version` for the dylib on macOS.
|
|
If a list is specified, it must be
|
|
either zero, one, or two elements. If only one element is specified
|
|
or if it's not a list, the specified value will be used for setting
|
|
both compatibility version and current version. If unspecified, the
|
|
`soversion` will be used as per the aforementioned rules.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[7] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBpic\fR
|
|
\fIbool\fR, since 0.36.0
|
|
.br
|
|
.RS 2
|
|
Builds the library as positional independent code
|
|
(so it can be linked into a shared library). This
|
|
option has no effect on Windows and OS X since it doesn't make
|
|
sense on Windows and PIC cannot be disabled on OS X.
|
|
.RE
|
|
|
|
\fBprelink\fR
|
|
\fIbool\fR, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
If `true` the object files in the target will be prelinked,
|
|
meaning that it will contain only one prelinked
|
|
object file rather than the individual object files.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBsoversion\fR
|
|
\fIstr | int\fR
|
|
.br
|
|
.RS 2
|
|
A string or integer specifying the soversion of this shared library,
|
|
such as `0`. On Linux and Windows this is used to set the
|
|
soversion (or equivalent) in the filename. For example, if
|
|
`soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one
|
|
of the aliases of the Linux shared library would be
|
|
`libfoo.so.4`. If this is not specified, the first part of `version`
|
|
is used instead (see below). For example, if `version` is `3.6.0` and
|
|
`soversion` is not defined, it is set to `3`.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string specifying the version of this shared library,
|
|
such as `1.1.0`. On Linux and OS X, this is used to set the shared
|
|
library version in the filename, such as `libfoo.so.1.1.0` and
|
|
`libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used
|
|
instead (see above).
|
|
.RE
|
|
|
|
\fBvs_module_defs\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Specify a Microsoft module definition file for controlling symbol exports,
|
|
etc., on platforms where that is possible (e.g. Windows).
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[8]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS build_target()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbuild_tgt\fR build_target(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
darwin_versions:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
export_dynamic:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implib:,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
java_resources:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
main_class:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
pic:,
|
|
.br
|
|
pie:,
|
|
.br
|
|
prelink:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
soversion:,
|
|
.br
|
|
target_type:,
|
|
.br
|
|
version:,
|
|
.br
|
|
vs_module_defs:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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 \fIexecutable\fR)
|
|
.br
|
|
- `shared_library` (see \fIshared_library\fR)
|
|
.br
|
|
- `shared_module` (see \fIshared_module\fR)
|
|
.br
|
|
- `static_library` (see \fIstatic_library\fR)
|
|
.br
|
|
- `both_libraries` (see \fIboth_libraries\fR)
|
|
.br
|
|
- `library` (see \fIlibrary\fR)
|
|
.br
|
|
- `jar` (see \fIjar\fR)
|
|
|
|
This declaration:
|
|
.RS 4
|
|
executable(<arguments and keyword arguments>)
|
|
.br
|
|
.RE
|
|
is equivalent to this:
|
|
.RS 4
|
|
build_target(<arguments and keyword arguments>, target_type : 'executable')
|
|
.br
|
|
.RE
|
|
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 \fIbuild_tgt\fR.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdarwin_versions\fR
|
|
\fIstr | int | list[str]\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Defines the `compatibility version` and `current version` for the dylib on macOS.
|
|
If a list is specified, it must be
|
|
either zero, one, or two elements. If only one element is specified
|
|
or if it's not a list, the specified value will be used for setting
|
|
both compatibility version and current version. If unspecified, the
|
|
`soversion` will be used as per the aforementioned rules.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBexport_dynamic\fR
|
|
\fIbool\fR, since 0.45.0
|
|
.br
|
|
.RS 2
|
|
when set to true causes the target's symbols to be
|
|
dynamically exported, allowing modules built using the
|
|
\fIshared_module\fR function to refer to functions,
|
|
variables and other symbols defined in the executable itself. Implies
|
|
the `implib` argument.
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[6] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplib\fR
|
|
\fIbool | str\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
When set to true, an import library is generated for the
|
|
executable (the name of the import library is based on \fBexe_name\fR).
|
|
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.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBjava_resources\fR
|
|
\fIstructured_src\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
Resources to be added to the jar
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBmain_class\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Main class for running the built jar
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBpic\fR
|
|
\fIbool\fR, since 0.36.0
|
|
.br
|
|
.RS 2
|
|
Builds the library as positional independent code
|
|
(so it can be linked into a shared library). This
|
|
option has no effect on Windows and OS X since it doesn't make
|
|
sense on Windows and PIC cannot be disabled on OS X.
|
|
.RE
|
|
|
|
\fBpie\fR
|
|
\fIbool\fR, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Build a position-independent executable.
|
|
.RE
|
|
|
|
\fBprelink\fR
|
|
\fIbool\fR, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
If `true` the object files in the target will be prelinked,
|
|
meaning that it will contain only one prelinked
|
|
object file rather than the individual object files.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBsoversion\fR
|
|
\fIstr | int\fR
|
|
.br
|
|
.RS 2
|
|
A string or integer specifying the soversion of this shared library,
|
|
such as `0`. On Linux and Windows this is used to set the
|
|
soversion (or equivalent) in the filename. For example, if
|
|
`soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one
|
|
of the aliases of the Linux shared library would be
|
|
`libfoo.so.4`. If this is not specified, the first part of `version`
|
|
is used instead (see below). For example, if `version` is `3.6.0` and
|
|
`soversion` is not defined, it is set to `3`.
|
|
.RE
|
|
|
|
\fBtarget_type\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The actual target to build
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string specifying the version of this shared library,
|
|
such as `1.1.0`. On Linux and OS X, this is used to set the shared
|
|
library version in the filename, such as `libfoo.so.1.1.0` and
|
|
`libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used
|
|
instead (see above).
|
|
.RE
|
|
|
|
\fBvs_module_defs\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Specify a Microsoft module definition file for controlling symbol exports,
|
|
etc., on platforms where that is possible (e.g. Windows).
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[7]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS configuration_data()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIcfg_data\fR configuration_data([data])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Creates an empty configuration object. You should add your
|
|
configuration with the \fIcfg_data\fR method calls and
|
|
finally use it in a call to \fIconfigure_file\fR.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBdata\fR
|
|
\fIdict[str | bool | int]\fR, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Optional dictionary to specify an initial data set. If
|
|
provided, each key/value pair is added into the \fIcfg_data\fR object
|
|
as if the \fIcfg_data.set\fR method was called for each of them.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS configure_file()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIfile\fR configure_file(
|
|
.br
|
|
.RS 4
|
|
capture: \fBfalse\fR,
|
|
.br
|
|
command:,
|
|
.br
|
|
configuration:,
|
|
.br
|
|
copy: \fBfalse\fR,
|
|
.br
|
|
depfile:,
|
|
.br
|
|
encoding: \fB'utf-8'\fR,
|
|
.br
|
|
format: \fB'meson'\fR,
|
|
.br
|
|
input:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
output:,
|
|
.br
|
|
output_format:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This function can run in three modes depending on the keyword arguments
|
|
passed to it.
|
|
|
|
When a \fIcfg_data\fR 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 \fIthe
|
|
configuration file documentation\fR[9]. \fB(since 0.49.0)\fR
|
|
A dictionary can be passed instead of a
|
|
\fIcfg_data\fR 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.
|
|
|
|
\fB(since 0.47.0)\fR 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.
|
|
.RE
|
|
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcapture\fR
|
|
\fIbool\fR, default: false, since 0.41.0
|
|
.br
|
|
.RS 2
|
|
When this argument is set to true,
|
|
Meson captures `stdout` of the `command` and writes it to the target
|
|
file specified as `output`.
|
|
.RE
|
|
|
|
\fBcommand\fR
|
|
\fIlist[str | file]\fR
|
|
.br
|
|
.RS 2
|
|
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. \fB(since 0.52.0)\fR The command can contain
|
|
file objects and more than one file can be passed to the `input` keyword
|
|
argument, see \fIcustom_target\fR for details about string
|
|
substitutions.
|
|
.RE
|
|
|
|
\fBconfiguration\fR
|
|
\fIcfg_data | dict[str | int | bool]\fR
|
|
.br
|
|
.RS 2
|
|
As explained above, when passed this will provide the replacement
|
|
data for the input file (if provided) or key value pairs to be
|
|
written to the output.
|
|
.RE
|
|
|
|
\fBcopy\fR
|
|
\fIbool\fR, default: false, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
As explained above, if specified Meson only
|
|
copies the file from input to output.
|
|
.RE
|
|
|
|
\fBdepfile\fR
|
|
\fIstr\fR, since 0.52.0
|
|
.br
|
|
.RS 2
|
|
A dependency file that the command can write listing
|
|
all the additional files this target depends on. A change
|
|
in any one of these files triggers a reconfiguration.
|
|
.RE
|
|
|
|
\fBencoding\fR
|
|
\fIstr\fR, default: 'utf-8', since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Set the file encoding for the input and output file.
|
|
The supported encodings are those of python3, see
|
|
\fIstandard-encodings\fR[10].
|
|
.RE
|
|
|
|
\fBformat\fR
|
|
\fIstr\fR, default: 'meson', since 0.46.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBinput\fR
|
|
\fIstr | file\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false, since 0.50.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default the file has no install
|
|
tag which means it is not being installed when `--tags` argument is specified.
|
|
.RE
|
|
|
|
\fBoutput\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The output file name. \fB(since 0.41.0)\fR 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.
|
|
.RE
|
|
|
|
\fBoutput_format\fR
|
|
\fIstr\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
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 `%`.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS custom_target()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIcustom_tgt\fR custom_target(
|
|
.br
|
|
.RS 4
|
|
[name],
|
|
.br
|
|
build_always:,
|
|
.br
|
|
build_always_stale: \fBfalse\fR,
|
|
.br
|
|
build_by_default:,
|
|
.br
|
|
capture: \fBfalse\fR,
|
|
.br
|
|
command:,
|
|
.br
|
|
console:,
|
|
.br
|
|
depend_files:,
|
|
.br
|
|
depends:,
|
|
.br
|
|
depfile:,
|
|
.br
|
|
env:,
|
|
.br
|
|
feed: \fBfalse\fR,
|
|
.br
|
|
input:,
|
|
.br
|
|
install:,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
output:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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.
|
|
.RS 4
|
|
custom_target('foo', output: 'file.txt', ...)
|
|
.br
|
|
.RE
|
|
\fBSince 0.60.0\fR 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@']`.
|
|
.br
|
|
- `@OUTPUT@`: the full path to the output passed to `output`. If more than one outputs are specified, the behavior is the same as `@INPUT@`.
|
|
.br
|
|
- `@INPUT0@` `@INPUT1@` `...`: the full path to the input with the specified array index in `input`
|
|
.br
|
|
- `@OUTPUT0@` `@OUTPUT1@` `...`: the full path to the output with the specified array index in `output`
|
|
.br
|
|
- `@OUTDIR@`: the full path to the directory where the output(s) must be written
|
|
.br
|
|
- `@DEPFILE@`: the full path to the dependency file passed to `depfile`
|
|
.br
|
|
- `@PLAINNAME@`: the input filename, without a path
|
|
.br
|
|
- `@BASENAME@`: the input filename, with extension removed
|
|
.br
|
|
- `@PRIVATE_DIR@` \fB(since 0.50.1)\fR: path to a directory where the custom target must store all its intermediate files.
|
|
.br
|
|
- `@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.
|
|
.br
|
|
- `@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.
|
|
.br
|
|
- `@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.
|
|
|
|
\fB(since 0.47.0)\fR The `depfile` keyword argument also accepts the
|
|
`@BASENAME@` and `@PLAINNAME@` substitutions.
|
|
|
|
The returned object also has methods that are documented in \fIcustom_tgt\fR.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBname\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR id of the custom target
|
|
|
|
This posarg is optional \fBsince 0.60.0\fR. It defaults to the basename
|
|
of the first output.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBbuild_always\fR
|
|
\fIbool\fR, \fBdeprecated\fR since 0.47.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBbuild_always_stale\fR
|
|
\fIbool\fR, default: false, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to true, to
|
|
have this target be built by default. This means it will be built when
|
|
`meson compile` is called without any arguments. The default value is `false`.
|
|
|
|
\fB(since 0.50.0)\fR 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.
|
|
.RE
|
|
|
|
\fBcapture\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBcommand\fR
|
|
\fIlist[str | file | exe | external_program]\fR
|
|
.br
|
|
.RS 2
|
|
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 \fIfind_program\fR,
|
|
\fIexecutable\fR, \fIconfigure_file\fR,
|
|
\fIfiles\fR, \fIcustom_target\fR, 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 \fBnot\fR work.
|
|
.RE
|
|
|
|
\fBconsole\fR
|
|
\fIbool\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
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 \fINinja's `console` pool\fR[11],
|
|
which has special properties such as not buffering stdout and
|
|
serializing all targets in this pool.
|
|
.RE
|
|
|
|
\fBdepend_files\fR
|
|
\fIlist[str | file]\fR
|
|
.br
|
|
.RS 2
|
|
files (\fIstr\fR,
|
|
\fIfile\fR, or the return value of \fIconfigure_file\fR that
|
|
this target depends on but are not listed in the `command` keyword
|
|
argument. Useful for adding regen dependencies.
|
|
.RE
|
|
|
|
\fBdepends\fR
|
|
\fIlist[build_tgt | custom_tgt]\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBdepfile\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
|
|
\fB(since 0.47.0)\fR the `@BASENAME@` and `@PLAINNAME@` substitutions
|
|
are also accepted.
|
|
.RE
|
|
|
|
\fBenv\fR
|
|
\fIenv | list[str] | dict[str]\fR, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
environment variables to set, such as
|
|
`{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`,
|
|
or an \fIenv\fR object which allows more
|
|
sophisticated environment juggling.
|
|
.RE
|
|
|
|
\fBfeed\fR
|
|
\fIbool\fR, default: false, since 0.59.0
|
|
.br
|
|
.RS 2
|
|
There are some compilers that can't be told to read
|
|
their input from a file and instead read it from standard input. When this
|
|
argument is set to `true`, Meson feeds the input file to `stdin`. Note that
|
|
your argument list may not contain `@INPUT@` when feed mode is active.
|
|
.RE
|
|
|
|
\fBinput\fR
|
|
\fIlist[str | file]\fR
|
|
.br
|
|
.RS 2
|
|
List of source files. \fB(since 0.41.0)\fR the list is flattened.
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR
|
|
.br
|
|
.RS 2
|
|
When true, one or more files of this target are installed during the install step (see `install_dir` for details).
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr | list[str | bool]\fR
|
|
.br
|
|
.RS 2
|
|
If only one install_dir is provided, all outputs are installed there.
|
|
\fBSince 0.40.0\fR Allows you to specify the installation directory for each
|
|
corresponding output. For example:
|
|
.RS 4
|
|
custom_target('different-install-dirs',
|
|
.br
|
|
output : ['first.file', 'second.file'],
|
|
.br
|
|
install : true,
|
|
.br
|
|
install_dir : ['somedir', 'otherdir'])
|
|
.br
|
|
.RE
|
|
This would install `first.file` to `somedir` and `second.file` to `otherdir`.
|
|
|
|
To only install some outputs, pass `false` for the outputs that you
|
|
don't want installed. For example:
|
|
.RS 4
|
|
custom_target('only-install-second',
|
|
.br
|
|
output : ['first.file', 'second.file'],
|
|
.br
|
|
install : true,
|
|
.br
|
|
install_dir : [false, 'otherdir'])
|
|
.br
|
|
.RE
|
|
This would install `second.file` to `otherdir` and not install `first.file`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
The file mode and optionally the owner/uid and group/gid.
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIlist[str]\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A list of strings, one per output, used by the `meson install --tags` command
|
|
to install only a subset of the files.
|
|
|
|
By default all outputs have no install tag which means they are not being
|
|
installed when `--tags` argument is specified. If only one tag is specified,
|
|
it is assumed that all outputs have the same tag. `false` can be used for
|
|
outputs that have no tag or are not installed.
|
|
.RE
|
|
|
|
\fBoutput\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of output files.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
Assuming that `command:` is executed by a POSIX `sh` shell
|
|
is not portable, notably to Windows. Instead, consider using a
|
|
`native: true` \fIexecutable\fR, or a python script.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS debug()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR debug(message, msg...)
|
|
|
|
since 0.63.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Write the argument string to the meson build log.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBmessage\fR
|
|
\fIstr | int | bool | list[str | int | bool] | dict[str | int | bool]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The message to print
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBmsg\fR
|
|
\fIstr | int | bool | list[str | int | bool] | dict[str | int | bool]\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Additional parameters will be separated by spaces
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS declare_dependency()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIdep\fR declare_dependency(
|
|
.br
|
|
.RS 4
|
|
compile_args:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
variables:,
|
|
.br
|
|
version:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This function returns a \fIdep\fR object that
|
|
behaves like the return value of \fIdependency\fR 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.
|
|
.RE
|
|
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcompile_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Compile arguments to use.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[inc | str]\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
the directories to add to the string search path (i.e. `-J` switch for DMD).
|
|
Must be \fIinc\fR objects or plain strings.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIstr | int | list[str | int]\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Other dependencies needed to use this dependency.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
the directories to add to header search path,
|
|
must be \fIinc\fR objects or \fB(since 0.50.0)\fR plain strings.
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Link arguments to use.
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib]\fR, since 0.46.0
|
|
.br
|
|
.RS 2
|
|
Libraries to link fully, same as \fIexecutable\fR.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib]\fR
|
|
.br
|
|
.RS 2
|
|
Libraries to link against.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIlist[str | file | custom_tgt | custom_idx | generated_list]\fR
|
|
.br
|
|
.RS 2
|
|
sources to add to targets
|
|
(or generated header files
|
|
that should be built before sources including them are built)
|
|
.RE
|
|
|
|
\fBvariables\fR
|
|
\fIdict[str] | list[str]\fR, since 0.54.0
|
|
.br
|
|
.RS 2
|
|
a dictionary of arbitrary strings,
|
|
this is meant to be used
|
|
in subprojects where special variables would be provided via cmake or
|
|
pkg-config. \fBsince 0.56.0\fR it can also be a list of `'key=value'` strings.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
the version of this dependency,
|
|
such as `1.2.3`. Defaults to the project version.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dependency()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIdep\fR dependency(
|
|
.br
|
|
.RS 4
|
|
names...,
|
|
.br
|
|
allow_fallback:,
|
|
.br
|
|
default_options:,
|
|
.br
|
|
disabler: \fBfalse\fR,
|
|
.br
|
|
fallback:,
|
|
.br
|
|
include_type: \fB'preserve'\fR,
|
|
.br
|
|
language:,
|
|
.br
|
|
method: \fB'auto'\fR,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
not_found_message:,
|
|
.br
|
|
required: \fBtrue\fR,
|
|
.br
|
|
static: \fBfalse\fR,
|
|
.br
|
|
version:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Finds an external dependency (usually a library installed on your
|
|
system) with the given name with `pkg-config` and \fIwith
|
|
CMake\fR[12] if `pkg-config` fails. Additionally,
|
|
frameworks (OSX only) and \fIlibrary-specific fallback detection
|
|
logic\fR[13]
|
|
are also supported.
|
|
|
|
\fBSince 0.60.0\fR 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`.
|
|
|
|
\fB Since \fR0.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 \fI`subproject()`\fR had been called. The subproject can be specified with the `fallback` argument. Alternatively, if the `fallback` argument is absent, \fBsince 0.55.0\fR Meson can automatically identify a subproject as a fallback if a wrap file \fIprovides\fR[14] 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 \fIWrap documentation\fR[13] 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 \fIdep\fR also has additional methods.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBnames\fR
|
|
\fIstr\fR, 1...N times, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
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`.
|
|
|
|
\fB\fRNOTE:\fB\fR Before \fB0.60.0\fR only a single dependency name was allowed.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBallow_fallback\fR
|
|
\fIbool\fR, since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies whether Meson should automatically pick a fallback subproject
|
|
in case the dependency
|
|
is not found in the system. If `true` and the dependency is not found
|
|
on the system, Meson will fallback to a subproject that provides this
|
|
dependency. If `false`, Meson will not fallback even if a subproject
|
|
provides this dependency. By default, Meson will do so if `required`
|
|
is `true` or \fI`enabled`\fR[0]; see the \fIWrap
|
|
documentation\fR[13]
|
|
for more details.
|
|
.RE
|
|
|
|
\fBdefault_options\fR
|
|
\fIlist[str]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
An array of default option values
|
|
that override those set in the subproject's `meson_options.txt`
|
|
(like `default_options` in \fIproject\fR, they only have
|
|
effect when Meson is run for the first time, and command line
|
|
arguments override any default options in build files)
|
|
.RE
|
|
|
|
\fBdisabler\fR
|
|
\fIbool\fR, default: false, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Returns a \fIdisabler\fR object instead of a not-found dependency
|
|
if this kwarg is set to `true` and the dependency couldn't be found.
|
|
.RE
|
|
|
|
\fBfallback\fR
|
|
\fIlist[str] | str\fR
|
|
.br
|
|
.RS 2
|
|
Manually specifies a subproject fallback
|
|
to use in case the dependency is not found in the system.
|
|
This is useful if the automatic search is not applicable or if you
|
|
want to support versions of Meson older than 0.55.0. If the value is an
|
|
array `['subproj_name', 'subproj_dep']`, the first value is the name
|
|
of the subproject and the second is the variable name in that
|
|
subproject that contains a dependency object such as the return
|
|
value of \fIdeclare_dependency\fR or
|
|
\fIdependency\fR, 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.
|
|
\fBSince 0.54.0\fR the value can be a single string, the subproject name;
|
|
in this case the subproject must use
|
|
`meson.override_dependency('dependency_name', subproj_dep)`
|
|
to specify the dependency object used in the superproject.
|
|
If the value is an empty list, it has the same effect as
|
|
`allow_fallback: false`.
|
|
.RE
|
|
|
|
\fBinclude_type\fR
|
|
\fIstr\fR, default: 'preserve', since 0.52.0
|
|
.br
|
|
.RS 2
|
|
An enum flag, marking how the dependency
|
|
flags should be converted. Supported values are `'preserve'`, `'system'` and
|
|
`'non-system'`. System dependencies may be handled differently on some
|
|
platforms, for instance, using `-isystem` instead of `-I`, where possible.
|
|
If `include_type` is set to `'preserve'`, no additional conversion will be
|
|
performed.
|
|
.RE
|
|
|
|
\fBlanguage\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Defines what language-specific dependency to find
|
|
if it's available for multiple languages.
|
|
.RE
|
|
|
|
\fBmethod\fR
|
|
\fIstr\fR, default: 'auto', since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Defines the way the dependency is detected, the default is
|
|
`auto` but can be overridden to be e.g. `qmake` for Qt development,
|
|
and \fIdifferent dependencies support different values\fR[15]
|
|
for this (though `auto` will work on all of them)
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBnot_found_message\fR
|
|
\fIstr\fR, since 0.50.0
|
|
.br
|
|
.RS 2
|
|
An optional string that will be printed as a \fImessage\fR if the dependency was not found.
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: true
|
|
.br
|
|
.RS 2
|
|
When set to `false`, Meson will proceed with the build
|
|
even if the dependency is not found.
|
|
|
|
When set to a \fI`feature`\fR[0] option, the feature
|
|
will control if it is searched and whether to fail if not found.
|
|
|
|
\fB(since 0.47.0)\fR The value of a `feature` option can also be passed.
|
|
.RE
|
|
|
|
\fBstatic\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Tells the dependency provider to try to get static
|
|
libraries instead of dynamic ones (note that this is not supported
|
|
by all dependency backends)
|
|
|
|
\fBSince 0.60.0\fR it also sets `default_library` option accordingly on the fallback
|
|
subproject if it was not set explicitly in `default_options` keyword argument.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR, since 0.37.0
|
|
.br
|
|
.RS 2
|
|
Specifies the required version,
|
|
a string containing a
|
|
comparison operator followed by the version string, examples include
|
|
`>1.0.0`, `<=2.3.5` or `3.1.4` for exact matching.
|
|
You can also specify multiple restrictions by passing a list to this
|
|
keyword argument, such as: `['>=3.14.0', '<=4.1.0']`.
|
|
These requirements are never met if the version is unknown.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
This function supports additional \fIlibrary-specific\fR[12] keyword arguments that may also be accepted (e.g. `modules` specifies submodules to use for dependencies such as Qt5 or Boost. `components` allows the user to manually add CMake `COMPONENTS` for the `find_package` lookup)
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS disabler()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIdisabler\fR disabler()
|
|
|
|
since 0.44.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a \fIdisabler\fR object.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS environment()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIenv\fR environment([env], method:, separator:)
|
|
|
|
since 0.35.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an empty \fIenv\fR object.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBenv\fR
|
|
\fIstr | list[str] | dict[str] | dict[list[str]]\fR, since 0.52.0
|
|
.br
|
|
.RS 2
|
|
If provided, each key/value pair is added into the \fIenv\fR object
|
|
as if \fIenv.set\fR method was called for each of them.
|
|
Since \fB0.62.0\fR list of strings is allowed in dictionary values. In that
|
|
case values are joined using the separator.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBmethod\fR
|
|
\fIstr\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
Must be one of 'set', 'prepend', or 'append'
|
|
(defaults to 'set'). Controls if initial values defined in the first
|
|
positional argument are prepended, appended or replace the current value
|
|
of the environment variable.
|
|
.RE
|
|
|
|
\fBseparator\fR
|
|
\fIstr\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
The separator to use for the initial values defined in
|
|
the first positional argument. If not explicitly specified, the default
|
|
path separator for the host operating system will be used, i.e. ';' for
|
|
Windows and ':' for UNIX/POSIX systems.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS error()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR error(message, msg...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Print the argument string and halts the build process.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBmessage\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The message to print
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBmsg\fR
|
|
\fIstr\fR, 0...N times, since 0.58.0
|
|
.br
|
|
.RS 2
|
|
Additional parameters will be separated by spaces
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS executable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIexe\fR executable(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
export_dynamic:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implib:,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
pie:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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 \fIexe\fR.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBexport_dynamic\fR
|
|
\fIbool\fR, since 0.45.0
|
|
.br
|
|
.RS 2
|
|
when set to true causes the target's symbols to be
|
|
dynamically exported, allowing modules built using the
|
|
\fIshared_module\fR function to refer to functions,
|
|
variables and other symbols defined in the executable itself. Implies
|
|
the `implib` argument.
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[6] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplib\fR
|
|
\fIbool | str\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
When set to true, an import library is generated for the
|
|
executable (the name of the import library is based on \fBexe_name\fR).
|
|
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.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBpie\fR
|
|
\fIbool\fR, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Build a position-independent executable.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[7]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
\fBWARNINGS\fR
|
|
.RS 4
|
|
The `link_language` kwarg was broken until 0.55.0
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS files()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[file]\fR files(file...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
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.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBfile\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Path to the file.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
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:
|
|
.RS 4
|
|
foofile = files('foo.cpp')
|
|
.br
|
|
.RE
|
|
Then you can use it in `bar2` like this:
|
|
.RS 4
|
|
executable('myprog', 'myprog.cpp', foofile, ...)
|
|
.br
|
|
.RE
|
|
Meson will then do the right thing.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS find_program()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIexternal_program\fR find_program(
|
|
.br
|
|
.RS 4
|
|
program_name,
|
|
.br
|
|
fallback...,
|
|
.br
|
|
dirs:,
|
|
.br
|
|
disabler: \fBfalse\fR,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
required: \fBtrue\fR,
|
|
.br
|
|
version:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
`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 \fImeson.override_find_program\fR
|
|
1. \fI`[provide]` sections\fR[13]
|
|
in subproject wrap files, if \fI`wrap_mode`\fR[16] is
|
|
set to `forcefallback`
|
|
1. \fI`[binaries]` section\fR[17] in your machine files
|
|
1. Directories provided using the `dirs:` kwarg (see below)
|
|
1. Project's source tree relative to the current subdir
|
|
- If you use the return value of \fIconfigure_file\fR, the
|
|
current subdir inside the build tree is used instead
|
|
1. `PATH` environment variable
|
|
1. \fI`[provide]` sections\fR[13] in
|
|
subproject wrap files, if \fI`wrap_mode`\fR[15] 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 \fBmust not\fR manually add the interpreter while using this
|
|
script as part of a list of commands. Since \fB0.50.0\fR 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.
|
|
.RS 4
|
|
setcap = find_program('setcap', '/usr/sbin/setcap', '/sbin/setcap', required : false)
|
|
.br
|
|
.RE
|
|
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:
|
|
.RS 4
|
|
setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false)
|
|
.br
|
|
.RE
|
|
The returned \fIexternal_program\fR object also has documented methods.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBprogram_name\fR
|
|
\fIstr | file\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the program to search, or a \fIfile\fR object to be used
|
|
without searching.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBfallback\fR
|
|
\fIstr | file\fR, 0...N times, since 0.37.0
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdirs\fR
|
|
\fIlist[str]\fR, since 0.53.0
|
|
.br
|
|
.RS 2
|
|
extra list of absolute paths where to look for program names.
|
|
.RE
|
|
|
|
\fBdisabler\fR
|
|
\fIbool\fR, default: false, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
If `true` and the program couldn't be found, return a \fIdisabler\fR object
|
|
instead of a not-found object.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false, since 0.43.0
|
|
.br
|
|
.RS 2
|
|
Defines how this executable should be searched. By default
|
|
it is set to `false`, which causes Meson to first look for the
|
|
executable in the cross file (when cross building) and if it is not
|
|
defined there, then from the system. If set to `true`, the cross
|
|
file is ignored and the program is only searched from the system.
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: true
|
|
.br
|
|
.RS 2
|
|
When `true`, Meson will abort if no program can be found.
|
|
If `required` is set to `false`,
|
|
Meson continue even if none of the programs can be found. You can
|
|
then use the `.found()` method on the returned \fIexternal_program\fR to check
|
|
whether it was found or not. \fB(since 0.47.0)\fR The value of a
|
|
\fI`feature`\fR[0] option can also be passed to the
|
|
`required` keyword argument.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR, since 0.52.0
|
|
.br
|
|
.RS 2
|
|
specifies the required version, see
|
|
\fIdependency\fR for argument format. The version of the program
|
|
is determined by running `program_name --version` command. If stdout is empty
|
|
it fallbacks to stderr. If the output contains more text than simply a version
|
|
number, only the first occurrence of numbers separated by dots is kept.
|
|
If the output is more complicated than that, the version checking will have to
|
|
be done manually using \fIrun_command\fR.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS generator()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIgenerator\fR generator(
|
|
.br
|
|
.RS 4
|
|
exe,
|
|
.br
|
|
arguments:,
|
|
.br
|
|
capture: \fBfalse\fR,
|
|
.br
|
|
depends:,
|
|
.br
|
|
depfile:,
|
|
.br
|
|
output:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
See also: \fIcustom_target\fR
|
|
|
|
This function creates a \fIgenerator\fR 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)
|
|
.br
|
|
- `@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 \fBmust\fR 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
|
|
.br
|
|
- `@INPUT@`: the full path to the input file
|
|
.br
|
|
- `@DEPFILE@`: the full path to the depfile
|
|
.br
|
|
- `@SOURCE_DIR@`: the full path to the root of the source tree
|
|
.br
|
|
- `@CURRENT_SOURCE_DIR@`: this is the directory where the currently processed meson.build is located in
|
|
.br
|
|
- `@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 \fB\fR\fBonly\fR\fB\fR
|
|
be used as inputs for a \fIbuild_target\fR or a \fIcustom_target\fR.
|
|
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 \fIcustom_target\fR instead.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBexe\fR
|
|
\fIexe | external_program\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Executable for the command to run
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBarguments\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
A list of template strings that will be the command line arguments passed to the executable.
|
|
.RE
|
|
|
|
\fBcapture\fR
|
|
\fIbool\fR, default: false, since 0.43.0
|
|
.br
|
|
.RS 2
|
|
When this argument is set to true, Meson captures `stdout`
|
|
of the `executable` and writes it to the target file
|
|
specified as `output`.
|
|
.RE
|
|
|
|
\fBdepends\fR
|
|
\fIlist[build_tgt | custom_tgt]\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
An array of build targets that must be built before
|
|
this generator can be run. This is used if you have a generator that calls
|
|
a second executable that is built in this project.
|
|
.RE
|
|
|
|
\fBdepfile\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A template string pointing to a dependency file that a
|
|
generator 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,
|
|
.RE
|
|
|
|
\fBoutput\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Template string (or list of template strings) defining
|
|
how an output file name is (or multiple output names are) generated
|
|
from a single source file name.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS get_option()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr | int | bool | feature | list[str | int | bool]\fR get_option(
|
|
.br
|
|
.RS 4
|
|
option_name,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Obtains the value of the \fIproject build option\fR[18]
|
|
specified in the positional argument.
|
|
|
|
Note that the value returned for built-in options that end in `dir`
|
|
such as `bindir` and `libdir` is usually a path relative to (and
|
|
inside) the `prefix` but you should not rely on that, as it can also
|
|
be an absolute path \fIin some cases\fR[19].
|
|
\fI`install_dir` arguments\fR[20] handle that as expected
|
|
but if you need an absolute path, e.g. to use in a define etc.,
|
|
you should use the path concatenation operator like this:
|
|
`get_option('prefix') / get_option('localstatedir')`.
|
|
Never manually join paths as if they were strings.
|
|
|
|
For options of type `feature` a
|
|
\fIfeature\fR option object
|
|
is returned instead of a string.
|
|
See \fI`feature` options\fR[0]
|
|
documentation for more details.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBoption_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the option to query
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS get_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIany\fR get_variable(variable_name, [default])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This function can be used to dynamically obtain a variable. `res =
|
|
get_variable(varname, fallback)` takes the value of `varname` (which
|
|
must be a string) and stores the variable of that name into `res`. If
|
|
the variable does not exist, the variable `fallback` is stored to
|
|
`res`instead. If a fallback is not specified, then attempting to read
|
|
a non-existing variable will cause a fatal error.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvariable_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the variable to get
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBdefault\fR
|
|
\fIany\fR
|
|
.br
|
|
.RS 2
|
|
Fallback value to return when the variable does not exist
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS import()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fImodule\fR import(module_name, disabler:, required: \fBtrue\fR)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Imports the given extension module. Returns an object that can be used to call
|
|
the methods of the module. Here's an example for a hypothetical `testmod`
|
|
module.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBmodule_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the module to import.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdisabler\fR
|
|
\fIbool\fR, since 0.59.0
|
|
.br
|
|
.RS 2
|
|
Returns a \fIdisabler\fR object when not found.
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: true, since 0.59.0
|
|
.br
|
|
.RS 2
|
|
When set to `false`, Meson will proceed with the build even if the module is not found.
|
|
When set to a \fI`feature`\fR[0] option, the feature will control if it is searched and whether to fail if not found.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
tmod = import('testmod')
|
|
.br
|
|
tmod.do_something()
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS include_directories()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIinc\fR include_directories(includes..., is_system: \fBfalse\fR)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an opaque object which contains the directories (relative to
|
|
the current directory) given in the positional arguments. The result
|
|
can then be passed to the `include_directories:` keyword argument when
|
|
building executables or libraries. You can use the returned object in
|
|
any subdirectory you want, Meson will make the paths work
|
|
automatically.
|
|
|
|
Note that this function call itself does not add the directories into
|
|
the search path, since there is no global search path. For something
|
|
like that, see \fI`add_project_arguments()`\fR.
|
|
|
|
See also `implicit_include_directories` parameter of
|
|
\fIexecutable\fR, which adds current source and build
|
|
directories to include path.
|
|
|
|
Each directory given is converted to two include paths: one that is
|
|
relative to the source root and one relative to the build root.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBincludes\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Include paths to add.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBis_system\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
If set to `true`, flags the specified directories as system directories.
|
|
This means that
|
|
they will be used with the `-isystem` compiler argument rather than
|
|
`-I` on compilers that support this flag (in practice everything
|
|
except Visual Studio).
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
For example, with the following source tree layout in
|
|
`/home/user/project.git`:
|
|
|
|
`meson.build`:
|
|
.RS 4
|
|
project(...)
|
|
.br
|
|
|
|
.br
|
|
subdir('include')
|
|
.br
|
|
subdir('src')
|
|
.br
|
|
|
|
.br
|
|
\...
|
|
.br
|
|
.RE
|
|
`include/meson.build`:
|
|
.RS 4
|
|
inc = include_directories('.')
|
|
.br
|
|
|
|
.br
|
|
\...
|
|
.br
|
|
.RE
|
|
`src/meson.build`:
|
|
.RS 4
|
|
sources = [...]
|
|
.br
|
|
|
|
.br
|
|
executable('some-tool', sources,
|
|
.br
|
|
include_directories : inc,
|
|
.br
|
|
...)
|
|
.br
|
|
|
|
.br
|
|
\...
|
|
.br
|
|
.RE
|
|
If the build tree is `/tmp/build-tree`, the following include paths
|
|
will be added to the `executable()` call: `-I/tmp/build-tree/include
|
|
-I/home/user/project.git/include`.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS install_data()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR install_data(
|
|
.br
|
|
.RS 4
|
|
file...,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
preserve_path: \fBfalse\fR,
|
|
.br
|
|
rename:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Installs files from the source tree that are listed as positional arguments.
|
|
|
|
See \fIInstalling\fR[19] for more examples.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBfile\fR
|
|
\fIfile | str\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Files to install.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The absolute or relative path to the installation directory.
|
|
If this is a relative path, it is assumed to be relative to the prefix.
|
|
|
|
If omitted, the directory defaults to `{datadir}/{projectname}` \fB(since 0.45.0)\fR.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
specify the file mode in symbolic format and
|
|
optionally the owner/uid and group/gid for the installed files. For
|
|
example:
|
|
|
|
`install_mode: 'rw-r--r--'` for just the file mode
|
|
|
|
`install_mode: ['rw-r--r--', 'nobody', 'nogroup']` for the file mode and the user/group
|
|
|
|
`install_mode: ['rw-r-----', 0, 0]` for the file mode and uid/gid
|
|
|
|
To leave any of these three as the default, specify `false`.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default these files have no install
|
|
tag which means they are not being installed when `--tags` argument is specified.
|
|
.RE
|
|
|
|
\fBpreserve_path\fR
|
|
\fIbool\fR, default: false, since 0.64.0
|
|
.br
|
|
.RS 2
|
|
Disable stripping child-directories from data files when installing.
|
|
|
|
This is equivalent to GNU Automake's `nobase` option.
|
|
.RE
|
|
|
|
\fBrename\fR
|
|
\fIlist[str]\fR, since 0.46.0
|
|
.br
|
|
.RS 2
|
|
If specified renames each source file into corresponding file from `rename` list.
|
|
Nested paths are allowed and they are
|
|
joined with `install_dir`. Length of `rename` list must be equal to
|
|
the number of sources.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIlist[file | str]\fR
|
|
.br
|
|
.RS 2
|
|
Additional files to install.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS install_emptydir()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR install_emptydir(dirpath..., install_mode:, install_tag:)
|
|
|
|
since 0.60.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Installs a new directory entry to the location specified by the positional
|
|
argument. If the directory exists and is not empty, the contents are left in
|
|
place.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBdirpath\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Directory to create during installation.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format and optionally the owner/uid and
|
|
group/gid for the created directory.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command to install only a
|
|
subset of the files. By default this directory has no install tag which
|
|
means it is not installed when the `--tags` argument is specified.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS install_headers()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR install_headers(
|
|
.br
|
|
.RS 4
|
|
file...,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
preserve_path: \fBfalse\fR,
|
|
.br
|
|
subdir:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Installs the specified header files from the source tree into the
|
|
system header directory (usually `/{prefix}/include`) during the
|
|
install step. This directory can be overridden by specifying it with
|
|
the `install_dir` keyword argument. If you just want to install into a
|
|
subdirectory of the system header directory, then use the `subdir`
|
|
argument. As an example if this has the value `myproj` then the
|
|
headers would be installed to `/{prefix}/include/myproj`.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBfile\fR
|
|
\fIfile | str\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Header files to install.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Where to install to.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBpreserve_path\fR
|
|
\fIbool\fR, default: false, since 0.63.0
|
|
.br
|
|
.RS 2
|
|
Disable stripping child-direcories from header files when installing.
|
|
|
|
This is equivalent to GNU Automake's `nobase` option.
|
|
.RE
|
|
|
|
\fBsubdir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Install to the `subdir` subdirectory of the default includedir.
|
|
|
|
Incompatible with the `install_dir` kwarg.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
For example, this will install `common.h` and `kola.h` into
|
|
`/{prefix}/include`:
|
|
.RS 4
|
|
install_headers('common.h', 'proj/kola.h')
|
|
.br
|
|
.RE
|
|
This will install `common.h` and `kola.h` into `/{prefix}/include/myproj`:
|
|
.RS 4
|
|
install_headers('common.h', 'proj/kola.h', subdir : 'myproj')
|
|
.br
|
|
.RE
|
|
This will install `common.h` and `kola.h` into `/{prefix}/cust/myproj`:
|
|
.RS 4
|
|
install_headers('common.h', 'proj/kola.h', install_dir : 'cust', subdir : 'myproj')
|
|
.br
|
|
.RE
|
|
This will install `common.h` into `/{prefix}/include` and `kola.h`
|
|
into `/{prefix}/include/proj/`:
|
|
.RS 4
|
|
install_headers('common.h, 'proj/kola.h', preserve_path : true)
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS install_man()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR install_man(file..., install_dir:, install_mode:, locale:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Installs the specified man files from the source tree into system's man directory
|
|
during the install step. This directory can be
|
|
overridden by specifying it with the `install_dir` keyword argument.
|
|
|
|
\fB(since 0.49.0)\fR [manpages are no longer compressed implicitly][install_man_49].
|
|
|
|
[install_man_49]:
|
|
https://mesonbuild.com/Release-notes-for-0-49-0.html#manpages-are-no-longer-compressed-implicitly
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBfile\fR
|
|
\fIfile | str\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Man pages to install.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Where to install to.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBlocale\fR
|
|
\fIstr\fR, since 0.58.0
|
|
.br
|
|
.RS 2
|
|
Can be used to specify the locale
|
|
into which the
|
|
man page will be installed within the manual page directory tree.
|
|
An example manual might be `foo.fr.1` with a locale of `fr`, such
|
|
that `{mandir}/{locale}/man{num}/foo.1` becomes the installed file.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS install_subdir()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR install_subdir(
|
|
.br
|
|
.RS 4
|
|
subdir_name,
|
|
.br
|
|
exclude_directories:,
|
|
.br
|
|
exclude_files:,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
strip_directory: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Installs the entire given subdirectory and its contents from the
|
|
source tree to the location specified by the keyword argument
|
|
`install_dir`.
|
|
|
|
\fB(since 0.45.0, deprecated since 0.60.0)\fR If the subdirectory does not exist
|
|
in the source tree, an empty directory is created in the specified location.
|
|
A newly created subdirectory may only be created in the keyword argument
|
|
`install_dir`. There are a number of flaws with this method, and it was never
|
|
intentionally designed to work this way, please use \fIinstall_emptydir\fR
|
|
instead.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBsubdir_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The sub-directory to install
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBexclude_directories\fR
|
|
\fIlist[str]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
A list of directory names that should not be installed.
|
|
Names are interpreted as paths relative to the `subdir_name` location.
|
|
.RE
|
|
|
|
\fBexclude_files\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
A list of file names that should not be installed.
|
|
Names are interpreted as paths relative to the `subdir_name` location.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Where to install to.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default these files have no install
|
|
tag which means they are not being installed when `--tags` argument is specified.
|
|
.RE
|
|
|
|
\fBstrip_directory\fR
|
|
\fIbool\fR, default: false, since 0.45.0
|
|
.br
|
|
.RS 2
|
|
Install directory contents.
|
|
If `strip_directory=true` only the last component of the source path is used.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
For a given directory `foo`:
|
|
.RS 4
|
|
text
|
|
.br
|
|
foo/
|
|
.br
|
|
bar/
|
|
.br
|
|
file1
|
|
.br
|
|
file2
|
|
.br
|
|
.RE
|
|
`install_subdir('foo', install_dir : 'share', strip_directory : false)` creates
|
|
.RS 4
|
|
text
|
|
.br
|
|
share/
|
|
.br
|
|
foo/
|
|
.br
|
|
bar/
|
|
.br
|
|
file1
|
|
.br
|
|
file2
|
|
.br
|
|
.RE
|
|
`install_subdir('foo', install_dir : 'share', strip_directory : true)` creates
|
|
.RS 4
|
|
text
|
|
.br
|
|
share/
|
|
.br
|
|
bar/
|
|
.br
|
|
file1
|
|
.br
|
|
file2
|
|
.br
|
|
.RE
|
|
`install_subdir('foo/bar', install_dir : 'share', strip_directory : false)` creates
|
|
.RS 4
|
|
text
|
|
.br
|
|
share/
|
|
.br
|
|
bar/
|
|
.br
|
|
file1
|
|
.br
|
|
.RE
|
|
`install_subdir('foo/bar', install_dir : 'share', strip_directory : true)` creates
|
|
.RS 4
|
|
text
|
|
.br
|
|
share/
|
|
.br
|
|
file1
|
|
.br
|
|
.RE
|
|
`install_subdir('new_directory', install_dir : 'share')` creates
|
|
.RS 4
|
|
text
|
|
.br
|
|
share/
|
|
.br
|
|
new_directory/
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS install_symlink()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR install_symlink(
|
|
.br
|
|
.RS 4
|
|
link_name,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
pointing_to:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.61.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Installs a symbolic link to `pointing_to` target under install_dir.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBlink_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the created link under `install_dir`.
|
|
It cannot contain path separators. Those should go in `install_dir`.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The absolute or relative path to the installation directory for the links.
|
|
If this is a relative path, it is assumed to be relative to the prefix.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default these files have no install
|
|
tag which means they are not being installed when `--tags` argument is specified.
|
|
.RE
|
|
|
|
\fBpointing_to\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Target to point the link to.
|
|
Can be absolute or relative and that will be respected when creating the link.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS is_disabler()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR is_disabler(var)
|
|
|
|
since 0.52.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if a variable is a disabler and false otherwise.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvar\fR
|
|
\fIany\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The variable to test
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS is_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR is_variable(var)
|
|
|
|
since 0.52.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if a variable of the given name exists and false otherwise.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvar\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The variable to test
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS jar()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIjar\fR jar(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
java_resources:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
main_class:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Build a jar from the specified Java source files. Keyword arguments
|
|
are the same as \fIexecutable\fR's, with the addition of
|
|
`main_class` which specifies the main class to execute when running
|
|
the jar with `java -jar file.jar`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[6] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBjava_resources\fR
|
|
\fIstructured_src\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
Resources to be added to the jar
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBmain_class\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Main class for running the built jar
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[7]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS join_paths()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR join_paths(part...)
|
|
|
|
since 0.36.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Joins the given strings into a file system path segment. For example
|
|
`join_paths('foo', 'bar')` results in `foo/bar`. If any one of the
|
|
individual segments is an absolute path, all segments before it are
|
|
dropped. That means that `join_paths('foo', '/bar')` returns `/bar`.
|
|
|
|
\fB(since 0.49.0)\fR Using the `/` operator on strings is equivalent to calling
|
|
\fIjoin_paths\fR.
|
|
.RS 4
|
|
# res1 and res2 will have identical values
|
|
.br
|
|
res1 = join_paths(foo, bar)
|
|
.br
|
|
res2 = foo / bar
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBpart\fR
|
|
\fIstr\fR, 1...N times
|
|
.br
|
|
.RS 2
|
|
The path parts to join.
|
|
.RE
|
|
|
|
.RE
|
|
\fBWARNINGS\fR
|
|
.RS 4
|
|
Don't use \fIjoin_paths\fR for sources in \fIlibrary\fR and \fIexecutable\fR. You should use \fIfiles\fR instead.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS library()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlib\fR library(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
darwin_versions:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
pic:,
|
|
.br
|
|
prelink:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
soversion:,
|
|
.br
|
|
version:,
|
|
.br
|
|
vs_module_defs:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Builds a library that is either static, shared or both depending on
|
|
the value of `default_library`
|
|
user \fIoption\fR[21].
|
|
You should use this instead of \fIshared_library\fR,
|
|
\fIstatic_library\fR or
|
|
\fIboth_libraries\fR most of the time. This allows you
|
|
to toggle your entire project (including subprojects) from shared to
|
|
static with only one option. This option applies to libraries being
|
|
built internal to the entire project. For external dependencies, the
|
|
default library type preferred is shared. This can be adapted on a per
|
|
library basis using the \fIdependency\fR `static` keyword.
|
|
|
|
The keyword arguments for this are the same as for
|
|
\fIbuild_target\fR
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdarwin_versions\fR
|
|
\fIstr | int | list[str]\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Defines the `compatibility version` and `current version` for the dylib on macOS.
|
|
If a list is specified, it must be
|
|
either zero, one, or two elements. If only one element is specified
|
|
or if it's not a list, the specified value will be used for setting
|
|
both compatibility version and current version. If unspecified, the
|
|
`soversion` will be used as per the aforementioned rules.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[6] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBpic\fR
|
|
\fIbool\fR, since 0.36.0
|
|
.br
|
|
.RS 2
|
|
Builds the library as positional independent code
|
|
(so it can be linked into a shared library). This
|
|
option has no effect on Windows and OS X since it doesn't make
|
|
sense on Windows and PIC cannot be disabled on OS X.
|
|
.RE
|
|
|
|
\fBprelink\fR
|
|
\fIbool\fR, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
If `true` the object files in the target will be prelinked,
|
|
meaning that it will contain only one prelinked
|
|
object file rather than the individual object files.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBsoversion\fR
|
|
\fIstr | int\fR
|
|
.br
|
|
.RS 2
|
|
A string or integer specifying the soversion of this shared library,
|
|
such as `0`. On Linux and Windows this is used to set the
|
|
soversion (or equivalent) in the filename. For example, if
|
|
`soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one
|
|
of the aliases of the Linux shared library would be
|
|
`libfoo.so.4`. If this is not specified, the first part of `version`
|
|
is used instead (see below). For example, if `version` is `3.6.0` and
|
|
`soversion` is not defined, it is set to `3`.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string specifying the version of this shared library,
|
|
such as `1.1.0`. On Linux and OS X, this is used to set the shared
|
|
library version in the filename, such as `libfoo.so.1.1.0` and
|
|
`libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used
|
|
instead (see above).
|
|
.RE
|
|
|
|
\fBvs_module_defs\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Specify a Microsoft module definition file for controlling symbol exports,
|
|
etc., on platforms where that is possible (e.g. Windows).
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[7]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS message()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR message(text, more_text...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This function prints its argument to stdout.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtext\fR
|
|
\fIstr | int | bool | list[str | int | bool] | dict[str | int | bool]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The message to print.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBmore_text\fR
|
|
\fIstr | int | bool | list[str | int | bool] | dict[str | int | bool]\fR, 0...N times, since 0.54.0
|
|
.br
|
|
.RS 2
|
|
Additional text that will be printed separated by spaces.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS project()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR project(
|
|
.br
|
|
.RS 4
|
|
project_name,
|
|
.br
|
|
language...,
|
|
.br
|
|
default_options:,
|
|
.br
|
|
license:,
|
|
.br
|
|
meson_version:,
|
|
.br
|
|
subproject_dir: \fB'subprojects'\fR,
|
|
.br
|
|
version:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
The first function called in each project, to initialize Meson.
|
|
|
|
The first argument to this function must be a string defining the name
|
|
of this project.
|
|
|
|
The project name can be any string you want, it's not used for
|
|
anything except descriptive purposes. However since it is written to
|
|
e.g. the dependency manifest is usually makes sense to have it be the
|
|
same as the project tarball or pkg-config name. So for example you
|
|
would probably want to use the name _libfoobar_ instead of _The Foobar
|
|
Library_.
|
|
|
|
It may be followed by the list of programming languages that the project uses.
|
|
|
|
\fB(since 0.40.0)\fR The list of languages is optional.
|
|
|
|
These languages may be used both for `native: false` (the default)
|
|
(host machine) targets and for `native: true` (build machine) targets.
|
|
\fB(since 0.56.0)\fR The build machine compilers for the specified
|
|
languages are not required.
|
|
|
|
Supported values for languages are `c`, `cpp` (for `C++`), `cuda`, `d`,
|
|
`objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), `vala` and `rust`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBproject_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the project.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBlanguage\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The languages that Meson should initialize.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdefault_options\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Accecpts strings in the form `key=value`
|
|
which have the same format as options to `meson configure`.
|
|
For example to set the default project type you would
|
|
set this: `default_options : ['buildtype=debugoptimized']`. Note
|
|
that these settings are only used when running Meson for the first
|
|
time. Global options such as `buildtype` can only be specified in
|
|
the master project, settings in subprojects are ignored. Project
|
|
specific options are used normally even in subprojects.
|
|
.RE
|
|
|
|
\fBlicense\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Takes a string or array of strings describing the license(s) the code is under.
|
|
|
|
This \fBshould\fR be an \fISPDX license expression\fR[22],
|
|
using the standardized license identifier from the \fISPDX license
|
|
list\fR[23]. Usually this would be something like
|
|
`license : 'GPL-2.0-or-later'`. If there are multiple licenses you can use the
|
|
`AND` and `OR` operators to join them: `license : 'Apache-2.0 OR GPL-2.0'`.
|
|
|
|
For backwards compatibility reasons you can also pass an array of
|
|
licenses here. This is not recommended, as it is ambiguous: `license :
|
|
['Apache-2.0', 'GPL-2.0-only']` instead use an SPDX espression: `license
|
|
: 'Apache-2.0 OR GPL-2.0-only'`, which makes it clear that the license
|
|
mean OR, not AND.
|
|
|
|
Note that the text is informal and is only written to the dependency
|
|
manifest. Meson does not do any license validation, you are responsible
|
|
for verifying that you abide by all licensing terms. You can access the
|
|
value in your Meson build files with `meson.project_license()`.
|
|
.RE
|
|
|
|
\fBmeson_version\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Takes a string describing which Meson version the project requires.
|
|
Usually something like `>=0.28.0`.
|
|
.RE
|
|
|
|
\fBsubproject_dir\fR
|
|
\fIstr\fR, default: 'subprojects'
|
|
.br
|
|
.RS 2
|
|
Specifies the top level directory name that holds Meson subprojects.
|
|
This is only meant as a compatibility option
|
|
for existing code bases that house their embedded source code in a
|
|
custom directory. All new projects should not set this but instead
|
|
use the default value. It should be noted that this keyword
|
|
argument is ignored inside subprojects. There can be only one
|
|
subproject dir and it is set in the top level Meson file.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr | file\fR
|
|
.br
|
|
.RS 2
|
|
A free form string describing the version of this project.
|
|
You can access the value in your Meson build files
|
|
with \fImeson.project_version\fR. \fB(Since 0.57.0)\fR this can also be a
|
|
\fIfile\fR object pointing to a file that contains exactly one line of
|
|
text.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS range()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIrange\fR range([start], [stop], [step])
|
|
|
|
since 0.58.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Return an opaque object that can be only be used in `foreach` statements.
|
|
|
|
<pre><code class="language-meson">\fIrange\fR range(\fIint\fR <b>stop</b>)
|
|
\fIrange\fR range(\fIint\fR <b>start</b>, \fIint\fR <b>stop</b>[, \fIint\fR <b>step</b>])</code></pre>
|
|
|
|
- `start` must be integer greater or equal to 0. Defaults to 0.
|
|
.br
|
|
- `stop` must be integer greater or equal to `start`.
|
|
.br
|
|
- `step` must be integer greater or equal to 1. Defaults to 1.
|
|
|
|
It cause the `foreach` loop to be called with the value from `start` included
|
|
to `stop` excluded with an increment of `step` after each loop.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBstart\fR
|
|
\fIint\fR, default: 0
|
|
.br
|
|
.RS 2
|
|
The start of the range
|
|
.RE
|
|
|
|
\fBstop\fR
|
|
\fIint\fR
|
|
.br
|
|
.RS 2
|
|
The end of the range
|
|
.RE
|
|
|
|
\fBstep\fR
|
|
\fIint\fR, default: 1
|
|
.br
|
|
.RS 2
|
|
The loop increment
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
# Loop 15 times with i from 0 to 14 included.
|
|
.br
|
|
foreach i : range(15)
|
|
.br
|
|
...
|
|
.br
|
|
endforeach
|
|
.br
|
|
.RE
|
|
The range object can also be assigned to a variable and indexed.
|
|
.RS 4
|
|
r = range(5, 10, 2)
|
|
.br
|
|
assert(r[2] == 9)
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS run_command()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIrunresult\fR run_command(
|
|
.br
|
|
.RS 4
|
|
command...,
|
|
.br
|
|
capture: \fBtrue\fR,
|
|
.br
|
|
check: \fBfalse\fR,
|
|
.br
|
|
env:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Runs the command specified in positional arguments. `command` can be a
|
|
string, or the output of \fIfind_program\fR,
|
|
\fIfiles\fR or \fIconfigure_file\fR, or \fIa
|
|
compiler object\fR.
|
|
|
|
Returns a \fIrunresult\fR object containing the result
|
|
of the invocation. The command is run from an \fBunspecified\fR directory,
|
|
and Meson will set three environment variables `MESON_SOURCE_ROOT`,
|
|
`MESON_BUILD_ROOT` and `MESON_SUBDIR` that specify the source
|
|
directory, build directory and subdirectory the target was defined in,
|
|
respectively.
|
|
|
|
See also \fIExternal commands\fR[24].
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBcommand\fR
|
|
\fIstr | file | external_program\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The command to execute during the setup process.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcapture\fR
|
|
\fIbool\fR, default: true, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
If `true`, any output generated on stdout will be captured and returned by
|
|
the `.stdout()` method. If it is false, then `.stdout()` will return an
|
|
empty string.
|
|
.RE
|
|
|
|
\fBcheck\fR
|
|
\fIbool\fR, default: false, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
If `true`, the exit status code of the command will be checked,
|
|
and the configuration will fail if it is non-zero. Note that
|
|
the default value will be `true` in future releases.
|
|
.RE
|
|
|
|
\fBenv\fR
|
|
\fIenv | list[str] | dict[str]\fR, since 0.50.0
|
|
.br
|
|
.RS 2
|
|
environment variables to set,
|
|
such as `['NAME1=value1', 'NAME2=value2']`,
|
|
or an \fIenv\fR object which allows more sophisticated
|
|
environment juggling. \fB(Since 0.52.0)\fR A dictionary is also accepted.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS run_target()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIrun_tgt\fR run_target(target_name, command:, depends:, env:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This function creates a new top-level target that runs a specified
|
|
command with the specified arguments. Like all top-level targets, this
|
|
integrates with the selected backend. For instance, you can run it as
|
|
`meson compile target_name`. Note that a run target produces no output
|
|
as far as Meson is concerned. It is only meant for tasks such as
|
|
running a code formatter or flashing an external device's firmware
|
|
with a built file.
|
|
|
|
The command is run from an \fBunspecified\fR directory, and Meson will set
|
|
three environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT`
|
|
and `MESON_SUBDIR` that specify the source directory, build directory
|
|
and subdirectory the target was defined in, respectively.
|
|
|
|
\fBSince 0.57.0\fR The template strings passed to `command` keyword arguments accept
|
|
the following special substitutions:
|
|
- `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend, this may be an absolute or a relative to current workdir path.
|
|
.br
|
|
- `@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.
|
|
.br
|
|
- `@CURRENT_SOURCE_DIR@` \fBSince 0.57.1\fR: 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.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the run target
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcommand\fR
|
|
\fIlist[exe| external_program | custom_tgt | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
A list containing the command to run and the arguments
|
|
to pass to it. Each list item may be a string or a target. For
|
|
instance, passing the return value of \fIexecutable\fR
|
|
as the first item will run that executable, or passing a string as
|
|
the first item will find that command in `PATH` and run it.
|
|
.RE
|
|
|
|
\fBdepends\fR
|
|
\fIlist[build_tgt | custom_tgt]\fR
|
|
.br
|
|
.RS 2
|
|
A list of targets that this target depends on but which
|
|
are not listed in the command array (because, for example, the
|
|
script does file globbing internally)
|
|
.RE
|
|
|
|
\fBenv\fR
|
|
\fIenv | list[str] | dict[str]\fR, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
environment variables to set, such as
|
|
`{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`,
|
|
or an \fIenv\fR object which allows more sophisticated environment juggling.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS set_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR set_variable(variable_name, value)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Assigns a value to the given variable name. Calling
|
|
`set_variable('foo', bar)` is equivalent to `foo = bar`.
|
|
|
|
\fB(since 0.46.1)\fR The `value` parameter can be an array type.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvariable_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to set
|
|
.RE
|
|
|
|
\fBvalue\fR
|
|
\fIany\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The value to set the variable to
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS shared_library()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlib\fR shared_library(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
darwin_versions:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
soversion:,
|
|
.br
|
|
version:,
|
|
.br
|
|
vs_module_defs:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Builds a shared library with the given sources.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdarwin_versions\fR
|
|
\fIstr | int | list[str]\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Defines the `compatibility version` and `current version` for the dylib on macOS.
|
|
If a list is specified, it must be
|
|
either zero, one, or two elements. If only one element is specified
|
|
or if it's not a list, the specified value will be used for setting
|
|
both compatibility version and current version. If unspecified, the
|
|
`soversion` will be used as per the aforementioned rules.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[6] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBsoversion\fR
|
|
\fIstr | int\fR
|
|
.br
|
|
.RS 2
|
|
A string or integer specifying the soversion of this shared library,
|
|
such as `0`. On Linux and Windows this is used to set the
|
|
soversion (or equivalent) in the filename. For example, if
|
|
`soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one
|
|
of the aliases of the Linux shared library would be
|
|
`libfoo.so.4`. If this is not specified, the first part of `version`
|
|
is used instead (see below). For example, if `version` is `3.6.0` and
|
|
`soversion` is not defined, it is set to `3`.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string specifying the version of this shared library,
|
|
such as `1.1.0`. On Linux and OS X, this is used to set the shared
|
|
library version in the filename, such as `libfoo.so.1.1.0` and
|
|
`libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used
|
|
instead (see above).
|
|
.RE
|
|
|
|
\fBvs_module_defs\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Specify a Microsoft module definition file for controlling symbol exports,
|
|
etc., on platforms where that is possible (e.g. Windows).
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[7]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS shared_module()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbuild_tgt\fR shared_module(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
vs_module_defs:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.37.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Builds a shared module with the given sources.
|
|
|
|
This is useful for building modules that will be `dlopen()`ed and
|
|
hence may contain undefined symbols that will be provided by the
|
|
library that is loading it.
|
|
|
|
If you want the shared module to be able to refer to functions and
|
|
variables defined in the \fIexecutable\fR it is loaded by,
|
|
you will need to set the `export_dynamic` argument of the executable to
|
|
`true`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[6] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBvs_module_defs\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR, since 0.52.0
|
|
.br
|
|
.RS 2
|
|
Specify a Microsoft module definition file for controlling symbol exports,
|
|
etc., on platforms where that is possible (e.g. Windows).
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[7]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
*Linking to a shared module on platforms other than Android is deprecated, and will be an error
|
|
in the future*.
|
|
It was previously allowed because it was the only way to have a shared-library-like target that
|
|
contained references to undefined symbols. However, since 0.40.0, the `override_options:`
|
|
\fIbuild_target\fR keyword argument can be used to create such a \fIshared_library\fR by passing
|
|
`override_options: 'b_lundef=false'`. Shared modules have other characteristics that make
|
|
them incompatible with linking, such as a lack of SONAME.
|
|
On macOS and iOS, linking to shared modules is disallowed by the linker, so we disallow it at
|
|
configure time.
|
|
On Android, if a shared module `foo` uses symbols from another shared module `bar`, `foo` must
|
|
also be linked to `bar`. Hence, linking one shared module to another will always be allowed when
|
|
building for Android.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS static_library()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlib\fR static_library(
|
|
.br
|
|
.RS 4
|
|
target_name,
|
|
.br
|
|
source...,
|
|
.br
|
|
<lang>_args:,
|
|
.br
|
|
<lang>_pch:,
|
|
.br
|
|
build_by_default: \fBtrue\fR,
|
|
.br
|
|
build_rpath:,
|
|
.br
|
|
d_debug:,
|
|
.br
|
|
d_import_dirs:,
|
|
.br
|
|
d_module_versions:,
|
|
.br
|
|
d_unittest: \fBfalse\fR,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
extra_files:,
|
|
.br
|
|
gnu_symbol_visibility:,
|
|
.br
|
|
gui_app: \fBfalse\fR,
|
|
.br
|
|
implicit_include_directories: \fBtrue\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
install: \fBfalse\fR,
|
|
.br
|
|
install_dir:,
|
|
.br
|
|
install_mode:,
|
|
.br
|
|
install_rpath:,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
link_args:,
|
|
.br
|
|
link_depends:,
|
|
.br
|
|
link_language:,
|
|
.br
|
|
link_whole:,
|
|
.br
|
|
link_with:,
|
|
.br
|
|
name_prefix:,
|
|
.br
|
|
name_suffix:,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
objects:,
|
|
.br
|
|
override_options:,
|
|
.br
|
|
pic:,
|
|
.br
|
|
prelink:,
|
|
.br
|
|
rust_crate_type:,
|
|
.br
|
|
sources:,
|
|
.br
|
|
win_subsystem: \fB'console'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Builds a static library with the given sources.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtarget_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR name of the build target
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fB<lang>_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
compiler flags to use for the given language;
|
|
eg: `cpp_args` for C++
|
|
.RE
|
|
|
|
\fB<lang>_pch\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
precompiled header file to use for the given language
|
|
.RE
|
|
|
|
\fBbuild_by_default\fR
|
|
\fIbool\fR, default: true, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Causes, when set to `true`, to have this target be built by default.
|
|
This means it will be built when `meson compile` is called without any
|
|
arguments. The default value is `true` for all built target types.
|
|
.RE
|
|
|
|
\fBbuild_rpath\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
A string to add to target's rpath definition in the build dir,
|
|
but which will be removed on install
|
|
.RE
|
|
|
|
\fBd_debug\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
The \fID version identifiers\fR[5] to add
|
|
during the compilation of D source files.
|
|
.RE
|
|
|
|
\fBd_import_dirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
List of directories to look in for string imports used in the D programming language.
|
|
.RE
|
|
|
|
\fBd_module_versions\fR
|
|
\fIlist[str | int]\fR
|
|
.br
|
|
.RS 2
|
|
List of module version identifiers set when compiling D sources.
|
|
.RE
|
|
|
|
\fBd_unittest\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, the D modules are compiled in debug mode.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIlist[dep]\fR
|
|
.br
|
|
.RS 2
|
|
one or more dependency objects
|
|
created with
|
|
\fIdependency\fR or \fIcompiler.find_library\fR
|
|
(for external deps) or \fIdeclare_dependency\fR
|
|
(for deps built by the project)
|
|
.RE
|
|
|
|
\fBextra_files\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
Not used for the build itself but are shown as source files in IDEs
|
|
that group files by targets (such as Visual Studio)
|
|
.RE
|
|
|
|
\fBgnu_symbol_visibility\fR
|
|
\fIstr\fR, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Specifies how symbols should be exported, see
|
|
e.g \fIthe GCC Wiki\fR[6] for more
|
|
information. This value can either be an empty string or one of
|
|
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which
|
|
is the same as `hidden` but also includes things like C++ implicit
|
|
constructors as specified in the GCC manual. Ignored on compilers that
|
|
do not support GNU visibility arguments.
|
|
.RE
|
|
|
|
\fBgui_app\fR
|
|
\fIbool\fR, default: false, \fBdeprecated\fR since 0.56.0
|
|
.br
|
|
.RS 2
|
|
When set to true flags this target as a GUI application
|
|
on platforms where this makes a differerence, \fB\fRdeprecated\fB\fR since
|
|
0.56.0, use `win_subsystem` instead.
|
|
.RE
|
|
|
|
\fBimplicit_include_directories\fR
|
|
\fIbool\fR, default: true, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Controls whether Meson adds the current source and build directories to the include path
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIlist[inc | str]\fR
|
|
.br
|
|
.RS 2
|
|
one or more objects created with the \fIinclude_directories\fR function,
|
|
or \fB(since 0.50.0)\fR strings, which will be transparently expanded to include directory objects
|
|
.RE
|
|
|
|
\fBinstall\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to true, this executable should be installed.
|
|
.RE
|
|
|
|
\fBinstall_dir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
override install directory for this file. If the value is a relative path,
|
|
it will be considered relative the `prefix` option.
|
|
For example, if you want to install plugins into a subdir, you'd use
|
|
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
|
|
.RE
|
|
|
|
\fBinstall_mode\fR
|
|
\fIlist[str | int]\fR, since 0.47.0
|
|
.br
|
|
.RS 2
|
|
Specify the file mode in symbolic format
|
|
and optionally the owner/uid and group/gid for the installed files.
|
|
|
|
See the `install_mode` kwarg of \fIinstall_data\fR for more information.
|
|
.RE
|
|
|
|
\fBinstall_rpath\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
A string to set the target's rpath to after install
|
|
(but \fBnot\fR before that). On Windows, this argument has no effect.
|
|
.RE
|
|
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files. By default all build targets have the
|
|
tag `runtime` except for static libraries that have the `devel` tag.
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Flags to use during linking. You can use UNIX-style
|
|
flags here for all platforms.
|
|
.RE
|
|
|
|
\fBlink_depends\fR
|
|
\fIstr | file | custom_tgt | custom_idx\fR
|
|
.br
|
|
.RS 2
|
|
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.
|
|
.RE
|
|
|
|
\fBlink_language\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
Makes the linker for this target be for the specified language.
|
|
It is generally unnecessary to set
|
|
this, as Meson will detect the right linker to use in most cases. There are
|
|
only two cases where this is needed. One, your main function in an
|
|
executable is not in the language Meson picked, or second you want to force
|
|
a library to use only one ABI.
|
|
|
|
\fB(broken until 0.55.0)\fR
|
|
.RE
|
|
|
|
\fBlink_whole\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
Links all contents of the given static libraries
|
|
whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC.
|
|
|
|
\fB(since 0.41.0)\fR If passed a list that list will be flattened.
|
|
|
|
\fB(since 0.51.0)\fR This argument also accepts outputs produced by
|
|
custom targets. The user must ensure that the output is a library in
|
|
the correct format.
|
|
.RE
|
|
|
|
\fBlink_with\fR
|
|
\fIlist[lib | custom_tgt | custom_idx]\fR
|
|
.br
|
|
.RS 2
|
|
One or more shared or static libraries
|
|
(built by this project) that this target should be linked with. \fB(since 0.41.0)\fR If passed a
|
|
list this list will be flattened. \fB(since 0.51.0)\fR 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.
|
|
.RE
|
|
|
|
\fBname_prefix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the prefix for the
|
|
target output filename by overriding the default (only used for
|
|
libraries). By default this is `lib` on all platforms and compilers,
|
|
except for MSVC shared libraries where it is omitted to follow
|
|
convention, and Cygwin shared libraries where it is `cyg`.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBname_suffix\fR
|
|
\fIstr | list[void]\fR
|
|
.br
|
|
.RS 2
|
|
The string that will be used as the extension for the
|
|
target by overriding the default. By default on Windows this is
|
|
`exe` for executables and on other platforms it is omitted.
|
|
|
|
For shared libraries, the default value
|
|
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else.
|
|
For static libraries, it is `a` everywhere. By convention MSVC
|
|
static libraries use the `lib` suffix, but we use `a` to avoid a
|
|
potential name clash with shared libraries which also generate
|
|
import libraries with a `lib` suffix.
|
|
|
|
Set this to `[]`, or omit the keyword argument for the default behaviour.
|
|
.RE
|
|
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Controls whether the target is compiled for the build or host machines.
|
|
.RE
|
|
|
|
\fBobjects\fR
|
|
\fIlist[extracted_obj | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
List of object files that should be linked in this target.
|
|
These can include third party products you don't have source to,
|
|
or object files produced by other build targets.
|
|
.RE
|
|
|
|
\fBoverride_options\fR
|
|
\fIlist[str]\fR, since 0.40.0
|
|
.br
|
|
.RS 2
|
|
takes an array of strings in the same format as `project`'s `default_options`
|
|
overriding the values of these options
|
|
for this target only.
|
|
.RE
|
|
|
|
\fBpic\fR
|
|
\fIbool\fR, since 0.36.0
|
|
.br
|
|
.RS 2
|
|
Builds the library as positional independent code
|
|
(so it can be linked into a shared library). This
|
|
option has no effect on Windows and OS X since it doesn't make
|
|
sense on Windows and PIC cannot be disabled on OS X.
|
|
.RE
|
|
|
|
\fBprelink\fR
|
|
\fIbool\fR, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
If `true` the object files in the target will be prelinked,
|
|
meaning that it will contain only one prelinked
|
|
object file rather than the individual object files.
|
|
.RE
|
|
|
|
\fBrust_crate_type\fR
|
|
\fIstr\fR, since 0.42.0
|
|
.br
|
|
.RS 2
|
|
Set the specific type of rust crate to compile (when compiling rust).
|
|
|
|
If the target is an \fIexecutable\fR this defaults to "bin", the only
|
|
allowed value.
|
|
|
|
If it is a \fIstatic_library\fR it defaults to "lib", and may be "lib",
|
|
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib"
|
|
means a C ABI library, "rlib" means a Rust ABI.
|
|
|
|
If it is a \fIshared_library\fR it defaults to "lib", and may be "lib",
|
|
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a
|
|
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and
|
|
"proc-macro" is a special rust proceedural macro crate.
|
|
|
|
"proc-macro" is new in 0.62.0.
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list | structured_src\fR
|
|
.br
|
|
.RS 2
|
|
Additional source files. Same as the source varargs.
|
|
.RE
|
|
|
|
\fBwin_subsystem\fR
|
|
\fIstr\fR, default: 'console', since 0.56.0
|
|
.br
|
|
.RS 2
|
|
Specifies the subsystem type to use
|
|
on the Windows platform. Typical values include `console` for text
|
|
mode programs and `windows` for gui apps. The value can also contain
|
|
version specification such as `windows,6.0`. See \fIMSDN
|
|
documentation\fR[7]
|
|
for the full list.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS structured_sources()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstructured_src\fR structured_sources(root, [additional])
|
|
|
|
since 0.62.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Create a StructuredSource object, which is opaque and may be passed as a source
|
|
to any build_target (including static_library, shared_library, executable,
|
|
etc.). This is useful for languages like Rust, which use the filesystem layout
|
|
to determine import names. This is only allowed in Rust targets, and cannot be
|
|
mixed with non structured inputs.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBroot\fR
|
|
\fIlist[str | file | custom_tgt | custom_idx | generated_list]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Sources to put at the root of the generated structure
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBadditional\fR
|
|
\fIdict[str | file | custom_tgt | custom_idx | generated_list]\fR
|
|
.br
|
|
.RS 2
|
|
Additional sources, where the key is the directory under the root to place
|
|
the values
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS subdir()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR subdir(dir_name, if_found:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Enters the specified subdirectory and executes the `meson.build` file in it.
|
|
Once that is done, it returns and execution continues on the
|
|
line following this `subdir()` command. Variables defined in that
|
|
`meson.build` file are then available for use in later parts of the
|
|
current build file and in all subsequent build files executed with
|
|
`subdir()`.
|
|
|
|
Note that this means that each `meson.build` file in a source tree can
|
|
and must only be executed once.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBdir_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Directory relative to the current `meson.build` to enter.
|
|
|
|
Cannot contain `..`
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBif_found\fR
|
|
\fIlist[dep]\fR, since 0.44.0
|
|
.br
|
|
.RS 2
|
|
Only enter the subdir if all \fIdep.found\fR methods return `true`.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS subdir_done()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR subdir_done()
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Stops further interpretation of the Meson script file from the point
|
|
of the invocation. All steps executed up to this point are valid and
|
|
will be executed by Meson. This means that all targets defined before
|
|
the call of \fIsubdir_done\fR will be build.
|
|
|
|
If the current script was called by `subdir` the execution returns to
|
|
the calling directory and continues as if the script had reached the
|
|
end. If the current script is the top level script Meson configures
|
|
the project as defined up to this point.
|
|
.RE
|
|
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
project('example exit', 'cpp')
|
|
.br
|
|
executable('exe1', 'exe1.cpp')
|
|
.br
|
|
subdir_done()
|
|
.br
|
|
executable('exe2', 'exe2.cpp')
|
|
.br
|
|
.RE
|
|
The executable `exe1` will be build, while the executable `exe2` is not
|
|
build.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS subproject()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIsubproject\fR subproject(
|
|
.br
|
|
.RS 4
|
|
subproject_name,
|
|
.br
|
|
default_options:,
|
|
.br
|
|
required: \fBtrue\fR,
|
|
.br
|
|
version:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Takes the project specified in the positional argument and brings that
|
|
in the current build specification by returning a \fIsubproject\fR object.
|
|
Subprojects must always be placed inside
|
|
the `subprojects` directory at the top source directory. So for
|
|
example a subproject called `foo` must be located in
|
|
`${MESON_SOURCE_ROOT}/subprojects/foo`.
|
|
|
|
- `default_options` \fB(since 0.37.0)\fR: an array of default option values that override those set in the subproject's `meson_options.txt` (like `default_options` in `project`, they only have effect when Meson is run for the first time, and command line arguments override any default options in build files). \fB(since 0.54.0)\fR: `default_library` built-in option can also be overridden.
|
|
.br
|
|
- `version`: works just like the same as in `dependency`. It specifies what version the subproject should be, as an example `>=1.0.1`
|
|
.br
|
|
- `required` \fB(since 0.48.0)\fR: By default, `required` is `true` and Meson will abort if the subproject could not be setup. You can set this to `false` and then use the `.found()` method on the \fIsubproject\fR object. You may also pass the value of a \fI`feature`\fR[0] option, same as \fIdependency\fR.
|
|
|
|
Note that you can use the returned \fIsubproject\fR object
|
|
to access any variable in the
|
|
subproject. However, if you want to use a dependency object from
|
|
inside a subproject, an easier way is to use the `fallback:` keyword
|
|
argument to \fIdependency\fR.
|
|
|
|
\fISee additional documentation\fR[25].
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBsubproject_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the subproject. The subproject must exist in the `subprojects`
|
|
directory (or the directory specified in the `subproject_dir` of
|
|
\fIproject\fR) as a directory or wrap file.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdefault_options\fR
|
|
\fIlist[str]\fR, since 0.37.0
|
|
.br
|
|
.RS 2
|
|
An array of default option values
|
|
that override those set in the subproject's `meson_options.txt`
|
|
(like `default_options` in \fIproject\fR, they only have effect when
|
|
Meson is run for the first time, and command line arguments override
|
|
any default options in build files). \fB(since 0.54.0)\fR: `default_library`
|
|
built-in option can also be overridden.
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: true, since 0.48.0
|
|
.br
|
|
.RS 2
|
|
Works just the same as in \fIdependency\fR.
|
|
.RE
|
|
|
|
\fBversion\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Works just like the same as in \fIdependency\fR.
|
|
It specifies what version the subproject should be, as an example `>=1.0.1`.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS summary()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR summary(
|
|
.br
|
|
.RS 4
|
|
key_or_dict,
|
|
.br
|
|
[value],
|
|
.br
|
|
bool_yn: \fBfalse\fR,
|
|
.br
|
|
list_sep:,
|
|
.br
|
|
section:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.53.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This function is used to summarize build configuration at the end of the build
|
|
process. This function provides a way for projects (and subprojects) to report
|
|
this information in a clear way.
|
|
|
|
The content is a series of key/value pairs grouped into sections. If
|
|
the section keyword argument is omitted, those key/value pairs are
|
|
implicitly grouped into a section with no title. key/value pairs can
|
|
optionally be grouped into a dictionary, but keep in mind that
|
|
dictionaries do not guarantee ordering. `key` must be string,
|
|
`value` can be:
|
|
|
|
- an integer, boolean or string
|
|
.br
|
|
- \fBsince 0.57.0\fR an external program or a dependency
|
|
.br
|
|
- \fBsince 0.58.0\fR a feature option
|
|
.br
|
|
- a list of those.
|
|
|
|
Instead of calling summary as `summary(key, value)`, it is also possible to
|
|
directly pass a dictionary to the \fIsummary\fR function, as seen in the example
|
|
below.
|
|
|
|
`summary()` can be called multiple times as long as the same
|
|
section/key pair doesn't appear twice. All sections will be collected
|
|
and printed at the end of the configuration in the same order as they
|
|
have been called.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBkey_or_dict\fR
|
|
\fIstr | dict[str | bool | int | dep | external_program | list[str | bool | int | dep | external_program]]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the new entry, or a dict containing multiple entries. If a
|
|
dict is passed it is equivalent to calling summary() once for each
|
|
key-value pair. Keep in mind that dictionaries do not guarantee
|
|
ordering.
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBvalue\fR
|
|
\fIstr | bool | int | dep | external_program | list[str | bool | int | dep | external_program]\fR
|
|
.br
|
|
.RS 2
|
|
The value to print for the `key`. Only valid if `key_or_dict` is a str.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBbool_yn\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Convert bool values to yes and no
|
|
.RE
|
|
|
|
\fBlist_sep\fR
|
|
\fIstr\fR, since 0.54.0
|
|
.br
|
|
.RS 2
|
|
The separator to use when printing list values in this summary. If no
|
|
separator is given, each list item will be printed on its own line.
|
|
.RE
|
|
|
|
\fBsection\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The section to put this summary information under. If the section keyword argument is omitted, key/value pairs are implicitly grouped into a section with no title.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
Example `meson.build`:
|
|
.RS 4
|
|
project('My Project', version : '1.0')
|
|
.br
|
|
summary({'bindir': get_option('bindir'),
|
|
.br
|
|
'libdir': get_option('libdir'),
|
|
.br
|
|
'datadir': get_option('datadir'),
|
|
.br
|
|
}, section: 'Directories')
|
|
.br
|
|
summary({'Some boolean': false,
|
|
.br
|
|
'Another boolean': true,
|
|
.br
|
|
'Some string': 'Hello World',
|
|
.br
|
|
'A list': ['string', 1, true],
|
|
.br
|
|
}, section: 'Configuration')
|
|
.br
|
|
.RE
|
|
Output:
|
|
.RS 4
|
|
My Project 1.0
|
|
.br
|
|
|
|
.br
|
|
Directories
|
|
.br
|
|
prefix : /opt/gnome
|
|
.br
|
|
bindir : bin
|
|
.br
|
|
libdir : lib/x86_64-linux-gnu
|
|
.br
|
|
datadir : share
|
|
.br
|
|
|
|
.br
|
|
Configuration
|
|
.br
|
|
Some boolean : False
|
|
.br
|
|
Another boolean: True
|
|
.br
|
|
Some string : Hello World
|
|
.br
|
|
A list : string
|
|
.br
|
|
1
|
|
.br
|
|
True
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS test()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR test(
|
|
.br
|
|
.RS 4
|
|
name,
|
|
.br
|
|
executable,
|
|
.br
|
|
args:,
|
|
.br
|
|
depends:,
|
|
.br
|
|
env:,
|
|
.br
|
|
is_parallel: \fBtrue\fR,
|
|
.br
|
|
priority: \fB0\fR,
|
|
.br
|
|
protocol: \fB'exitcode'\fR,
|
|
.br
|
|
should_fail: \fBfalse\fR,
|
|
.br
|
|
suite:,
|
|
.br
|
|
timeout: \fB30\fR,
|
|
.br
|
|
verbose: \fBfalse\fR,
|
|
.br
|
|
workdir:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Defines a test to run with the test harness. Takes two positional
|
|
arguments, the first is the name of the test and the second is the
|
|
executable to run. The executable can be an \fIexe\fR object returned by
|
|
\fIexecutable\fR or an \fIexternal_program\fR object] returned by
|
|
\fIfind_program\fR.
|
|
|
|
\fB(since 0.55.0)\fR When cross compiling, if an exe_wrapper is needed and
|
|
defined the environment variable `MESON_EXE_WRAPPER` will be set to
|
|
the string value of that wrapper (implementation detail: using
|
|
`mesonlib.join_args`). Test scripts may use this to run cross built
|
|
binaries. If your test needs `MESON_EXE_WRAPPER` in cross build
|
|
situations it is your responsibility to return code 77 to tell the
|
|
harness to report "skip".
|
|
|
|
By default, environment variable
|
|
\fI`MALLOC_PERTURB_`\fR[26]
|
|
is automatically set by `meson test` to a random value between 1..255.
|
|
This can help find memory leaks on configurations using glibc,
|
|
including with non-GCC compilers. However, this can have a performance
|
|
impact, and may fail a test due to external libraries whose internals
|
|
are out of the user's control. To check if this feature is causing an
|
|
expected runtime crash, disable the feature by temporarily setting
|
|
environment variable `MALLOC_PERTURB_=0`. While it's preferable to
|
|
only temporarily disable this check, if a project requires permanent
|
|
disabling of this check in meson.build do like:
|
|
.RS 4
|
|
nomalloc = environment({'MALLOC_PERTURB_': '0'})
|
|
.br
|
|
|
|
.br
|
|
test(..., env: nomalloc, ...)
|
|
.br
|
|
.RE
|
|
In addition to running individual executables as test cases, `test()`
|
|
can also be used to invoke an external test harness. In this case,
|
|
it is best to use `verbose: true` \fB(since 0.62.0)\fR and, if supported
|
|
by the external harness, `protocol: 'tap'` \fB(since 0.50.0)\fR. This will
|
|
ensure that Meson logs each subtest as it runs, instead of including
|
|
the whole log at the end of the run.
|
|
|
|
Defined tests can be run in a backend-agnostic way by calling
|
|
`meson test` inside the build dir, or by using backend-specific
|
|
commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fBunique\fR test id
|
|
.RE
|
|
|
|
\fBexecutable\fR
|
|
\fIexe | jar | external_program | file\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The program to execute
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str | file | tgt]\fR
|
|
.br
|
|
.RS 2
|
|
Arguments to pass to the executable
|
|
.RE
|
|
|
|
\fBdepends\fR
|
|
\fIlist[build_tgt | custom_tgt]\fR, since 0.46.0
|
|
.br
|
|
.RS 2
|
|
specifies that this test depends on the specified
|
|
target(s), even though it does not take any of them as a command
|
|
line argument. This is meant for cases where test finds those
|
|
targets internally, e.g. plugins or globbing. Those targets are built
|
|
before test is executed even if they have `build_by_default : false`.
|
|
.RE
|
|
|
|
\fBenv\fR
|
|
\fIenv | list[str] | dict[str]\fR
|
|
.br
|
|
.RS 2
|
|
environment variables to set, such as `['NAME1=value1',
|
|
\'NAME2=value2']`, or an \fIenv\fR object which allows more sophisticated
|
|
environment juggling. \fB(Since 0.52.0)\fR A dictionary is also accepted.
|
|
.RE
|
|
|
|
\fBis_parallel\fR
|
|
\fIbool\fR, default: true
|
|
.br
|
|
.RS 2
|
|
when false, specifies that no other test must be
|
|
running at the same time as this test
|
|
.RE
|
|
|
|
\fBpriority\fR
|
|
\fIint\fR, default: 0, since 0.52.0
|
|
.br
|
|
.RS 2
|
|
specifies the priority of a test. Tests with a
|
|
higher priority are \fBstarted\fR before tests with a lower priority.
|
|
The starting order of tests with identical priorities is
|
|
implementation-defined. The default priority is 0, negative numbers are
|
|
permitted.
|
|
.RE
|
|
|
|
\fBprotocol\fR
|
|
\fIstr\fR, default: 'exitcode', since 0.50.0
|
|
.br
|
|
.RS 2
|
|
specifies how the test results are parsed and can
|
|
be one of `exitcode`, `tap`, or `gtest`. For more information about test
|
|
harness protocol read \fIUnit Tests\fR[1]. The following values are
|
|
accepted:
|
|
|
|
- `exitcode`: the executable's exit code is used by the test harness to record the outcome of the test).
|
|
.br
|
|
- `tap`: \fITest Anything Protocol\fR[2].
|
|
.br
|
|
- `gtest` \fB(since 0.55.0)\fR: for Google Tests.
|
|
.br
|
|
- `rust` \fB(since 0.56.0)\fR: for native rust tests
|
|
.RE
|
|
|
|
\fBshould_fail\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
when true the test is considered passed if the
|
|
executable returns a non-zero return value (i.e. reports an error)
|
|
.RE
|
|
|
|
\fBsuite\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
`'label'` (or list of labels `['label1', 'label2']`)
|
|
attached to this test. The suite name is qualified by a (sub)project
|
|
name resulting in `(sub)project_name:label`. In the case of a list
|
|
of strings, the suite names will be `(sub)project_name:label1`,
|
|
`(sub)project_name:label2`, etc.
|
|
.RE
|
|
|
|
\fBtimeout\fR
|
|
\fIint\fR, default: 30
|
|
.br
|
|
.RS 2
|
|
the amount of seconds the test is allowed to run, a test
|
|
that exceeds its time limit is always considered failed, defaults to
|
|
30 seconds. \fBSince 0.57\fR if timeout is `<= 0` the test has infinite duration,
|
|
in previous versions of Meson the test would fail with a timeout immediately.
|
|
.RE
|
|
|
|
\fBverbose\fR
|
|
\fIbool\fR, default: false, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
if true, forces the test results to be logged as if `--verbose` was passed
|
|
to `meson test`.
|
|
.RE
|
|
|
|
\fBworkdir\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
absolute path that will be used as the working directory
|
|
for the test
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS unset_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR unset_variable(varname)
|
|
|
|
since 0.60.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Unsets a variable.
|
|
Referencing a variable which has been unset is an error until it has been set again.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The variable to unset.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS vcs_tag()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIcustom_tgt\fR vcs_tag(
|
|
.br
|
|
.RS 4
|
|
command:,
|
|
.br
|
|
fallback: \fB[[meson.project_version]]\fR,
|
|
.br
|
|
input:,
|
|
.br
|
|
output:,
|
|
.br
|
|
replace_string: \fB'@VCS_TAG@'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This command detects revision control commit information at build time
|
|
and places it in the specified output file. This file is guaranteed to
|
|
be up to date on every build. Keywords are similar to \fIcustom_target\fR.
|
|
|
|
Meson will read the contents of `input`, substitute the
|
|
`replace_string` with the detected revision number, and write the
|
|
result to `output`. This method returns a
|
|
\fIcustom_tgt\fR object that (as usual) should be
|
|
used to signal dependencies if other targets use the file outputted
|
|
by this.
|
|
|
|
For example, if you generate a header with this and want to use that
|
|
in a build target, you must add the return value to the sources of
|
|
that build target. Without that, Meson will not know the order in
|
|
which to build the targets.
|
|
|
|
If you desire more specific behavior than what this command provides,
|
|
you should use \fIcustom_target\fR.
|
|
.RE
|
|
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcommand\fR
|
|
\fIlist[exe | external_program | custom_tgt | file | str]\fR
|
|
.br
|
|
.RS 2
|
|
The command to execute, see \fIcustom_target\fR for details
|
|
on how this command must be specified.
|
|
|
|
This parameter is optional. If it is absent, Meson will try
|
|
its best to find a suitable default command.
|
|
|
|
\fB(since 0.62.0)\fR \fIfile\fR is accepted.
|
|
|
|
\fB(since 0.63.0)\fR \fIcustom_tgt\fR, \fIexe\fR, and \fIexternal_program\fR are accepted.
|
|
.RE
|
|
|
|
\fBfallback\fR
|
|
\fIstr\fR, default: [[meson.project_version]]
|
|
.br
|
|
.RS 2
|
|
Version number to use when no revision control information is present,
|
|
such as when building from a release tarball.
|
|
.RE
|
|
|
|
\fBinput\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
File to modify (e.g. `version.c.in`).
|
|
.RE
|
|
|
|
\fBoutput\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
File to write the results to (e.g. `version.c`).
|
|
.RE
|
|
|
|
\fBreplace_string\fR
|
|
\fIstr\fR, default: '@VCS_TAG@'
|
|
.br
|
|
.RS 2
|
|
String in the input file to substitute with the commit information.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS warning()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR warning(text, more_text...)
|
|
|
|
since 0.44.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
This function prints its argument to stdout prefixed with WARNING:.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtext\fR
|
|
\fIstr | int | bool | list[str | int | bool] | dict[str | int | bool]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The message to print.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBmore_text\fR
|
|
\fIstr | int | bool | list[str | int | bool] | dict[str | int | bool]\fR, 0...N times, since 0.54.0
|
|
.br
|
|
.RS 2
|
|
Additional text that will be printed separated by spaces.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS bool.to_int()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIint\fR bool.to_int()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `1` if `true` and `0` if `false`
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS bool.to_string()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR bool.to_string([true_str], [false_str])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the string `'true'` if the boolean is true or `'false'` otherwise.
|
|
You can also pass it two strings as positional
|
|
arguments to specify what to return for true/false. For instance,
|
|
`bool.to_string('yes', 'no')` will return `yes` if the boolean is
|
|
true and `no` if it is false.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBtrue_str\fR
|
|
\fIstr\fR, default: 'true'
|
|
.br
|
|
.RS 2
|
|
The string to return when the boolean is `true`
|
|
.RE
|
|
|
|
\fBfalse_str\fR
|
|
\fIstr\fR, default: 'false'
|
|
.br
|
|
.RS 2
|
|
The string to return when the boolean is `false`
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS both_libs.get_shared_lib()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlib\fR both_libs.get_shared_lib()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the stored shared library
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS both_libs.get_static_lib()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlib\fR both_libs.get_static_lib()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the stored static library
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_machine.cpu()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR build_machine.cpu()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a more specific CPU name, such as `i686`, `amd64`, etc.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_machine.cpu_family()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR build_machine.cpu_family()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the CPU family name.
|
|
\fIThis table\fR[27] contains
|
|
all known CPU families. These are guaranteed to continue working.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_machine.endian()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR build_machine.endian()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
returns `'big'` on big-endian systems and `'little'` on little-endian systems.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_machine.system()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR build_machine.system()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the operating system name.
|
|
\fIThis table\fR[28] Lists
|
|
all of the currently known Operating System names, these are
|
|
guaranteed to continue working.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_tgt.extract_all_objects()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIextracted_obj\fR build_tgt.extract_all_objects(
|
|
.br
|
|
.RS 4
|
|
recursive: \fBtrue\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Acts the same as `extract_objects`, but returns all object files generated
|
|
by this target.
|
|
|
|
By default only objects built for this target are returned to maintain
|
|
backward compatibility with previous versions. The default value for the
|
|
`recursive` kwarg will eventually be changed to `true` in a future version.
|
|
.RE
|
|
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBrecursive\fR
|
|
\fIbool\fR, default: true, since 0.46.0
|
|
.br
|
|
.RS 2
|
|
Also return objects passed to the `objects` argument of this target.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS build_tgt.extract_objects()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIextracted_obj\fR build_tgt.extract_objects(source...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an opaque value representing the object files generated for those
|
|
source files. This is typically used to take single object files and link
|
|
them to unit tests or to compile some source files with custom flags. To
|
|
use the object file(s) in another build target, use the
|
|
`objects:` keyword argument to a \fIbuild_target\fR or include them in the command
|
|
line of a \fIcustom_target\fR.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file\fR, 1...N times
|
|
.br
|
|
.RS 2
|
|
Source filenames for which the built objects should be extracted.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS build_tgt.found()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR build_tgt.found()
|
|
|
|
since 0.59.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Always returns `true`. This function is meant to make executables
|
|
objects feature compatible with \fIexternal_program\fR objects. This
|
|
simplifies use-cases where an executable is used instead of
|
|
an \fIexternal_program\fR.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_tgt.full_path()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR build_tgt.full_path()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a full path pointing to the result target file.
|
|
\fB\fRNOTE:\fB\fR In most cases using the object itself will do the same job
|
|
as this and will also allow Meson to setup inter-target dependencies
|
|
correctly. Please file a bug if that doesn't work for you.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_tgt.name()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR build_tgt.name()
|
|
|
|
since 0.54.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the name of the target.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_tgt.path()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR build_tgt.path()
|
|
|
|
\fBdeprecated\fR since 0.59.0, since 0.59.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Does the exact same as \fIbuild_tgt.full_path\fR. \fB\fRNOTE\fB\fR: This
|
|
function is solely kept for compatebility with \fIexternal_program\fR objects.
|
|
It will be removed once the, also deprecated, corresponding `path()`
|
|
function in the \fIexternal_program\fR object is removed.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS build_tgt.private_dir_include()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIinc\fR build_tgt.private_dir_include()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a value that works like \fIinclude_directories\fR, but points to the
|
|
private directory of this target. Usually only needed if an another target
|
|
needs to access some generated internal headers of this target.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS cfg_data.get()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr | int | bool\fR cfg_data.get(varname, [default_value])
|
|
|
|
since 0.38.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the value of `varname`, if the
|
|
value has not been set returns `default_value` if it is defined
|
|
\fB(since 0.38.0)\fR and errors out if not
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to query
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBdefault_value\fR
|
|
\fIstr | int | bool\fR
|
|
.br
|
|
.RS 2
|
|
The default value to return when `varname` does not exist
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS cfg_data.get_unquoted()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr | int | bool\fR cfg_data.get_unquoted(varname, [default_value])
|
|
|
|
since 0.44.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the value
|
|
of `varname` but without surrounding double quotes (`"`). If the value has
|
|
not been set returns `default_value` if it is defined and errors out if not.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to query
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBdefault_value\fR
|
|
\fIstr | int | bool\fR
|
|
.br
|
|
.RS 2
|
|
The default value to return when `varname` does not exist
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS cfg_data.has()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR cfg_data.has(varname)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
returns `true` if the specified variable is set
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to query
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS cfg_data.keys()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR cfg_data.keys()
|
|
|
|
since 0.57.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an array of keys of
|
|
the configuration data object.
|
|
|
|
You can iterate over this array with the \fI`foreach`
|
|
statement\fR[29].
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS cfg_data.merge_from()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR cfg_data.merge_from(other)
|
|
|
|
since 0.42.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Takes as argument a different
|
|
configuration data object and copies all entries from that object to
|
|
the current.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBother\fR
|
|
\fIcfg_data\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The other \fIcfg_data\fR object to merge into this one.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS cfg_data.set()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR cfg_data.set(varname, value, description:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Sets a variable to a given value
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to set
|
|
.RE
|
|
|
|
\fBvalue\fR
|
|
\fIstr | int | bool\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The value to set
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdescription\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Message / Comment that will be written in the
|
|
result file. The replacement assumes a file with C syntax. If your
|
|
generated file is source code in some other language, you probably
|
|
don't want to add a description field because it most likely will
|
|
cause a syntax error.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS cfg_data.set10()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR cfg_data.set10(varname, value, description:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Is the same as \fIcfg_data.set\fR but the value
|
|
is either `true` or `false` and will be written as 1 or 0,
|
|
respectively
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to set
|
|
.RE
|
|
|
|
\fBvalue\fR
|
|
\fIbool | int\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The value to set as either `1` or `0`
|
|
|
|
Passing numbers was never intended to work, and since 0.62 it has been
|
|
deprecated. It will be removed in a future version of Meson. If you
|
|
need to pass numbers use the `.set` method.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdescription\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Message / Comment that will be written in the
|
|
result file. The replacement assumes a file with C syntax. If your
|
|
generated file is source code in some other language, you probably
|
|
don't want to add a description field because it most likely will
|
|
cause a syntax error.
|
|
.RE
|
|
|
|
.RE
|
|
\fBWARNINGS\fR
|
|
.RS 4
|
|
numeric values < 0 have the surprising behavior of being converted to `true`, values > 1 have the more expected but unintentional behavior of being interpreted as `true`.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS cfg_data.set_quoted()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR cfg_data.set_quoted(varname, value, description:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Is same as \fIcfg_data.set\fR but quotes the value in double quotes (`"`)
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to set
|
|
.RE
|
|
|
|
\fBvalue\fR
|
|
\fIstr | int | bool\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The value to set
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdescription\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Message / Comment that will be written in the
|
|
result file. The replacement assumes a file with C syntax. If your
|
|
generated file is source code in some other language, you probably
|
|
don't want to add a description field because it most likely will
|
|
cause a syntax error.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS cmake.subproject_options()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIcmake_options\fR cmake.subproject_options()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an empty `cmake_options` object.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS cmake_options.add_cmake_defines()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR cmake_options.add_cmake_defines(defines...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Add CMake defines (`-D<VAR>=<VAL>`) to the CMake commandline
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBdefines\fR
|
|
\fIdict[str]\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
A `key` `value` map of CMake defines to add (`-D<key>=<val>`)
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.alignment()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIint\fR compiler.alignment(typename, args:, dependencies:, prefix:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the alignment of the specified type.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtypename\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the type to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.check_header()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.check_header(
|
|
.br
|
|
.RS 4
|
|
header_name,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
required: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.47.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the specified header is \fBusable\fR
|
|
with the specified prefix, dependencies, and arguments.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBheader_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The header to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: false, since 0.50.0
|
|
.br
|
|
.RS 2
|
|
When set to `true`, Meson will halt if the header check fails.
|
|
When set to a \fI`feature`\fR[0] option, the feature will control if it is searched and whether to fail if not found.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.cmd_array()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR compiler.cmd_array()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an array containing the command(s) for the compiler.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS compiler.compiles()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.compiles(
|
|
.br
|
|
.RS 4
|
|
code,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
name:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the code compiles.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBcode\fR
|
|
\fIstr | file\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The source code to check.
|
|
|
|
If a string is passed, the code is used directly. If a \fIfile\fR object
|
|
is passed, its content is used for the compiler check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBname\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The name to use for printing a message about the compiler check.
|
|
If this keyword argument is not passed, no message will be printed about the check.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.compute_int()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIint\fR compiler.compute_int(
|
|
.br
|
|
.RS 4
|
|
expr,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
guess:,
|
|
.br
|
|
high: \fB1024\fR,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
low: \fB-1024\fR,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.40.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Computes the value of the given expression
|
|
(as an example `1 + 2`). When cross compiling this is evaluated with
|
|
an iterative algorithm, you can specify keyword arguments `low`
|
|
(defaults to -1024), `high` (defaults to 1024) and `guess` to
|
|
specify max and min values for the search and the value to try
|
|
first.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBexpr\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The expression to compute.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBguess\fR
|
|
\fIint\fR
|
|
.br
|
|
.RS 2
|
|
The value to try first.
|
|
.RE
|
|
|
|
\fBhigh\fR
|
|
\fIint\fR, default: 1024
|
|
.br
|
|
.RS 2
|
|
The max value.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBlow\fR
|
|
\fIint\fR, default: -1024
|
|
.br
|
|
.RS 2
|
|
The min value.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.find_library()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIdep\fR compiler.find_library(
|
|
.br
|
|
.RS 4
|
|
libname,
|
|
.br
|
|
dirs:,
|
|
.br
|
|
disabler: \fBfalse\fR,
|
|
.br
|
|
has_headers:,
|
|
.br
|
|
header_args:,
|
|
.br
|
|
header_dependencies:,
|
|
.br
|
|
header_include_directories:,
|
|
.br
|
|
header_no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
header_prefix:,
|
|
.br
|
|
required: \fBtrue\fR,
|
|
.br
|
|
static: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Tries to find the library specified in the positional argument.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBlibname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The library to find.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdirs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Additional directories to search in.
|
|
|
|
By default the library is searched for in the system library directory
|
|
(e.g. /usr/lib). Specifying more directories here, causes Meson to search
|
|
in those directories as well as the system directories.
|
|
.RE
|
|
|
|
\fBdisabler\fR
|
|
\fIbool\fR, default: false, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
If `true`, this method will return a \fIdisabler\fR on a failed check.
|
|
.RE
|
|
|
|
\fBhas_headers\fR
|
|
\fIlist[str]\fR, since 0.50.0
|
|
.br
|
|
.RS 2
|
|
List of headers that must be found as well.
|
|
This check is equivalent to checking each header with a
|
|
\fIcompiler.has_header\fR call.
|
|
|
|
When used, kwargs that \fIcompiler.has_header\fR would accept can be
|
|
passed here prefixed with `header_`, and will have the same effect on
|
|
the header check.
|
|
.RE
|
|
|
|
\fBheader_args\fR
|
|
\fIlist[str]\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
When the `has_headers` kwarg is also used, this argument is passed to
|
|
\fIcompiler.has_header\fR as `args`.
|
|
.RE
|
|
|
|
\fBheader_dependencies\fR
|
|
\fIdep | list[dep]\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
When the `has_headers` kwarg is also used, this argument is passed to
|
|
\fIcompiler.has_header\fR as `dependencies`.
|
|
.RE
|
|
|
|
\fBheader_include_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
When the `has_headers` kwarg is also used, this argument is passed to
|
|
\fIcompiler.has_header\fR as `include_directories`.
|
|
.RE
|
|
|
|
\fBheader_no_builtin_args\fR
|
|
\fIbool\fR, default: false, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
When the `has_headers` kwarg is also used, this argument is passed to
|
|
\fIcompiler.has_header\fR as `no_builtin_args`.
|
|
.RE
|
|
|
|
\fBheader_prefix\fR
|
|
\fIstr\fR, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
When the `has_headers` kwarg is also used, this argument is passed to
|
|
\fIcompiler.has_header\fR as `prefix`.
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: true
|
|
.br
|
|
.RS 2
|
|
If set `true`, Meson will abort with an error if the library could not
|
|
be found. Otherwise, Meson will continue and the found method of the
|
|
returned object will return `false`.
|
|
|
|
When set to a \fI`feature`\fR[0] option, the feature
|
|
will control if it is searched and whether to fail if not found.
|
|
|
|
\fB(since 0.47.0)\fR The value of a `feature` option can also be passed here.
|
|
.RE
|
|
|
|
\fBstatic\fR
|
|
\fIbool\fR, default: false, since 0.51.0
|
|
.br
|
|
.RS 2
|
|
If `true`, the search is limited to static libraries only.
|
|
Setting this value to `false` (the default) will search for both shared
|
|
\fBand\fR static libraries.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.first_supported_argument()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR compiler.first_supported_argument(arg...)
|
|
|
|
since 0.43.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Given a list of strings, returns a single-element list containing the first
|
|
argument that passes the \fIcompiler.has_argument\fR test or an empty array if
|
|
none pass.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The arguments to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.first_supported_link_argument()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR compiler.first_supported_link_argument(arg...)
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Given a list of strings, returns the first argument that passes the
|
|
\fIcompiler.has_link_argument\fR test or an empty array if none pass.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The link arguments to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.get_argument_syntax()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR compiler.get_argument_syntax()
|
|
|
|
since 0.49.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
returns a string identifying the type of arguments the compiler takes.
|
|
Can be one of `gcc`, `msvc`, or an undefined
|
|
string value. This method is useful for identifying compilers that are not
|
|
gcc or msvc, but use the same argument syntax as one of those two compilers
|
|
such as clang or icc, especially when they use different syntax on different
|
|
operating systems.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS compiler.get_define()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR compiler.get_define(
|
|
.br
|
|
.RS 4
|
|
definename,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.40.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the given preprocessor symbol's value
|
|
as a string or empty string if it is not defined.
|
|
|
|
\fB(since 0.47.0)\fR This method will concatenate string literals as
|
|
the compiler would. E.g. `"a" "b"` will become `"ab"`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBdefinename\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The define to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.get_id()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR compiler.get_id()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string identifying the compiler.
|
|
For example, `gcc`, `msvc`, \fIand more\fR[30].
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS compiler.get_linker_id()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR compiler.get_linker_id()
|
|
|
|
since 0.53.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string identifying the linker.
|
|
For example, `ld.bfd`, `link`, \fIand more\fR[31].
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS compiler.get_supported_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR compiler.get_supported_arguments(
|
|
.br
|
|
.RS 4
|
|
arg...,
|
|
.br
|
|
checked: \fB'off'\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.43.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an array containing only the arguments supported by the compiler,
|
|
as if \fIcompiler.has_argument\fR were called on them individually.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The arguments to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBchecked\fR
|
|
\fIstr\fR, default: 'off', since 0.59.0
|
|
.br
|
|
.RS 2
|
|
Supported values:
|
|
- `'off'`: Quietely ignore unsupported arguments
|
|
- `'warn'`: Print a warning for unsupported arguments
|
|
- `'require'`: Abort if at least one argument is not supported
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.get_supported_function_attributes()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR compiler.get_supported_function_attributes()
|
|
|
|
since 0.48.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an array containing any names that are supported GCC style attributes.
|
|
Equivalent to \fIcompiler.has_function_attribute\fR was called on each of
|
|
them individually.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS compiler.get_supported_link_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR compiler.get_supported_link_arguments(arg...)
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an array containing only the arguments supported by the compiler,
|
|
as if \fIcompiler.has_link_argument\fR were called on them individually.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The link arguments to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_argument()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_argument(argument)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the compiler accepts the specified command line argument,
|
|
that is, can compile code without erroring out or printing a warning about
|
|
an unknown flag.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBargument\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The argument to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_function()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_function(
|
|
.br
|
|
.RS 4
|
|
funcname,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the given function is provided
|
|
by the standard library or a library passed in with the `args` keyword.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBfuncname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The function to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_function_attribute()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_function_attribute(name)
|
|
|
|
since 0.48.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the compiler supports the GNU style (`__attribute__(...)`) `name`.
|
|
This is preferable to manual compile checks as it may be optimized for compilers that
|
|
do not support such attributes.
|
|
\fIThis table\fR[32] lists all of the supported attributes.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The attribute name to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_header()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_header(
|
|
.br
|
|
.RS 4
|
|
header_name,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
required: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the specified header is \fBexists\fR
|
|
with the specified prefix, dependencies, and arguments.
|
|
|
|
This method is faster than \fIcompiler.check_header\fR since it only does a
|
|
pre-processor check.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBheader_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The header to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: false, since 0.50.0
|
|
.br
|
|
.RS 2
|
|
When set to `true`, Meson will halt if the header check fails.
|
|
When set to a \fI`feature`\fR[0] option, the feature will control if it is searched and whether to fail if not found.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_header_symbol()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_header_symbol(
|
|
.br
|
|
.RS 4
|
|
header,
|
|
.br
|
|
symbol,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
required: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Detects whether a particular symbol is declared in the specified header.
|
|
|
|
Symbols here include function, variable, `#define`, type definition, etc.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBheader\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The header to check.
|
|
.RE
|
|
|
|
\fBsymbol\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The symbol to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
\fBrequired\fR
|
|
\fIbool | feature\fR, default: false, since 0.50.0
|
|
.br
|
|
.RS 2
|
|
When set to `true`, Meson will halt if the header check fails.
|
|
When set to a \fI`feature`\fR[0] option, the feature will control if it is searched and whether to fail if not found.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_link_argument()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_link_argument(argument)
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the linker accepts the specified command line argument,
|
|
that is, can
|
|
compile and link code without erroring out or printing a warning
|
|
about an unknown flag. Link arguments will be passed to the
|
|
compiler, so should usually have the `-Wl,` prefix. On VisualStudio
|
|
a `/link` argument will be prepended.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBargument\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The argument to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_member()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_member(
|
|
.br
|
|
.RS 4
|
|
typename,
|
|
.br
|
|
membername,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the type has the specified member.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtypename\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The type to check.
|
|
.RE
|
|
|
|
\fBmembername\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The member to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_members()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_members(
|
|
.br
|
|
.RS 4
|
|
typename,
|
|
.br
|
|
member...,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the type has \fBall\fR the specified members.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtypename\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The type to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBmember\fR
|
|
\fIstr\fR, 1...N times
|
|
.br
|
|
.RS 2
|
|
The members to check
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_multi_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_multi_arguments(arg...)
|
|
|
|
since 0.37.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
the same as \fIcompiler.has_argument\fR but takes multiple arguments
|
|
and uses them all in a single compiler invocation.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The arguments to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_multi_link_arguments()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_multi_link_arguments(arg...)
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
the same as \fIcompiler.has_link_argument\fR but takes multiple arguments
|
|
and uses them all in a single compiler invocation.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The link arguments to check.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.has_type()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.has_type(
|
|
.br
|
|
.RS 4
|
|
typename,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the specified token is a type.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtypename\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The type to check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.links()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.links(
|
|
.br
|
|
.RS 4
|
|
code,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
name:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the code compiles and links.
|
|
|
|
\fBSince 0.60.0\fR, if the `file` object's
|
|
suffix does not match the compiler object's language, the compiler
|
|
corresponding to the suffix is used to compile the source, while the
|
|
target of the `links` method is used to link the resulting object file.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBcode\fR
|
|
\fIstr | file\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The source code to check.
|
|
|
|
If a string is passed, the code is used directly. If a \fIfile\fR object
|
|
is passed, its content is used for the compiler check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBname\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The name to use for printing a message about the compiler check.
|
|
If this keyword argument is not passed, no message will be printed about the check.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.preprocess()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[custom_idx]\fR compiler.preprocess(
|
|
.br
|
|
.RS 4
|
|
source...,
|
|
.br
|
|
compile_args:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
output:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.64.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Preprocess a list of source files but do not compile them. The preprocessor
|
|
will receive the same arguments (include directories, defines, etc) as with
|
|
normal compilation. That includes for example args added with
|
|
`add_project_arguments()`, or on the command line with `-Dc_args=-DFOO`.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
Input source to compile. The following types are supported:
|
|
|
|
- Strings relative to the current source directory
|
|
.br
|
|
- \fIfile\fR objects defined in any preceding build file
|
|
.br
|
|
- The return value of configure-time generators such as \fIconfigure_file\fR
|
|
.br
|
|
- The return value of build-time generators such as \fIcustom_target\fR or \fIgenerator.process\fR
|
|
|
|
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 \fIorder-only
|
|
dependency\fR[3] on
|
|
all generated input files, including unknown files. This is needed to
|
|
bootstrap the generation of the real dependencies in the
|
|
\fIdepfile\fR[4] generated
|
|
by your compiler to determine when to rebuild sources. Ninja relies on
|
|
this dependency file for all input files, generated and non-generated.
|
|
The behavior is similar for other backends.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcompile_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Extra flags to pass to the preprocessor
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBoutput\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Template for name of preprocessed files: `@PLAINNAME@` is replaced by
|
|
the source filename and `@BASENAME@` is replaced by the source filename
|
|
without its extension.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.run()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIrunresult\fR compiler.run(
|
|
.br
|
|
.RS 4
|
|
code,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
name:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Attempts to compile and execute the given code fragment.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBcode\fR
|
|
\fIstr | file\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The source code to check.
|
|
|
|
If a string is passed, the code is used directly. If a \fIfile\fR object
|
|
is passed, its content is used for the compiler check.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBname\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The name to use for printing a message about the compiler check.
|
|
If this keyword argument is not passed, no message will be printed about the check.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.sizeof()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIint\fR compiler.sizeof(
|
|
.br
|
|
.RS 4
|
|
typename,
|
|
.br
|
|
args:,
|
|
.br
|
|
dependencies:,
|
|
.br
|
|
include_directories:,
|
|
.br
|
|
no_builtin_args: \fBfalse\fR,
|
|
.br
|
|
prefix:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
returns the size of the given type (e.g. `'int'`) or -1 if the type is unknown.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBtypename\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The type to compute.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBargs\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to pass a list of compiler arguments.
|
|
Defining include paths for headers not in the default include path
|
|
via `-Isome/path/to/header` is generally supported, however, usually not
|
|
recommended.
|
|
|
|
This is because include directories can also be specified via the
|
|
`include_directories` or the `dependency` kwarg (if present).
|
|
The same is also true for passing libraries to link with `-lfoo`.
|
|
.RE
|
|
|
|
\fBdependencies\fR
|
|
\fIdep | list[dep]\fR
|
|
.br
|
|
.RS 2
|
|
Additionally dependencies required for compiling and / or linking.
|
|
.RE
|
|
|
|
\fBinclude_directories\fR
|
|
\fIinc | list[inc]\fR, since 0.38.0
|
|
.br
|
|
.RS 2
|
|
Extra directories for header searches.
|
|
.RE
|
|
|
|
\fBno_builtin_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
|
|
.RE
|
|
|
|
\fBprefix\fR
|
|
\fIstr | list[str]\fR
|
|
.br
|
|
.RS 2
|
|
Used to add `#include`s and other things that are required
|
|
for the symbol to be declared. Since 1.0.0 an array is accepted
|
|
too. When an array is passed, the items are concatenated together
|
|
separated by a newline.
|
|
System definitions should be passed via compiler args
|
|
(eg: `_GNU_SOURCE` is often required for some symbols to be exposed
|
|
on Linux, and it should be passed via `args` keyword argument).
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS compiler.symbols_have_underscore_prefix()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR compiler.symbols_have_underscore_prefix()
|
|
|
|
since 0.37.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the C symbol mangling is one underscore (`_`) prefixed to the symbol.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS compiler.version()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR compiler.version()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the compiler's version number as a string.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS custom_idx.full_path()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR custom_idx.full_path()
|
|
|
|
since 0.54.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a full path pointing to the result target file
|
|
NOTE: In most cases using the object itself will do the same job as
|
|
this and will also allow Meson to setup inter-target dependencies
|
|
correctly. Please file a bug if that doesn't work for you.
|
|
|
|
See \fIcustom_tgt.full_path\fR
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS custom_tgt.[index]()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIcustom_idx\fR custom_tgt.[index]()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an opaque object that references this target, and
|
|
can be used as a source in other targets. When it is used as such it
|
|
will make that target depend on this custom target, but the only
|
|
source added will be the one that corresponds to the index of the
|
|
custom target's output argument.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS custom_tgt.full_path()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR custom_tgt.full_path()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a full path pointing to the result target file
|
|
NOTE: In most cases using the object itself will do the same job as
|
|
this and will also allow Meson to setup inter-target dependencies
|
|
correctly. Please file a bug if that doesn't work for you.
|
|
\fB(since 0.54.0)\fR It can be also called on indexes objects:
|
|
`custom_targets[i].full_path()`.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS custom_tgt.to_list()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[custom_idx]\fR custom_tgt.to_list()
|
|
|
|
since 0.54.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a list of opaque objects that references this target,
|
|
and can be used as a source in other targets. This can be used to
|
|
iterate outputs with `foreach` loop.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS dep.as_link_whole()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIdep\fR dep.as_link_whole()
|
|
|
|
since 0.56.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Only dependencies created with \fIdeclare_dependency\fR,
|
|
returns a copy of the dependency object with all
|
|
link_with arguments changed to link_whole. This is useful for example for
|
|
fallback dependency from a subproject built with `default_library=static`.
|
|
Note that all `link_with` objects must be static libraries otherwise an error
|
|
will be raised when trying to `link_whole` a shared library.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS dep.as_system()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIdep\fR dep.as_system([value])
|
|
|
|
since 0.52.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a copy of the dependency object, which has changed the value of `include_type`
|
|
to `value`. The `value` argument is optional and
|
|
defaults to `'preserve'`.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBvalue\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The new value. See \fIdependency\fR for supported values.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dep.found()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR dep.found()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns whether the dependency was found.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS dep.get_configtool_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR dep.get_configtool_variable(var_name)
|
|
|
|
\fBdeprecated\fR since 0.56.0, since 0.44.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Gets the command line argument from the config tool (with `--` prepended), or,
|
|
if invoked on a non config-tool dependency, error out.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvar_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the variable to query
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dep.get_pkgconfig_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR dep.get_pkgconfig_variable(
|
|
.br
|
|
.RS 4
|
|
var_name,
|
|
.br
|
|
default:,
|
|
.br
|
|
define_variable:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
\fBdeprecated\fR since 0.56.0, since 0.36.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Gets the pkg-config variable specified,
|
|
or, if invoked on a non pkg-config
|
|
dependency, error out.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvar_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the variable to query
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBdefault\fR
|
|
\fIstr\fR, since 0.45.0
|
|
.br
|
|
.RS 2
|
|
The value to return if the variable was not found.
|
|
A warning is issued if the variable is not defined and this kwarg is not set.
|
|
.RE
|
|
|
|
\fBdefine_variable\fR
|
|
\fIlist[str]\fR, since 0.44.0
|
|
.br
|
|
.RS 2
|
|
You can also redefine a
|
|
variable by passing a list to this kwarg
|
|
that can affect the retrieved variable: `['prefix', '/'])`.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dep.get_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR dep.get_variable(
|
|
.br
|
|
.RS 4
|
|
[varname],
|
|
.br
|
|
cmake:,
|
|
.br
|
|
configtool:,
|
|
.br
|
|
default_value:,
|
|
.br
|
|
internal:,
|
|
.br
|
|
pkgconfig:,
|
|
.br
|
|
pkgconfig_define:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.51.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
A generic variable getter method, which replaces the
|
|
`get_\fBtype\fR_variable` methods. This allows one to get the variable
|
|
from a dependency without knowing specifically how that dependency
|
|
was found. If `default_value` is set and the value cannot be gotten
|
|
from the object then `default_value` is returned, if it is not set
|
|
then an error is raised.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBvarname\fR
|
|
\fIstr\fR, since 0.58.0
|
|
.br
|
|
.RS 2
|
|
This argument is used as a default value
|
|
for `cmake`, `pkgconfig`, `configtool` and `internal` keyword
|
|
arguments. It is useful in the common case where `pkgconfig` and `internal`
|
|
use the same variable name, in which case it's easier to write `dep.get_variable('foo')`
|
|
instead of `dep.get_variable(pkgconfig: 'foo', internal: 'foo')`.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcmake\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The CMake variable name
|
|
.RE
|
|
|
|
\fBconfigtool\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The configtool variable name
|
|
.RE
|
|
|
|
\fBdefault_value\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The default value to return when the variable does not exist
|
|
.RE
|
|
|
|
\fBinternal\fR
|
|
\fIstr\fR, since 0.54.0
|
|
.br
|
|
.RS 2
|
|
The internal variable name
|
|
.RE
|
|
|
|
\fBpkgconfig\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The pkgconfig variable name
|
|
.RE
|
|
|
|
\fBpkgconfig_define\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
See \fIdep.get_pkgconfig_variable\fR
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dep.include_type()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR dep.include_type()
|
|
|
|
since 0.52.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the value set by the `include_type` kwarg.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS dep.name()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR dep.name()
|
|
|
|
since 0.48.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the name of the dependency that was searched.
|
|
Returns `'internal'` for dependencies created with
|
|
\fIdeclare_dependency\fR.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS dep.partial_dependency()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIdep\fR dep.partial_dependency(
|
|
.br
|
|
.RS 4
|
|
compile_args: \fBfalse\fR,
|
|
.br
|
|
includes: \fBfalse\fR,
|
|
.br
|
|
link_args: \fBfalse\fR,
|
|
.br
|
|
links: \fBfalse\fR,
|
|
.br
|
|
sources: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a new dependency object with the same name, version, found status,
|
|
type name, and methods as the object that called it. This new
|
|
object will only inherit other attributes from its parent as
|
|
controlled by keyword arguments.
|
|
|
|
If the parent has any dependencies, those will be applied to the new
|
|
partial dependency with the same rules. So, given:
|
|
.RS 4
|
|
dep1 = declare_dependency(compile_args : '-Werror=foo', link_with : 'libfoo')
|
|
.br
|
|
dep2 = declare_dependency(compile_args : '-Werror=bar', dependencies : dep1)
|
|
.br
|
|
dep3 = dep2.partial_dependency(compile_args : true)
|
|
.br
|
|
.RE
|
|
dep3 will add `['-Werror=foo', '-Werror=bar']` to the compiler args
|
|
of any target it is added to, but libfoo will not be added to the
|
|
link_args.
|
|
|
|
The following arguments will add the following attributes:
|
|
|
|
- compile_args: any arguments passed to the compiler
|
|
.br
|
|
- link_args: any arguments passed to the linker
|
|
.br
|
|
- links: anything passed via link_with or link_whole
|
|
.br
|
|
- includes: any include_directories
|
|
.br
|
|
- sources: any compiled or static sources the dependency has
|
|
.RE
|
|
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBcompile_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Whether to include compile_args
|
|
.RE
|
|
|
|
\fBincludes\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Whether to include includes
|
|
.RE
|
|
|
|
\fBlink_args\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Whether to include link_args
|
|
.RE
|
|
|
|
\fBlinks\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Whether to include links
|
|
.RE
|
|
|
|
\fBsources\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
Whether to include sources
|
|
.RE
|
|
|
|
.RE
|
|
\fBWARNINGS\fR
|
|
.RS 4
|
|
A bug present until 0.50.1 results in the above behavior not working correctly.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dep.type_name()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR dep.type_name()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string describing the type of the
|
|
dependency, the most common values are `internal` for deps created
|
|
with \fIdeclare_dependency\fR and `pkgconfig` for system dependencies
|
|
obtained with Pkg-config.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS dep.version()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR dep.version()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
the version number as a string,
|
|
for example `1.2.8`.
|
|
`unknown` if the dependency provider doesn't support determining the
|
|
version.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS dict.get()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIany\fR dict.get(key, [fallback])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
returns the value for the key given as first
|
|
argument if it is present in the dictionary, or the optional
|
|
fallback value given as the second argument. If a single argument
|
|
was given and the key was not found, causes a fatal error
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBkey\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The key to query.
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBfallback\fR
|
|
\fIany\fR
|
|
.br
|
|
.RS 2
|
|
Fallback value that is returned if the key is not in the \fIdict\fR.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dict.has_key()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR dict.has_key(key)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the dictionary contains the key given as argument, `false` otherwise.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBkey\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The key to query.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS dict.keys()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR dict.keys()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns an array of keys in the dictionary.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS disabler.found()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR disabler.found()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Always returns `false`
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS env.append()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR env.append(variable, Value..., separator:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
appends the given values to
|
|
the old value of the environment variable, e.g. `env.append('FOO',
|
|
\'BAR', 'BAZ', separator : ';')` produces `BOB;BAR;BAZ` if `FOO` had
|
|
the value `BOB` and plain `BAR;BAZ` if the value was not defined.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvariable\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The variable to modify
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBValue\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The values to append
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBseparator\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The separator to use. If not explicitly specified, the default path
|
|
separator for the host operating system will be used, i.e. ';' for
|
|
Windows and ':' for UNIX/POSIX systems.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS env.prepend()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR env.prepend(variable, Value..., separator:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Same as `append` except that it writes to the beginning of the variable.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvariable\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The variable to modify
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBValue\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The values to prepend
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBseparator\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The separator to use. If not explicitly specified, the default path
|
|
separator for the host operating system will be used, i.e. ';' for
|
|
Windows and ':' for UNIX/POSIX systems.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS env.set()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR env.set(variable, Value..., separator:)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Sets the environment variable
|
|
specified in the first argument to the values in the varargs
|
|
joined by the separator. For instance, `env.set('FOO', 'BAR'),` sets envvar
|
|
`FOO` to value `BAR`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvariable\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The variable to modify
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBValue\fR
|
|
\fIstr\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The values to set
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBseparator\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
The separator to use. If not explicitly specified, the default path
|
|
separator for the host operating system will be used, i.e. ';' for
|
|
Windows and ':' for UNIX/POSIX systems.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS external_program.found()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR external_program.found()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns whether the executable was found.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS external_program.full_path()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR external_program.full_path()
|
|
|
|
since 0.55.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string pointing to the script or executable.
|
|
|
|
\fB\fRNOTE:\fB\fR You should not usually need to use this method. Passing the
|
|
object itself should work in most contexts where a program can appear,
|
|
and allows Meson to setup inter-target dependencies correctly (for
|
|
example in cases where a program might be overridden by a \fIbuild_tgt\fR).
|
|
Only use this if you specifically need a string, such as when embedding
|
|
a program path into a header file.
|
|
|
|
For example:
|
|
.RS 4
|
|
run_command(find_program('foo'), 'arg1', 'arg2')
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS external_program.path()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR external_program.path()
|
|
|
|
\fBdeprecated\fR since 0.55.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
\fBDeprecated:\fR Use \fIexternal_program.full_path\fR instead.
|
|
|
|
Returns a string pointing to the script or executable.
|
|
|
|
\fB\fRNOTE:\fB\fR You should not usually need to use this method. Passing the
|
|
object itself should work in most contexts where a program can appear,
|
|
and allows Meson to setup inter-target dependencies correctly (for
|
|
example in cases where a program might be overridden by a \fIbuild_tgt\fR).
|
|
Only use this if you specifically need a string, such as when embedding
|
|
a program path into a header file.
|
|
|
|
For example:
|
|
.RS 4
|
|
run_command(find_program('foo'), 'arg1', 'arg2')
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS external_program.version()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR external_program.version()
|
|
|
|
since 0.62.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
The version number as a string, for example `1.2.8`.
|
|
|
|
`unknown` if the program cannot determine the version via a `--version` argument.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS feature.allowed()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR feature.allowed()
|
|
|
|
since 0.59.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns whether the feature was set to `'enabled'` or `'auto'`
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS feature.auto()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR feature.auto()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns whether the feature was set to `'auto'`
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS feature.disable_auto_if()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIfeature\fR feature.disable_auto_if(value)
|
|
|
|
since 0.59.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the feature, with `'auto'` converted to `'disabled'` if value is true.
|
|
|
|
| Feature / Condition | `value = true` | `value = false` |
|
|
| ------------------- | -------------- | --------------- |
|
|
| Enabled | Enabled | Enabled |
|
|
| Disabled | Disabled | Disabled |
|
|
| Auto | Disabled | Auto |
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvalue\fR
|
|
\fIbool\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
See the table above
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS feature.disabled()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR feature.disabled()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns whether the feature was set to `'disabled'`
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS feature.enabled()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR feature.enabled()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns whether the feature was set to `'enabled'`
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS feature.require()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIfeature\fR feature.require(value, error_message: \fB''\fR)
|
|
|
|
since 0.59.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the object itself if the value is true; an error if the object is
|
|
`'enabled'` and the value is false; a disabled feature if the object
|
|
is `'auto'` or `'disabled'` and the value is false.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvalue\fR
|
|
\fIbool\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The value to check
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBerror_message\fR
|
|
\fIstr\fR, default: ''
|
|
.br
|
|
.RS 2
|
|
The error Message to print if the check fails
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
`require` is useful to restrict the applicability of `'auto'` features,
|
|
for example based on other features or on properties of the host machine:
|
|
.RS 4
|
|
if get_option('directx').require(host_machine.system() == 'windows',
|
|
.br
|
|
error_message: 'DirectX only available on Windows').allowed() then
|
|
.br
|
|
src += ['directx.c']
|
|
.br
|
|
config.set10('HAVE_DIRECTX', true)
|
|
.br
|
|
endif
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS generator.process()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIgenerated_list\fR generator.process(
|
|
.br
|
|
.RS 4
|
|
source...,
|
|
.br
|
|
extra_args:,
|
|
.br
|
|
preserve_path_from:,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Takes a list of files, causes them to be processed and returns an object containing the result
|
|
which can then, for example, be passed into a build target definition.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBsource\fR
|
|
\fIstr | file | custom_tgt | custom_idx | generated_list\fR, 1...N times
|
|
.br
|
|
.RS 2
|
|
List of sources to process.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBextra_args\fR
|
|
\fIlist[str]\fR
|
|
.br
|
|
.RS 2
|
|
If present, will be used to replace an entry `@EXTRA_ARGS@` in the argument list.
|
|
.RE
|
|
|
|
\fBpreserve_path_from\fR
|
|
\fIstr\fR, since 0.45.0
|
|
.br
|
|
.RS 2
|
|
If given, specifies that the output files need to maintain their directory structure
|
|
inside the target temporary directory. The most common value for this is
|
|
`meson.current_source_dir()`. With this value when a file called
|
|
`subdir/one.input` is processed it generates a file `{target private
|
|
directory}/subdir/one.out` as opposed to `{target private
|
|
directory}/one.out`.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS int.is_even()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR int.is_even()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the number is even.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS int.is_odd()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR int.is_odd()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the number is odd
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS int.to_string()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR int.to_string()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the value of the number as a string.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS list.contains()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR list.contains(item)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the array contains the object
|
|
given as argument, `false` otherwise
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBitem\fR
|
|
\fIany\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The item to check
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS list.get()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIany\fR list.get(index, [fallback])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
returns the object at the given index,
|
|
negative indices count from the back of the array, indexing out of
|
|
bounds returns the `fallback` value \fB(since 0.38.0)\fR or, if it is
|
|
not specified, causes a fatal error
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBindex\fR
|
|
\fIint\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Index of the list position to query. Negative values start at the end of the list
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBfallback\fR
|
|
\fIany\fR
|
|
.br
|
|
.RS 2
|
|
Fallback value that is returned if the index is out of range.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS list.length()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIint\fR list.length()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the current size of the array / list.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.add_devenv()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR meson.add_devenv(env, method:, separator:)
|
|
|
|
since 0.58.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
add an \fIenv\fR object (returned by \fIenvironment\fR)
|
|
to the list of environments that will be applied when using \fI`meson devenv`\fR[33]
|
|
command line.
|
|
|
|
This is useful for developers who wish to use the project without
|
|
installing it, it is often needed to set for example the path to plugins
|
|
directory, etc. Alternatively, a list or dictionary can be passed as first
|
|
argument.
|
|
.RS 4
|
|
devenv = environment()
|
|
.br
|
|
devenv.set('PLUGINS_PATH', meson.current_build_dir())
|
|
.br
|
|
\...
|
|
.br
|
|
meson.add_devenv(devenv)
|
|
.br
|
|
.RE
|
|
After configuring and compiling that project, a terminal can be opened with
|
|
the environment set:
|
|
.RS 4
|
|
sh
|
|
.br
|
|
$ meson devenv -C <builddir>
|
|
.br
|
|
$ echo $PLUGINS_PATH
|
|
.br
|
|
/path/to/source/subdir
|
|
.br
|
|
.RE
|
|
See \fI`meson devenv`\fR[32] command documentation for a list of
|
|
environment variables that are set by default by Meson.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBenv\fR
|
|
\fIenv | str | list[str] | dict[str] | dict[list[str]]\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The \fIenv\fR object to add.
|
|
Since \fB0.62.0\fR list of strings is allowed in dictionary values. In that
|
|
case values are joined using the separator.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBmethod\fR
|
|
\fIstr\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
Must be one of 'set', 'prepend', or 'append'
|
|
(defaults to 'set'). Controls if initial values defined in the first
|
|
positional argument are prepended, appended or replace the current value
|
|
of the environment variable.
|
|
.RE
|
|
|
|
\fBseparator\fR
|
|
\fIstr\fR, since 0.62.0
|
|
.br
|
|
.RS 2
|
|
The separator to use for the initial values defined in
|
|
the first positional argument. If not explicitly specified, the default
|
|
path separator for the host operating system will be used, i.e. ';' for
|
|
Windows and ':' for UNIX/POSIX systems.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.add_dist_script()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR meson.add_dist_script(script_name, arg...)
|
|
|
|
since 0.48.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Causes the script given as argument to run during `dist`
|
|
operation after the
|
|
distribution source has been generated but before it is
|
|
archived. Note that this runs the script file that is in the
|
|
_staging_ directory, not the one in the source directory. If the
|
|
script file can not be found in the staging directory, it is a hard
|
|
error. The `MESON_DIST_ROOT` environment variables is set when dist scripts is
|
|
run.
|
|
|
|
\fB(since 0.54.0)\fR The `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`
|
|
environment variables are set when dist scripts are run. They are path to the
|
|
root source and build directory of the main project, even when the script
|
|
comes from a subproject.
|
|
|
|
\fB(since 0.58.0)\fR This command can be invoked from a subproject, it was a hard
|
|
error in earlier versions. Subproject dist scripts will only be executed
|
|
when running `meson dist --include-subprojects`. `MESON_PROJECT_SOURCE_ROOT`,
|
|
`MESON_PROJECT_BUILD_ROOT` and `MESON_PROJECT_DIST_ROOT` environment
|
|
variables are set when dist scripts are run. They are identical to
|
|
`MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` and `MESON_DIST_ROOT` for main project
|
|
scripts, but for subproject scripts they have the path to the root of the
|
|
subproject appended, usually `subprojects/<subproject-name>`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBscript_name\fR
|
|
\fIstr | file | external_program\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The script to execute.
|
|
|
|
\fB(since 0.55.0)\fR The output of \fIfind_program\fR as well as strings are accepted.
|
|
|
|
\fB(since 0.57.0)\fR \fIfile\fR objects and the output of \fIconfigure_file\fR may be used.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr | file | external_program\fR, 0...N times, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Additional arguments
|
|
|
|
\fB(since 0.55.0)\fR The output of \fIconfigure_file\fR, \fIfiles\fR, and \fIfind_program\fR
|
|
as well as strings are accepted.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.add_install_script()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR meson.add_install_script(
|
|
.br
|
|
.RS 4
|
|
script_name,
|
|
.br
|
|
arg...,
|
|
.br
|
|
install_tag:,
|
|
.br
|
|
skip_if_destdir: \fBfalse\fR,
|
|
.br
|
|
.RE
|
|
)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Causes the script given as an argument to be run during the install step,
|
|
this script will have the environment variables `MESON_SOURCE_ROOT`,
|
|
`MESON_BUILD_ROOT`, `MESON_INSTALL_PREFIX`,
|
|
`MESON_INSTALL_DESTDIR_PREFIX`, and `MESONINTROSPECT` set.
|
|
All positional arguments are passed as parameters.
|
|
|
|
\fB(since 0.54.0)\fR If `meson install` is called with the `--quiet` option, the
|
|
environment variable `MESON_INSTALL_QUIET` will be set.
|
|
|
|
Meson uses the `DESTDIR` environment variable as set by the
|
|
inherited environment to determine the (temporary) installation
|
|
location for files. Your install script must be aware of this while
|
|
manipulating and installing files. The correct way to handle this is
|
|
with the `MESON_INSTALL_DESTDIR_PREFIX` variable which is always set
|
|
and contains `DESTDIR` (if set) and `prefix` joined together. This
|
|
is useful because both are usually absolute paths and there are
|
|
platform-specific edge-cases in joining two absolute paths.
|
|
|
|
In case it is needed, `MESON_INSTALL_PREFIX` is also always set and
|
|
has the value of the `prefix` option passed to Meson.
|
|
|
|
`MESONINTROSPECT` contains the path to the introspect command that
|
|
corresponds to the `meson` executable that was used to configure the
|
|
build. (This might be a different path than the first executable
|
|
found in `PATH`.) It can be used to query build configuration. Note
|
|
that the value will contain many parts, f.ex., it may be `python3
|
|
/path/to/meson.py introspect`. The user is responsible for splitting
|
|
the string to an array if needed by splitting lexically like a UNIX
|
|
shell would. If your script uses Python, `shlex.split()` is the
|
|
easiest correct way to do this.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBscript_name\fR
|
|
\fIstr | file | external_program | exe | custom_tgt | custom_idx\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The script to execute.
|
|
|
|
\fB(since 0.55.0)\fR The output of \fIfind_program\fR, \fIexecutable\fR,
|
|
\fIcustom_target\fR, as well as strings are accepted.
|
|
|
|
\fB(since 0.57.0)\fR \fIfile\fR objects and the output of \fIconfigure_file\fR may be used.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr | file | external_program | exe | custom_tgt | custom_idx\fR, 0...N times, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Additional arguments
|
|
|
|
\fB(since 0.55.0)\fR The output of \fIfind_program\fR, \fIexecutable\fR,
|
|
\fIcustom_target\fR, as well as strings are accepted.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBinstall_tag\fR
|
|
\fIstr\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
A string used by the `meson install --tags` command
|
|
to install only a subset of the files.
|
|
By default the script has no install tag which means it is not being run when
|
|
`meson install --tags` argument is specified.
|
|
.RE
|
|
|
|
\fBskip_if_destdir\fR
|
|
\fIbool\fR, default: false, since 0.57.0
|
|
.br
|
|
.RS 2
|
|
If `true` the script will not be run if DESTDIR is set during installation.
|
|
This is useful in the case the script updates system wide
|
|
cache that is only needed when copying files into final destination.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.add_postconf_script()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR meson.add_postconf_script(script_name, arg...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Runs the given command after all project files have been generated.
|
|
This script will have the environment variables
|
|
`MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT` set.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBscript_name\fR
|
|
\fIstr | file | external_program\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The script to execute.
|
|
|
|
\fB(since 0.55.0)\fR The output of \fIfind_program\fR as well as strings are accepted.
|
|
|
|
\fB(since 0.57.0)\fR \fIfile\fR objects and the output of \fIconfigure_file\fR may be used.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBarg\fR
|
|
\fIstr | file | external_program\fR, 0...N times, since 0.49.0
|
|
.br
|
|
.RS 2
|
|
Additional arguments
|
|
|
|
\fB(since 0.55.0)\fR The output of \fIconfigure_file\fR, \fIfiles\fR, and \fIfind_program\fR
|
|
as well as strings are accepted.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.backend()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.backend()
|
|
|
|
since 0.37.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string representing the current backend:
|
|
|
|
- `ninja`
|
|
.br
|
|
- `vs2010`
|
|
.br
|
|
- `vs2012`
|
|
.br
|
|
- `vs2013`
|
|
.br
|
|
- `vs2015`
|
|
.br
|
|
- `vs2017`
|
|
.br
|
|
- `vs2019`
|
|
.br
|
|
- `vs2022`
|
|
.br
|
|
- `xcode`
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.build_root()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.build_root()
|
|
|
|
\fBdeprecated\fR since 0.56.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string with the absolute path to the build root directory.
|
|
This function will return the
|
|
build root of the parent project if called from a subproject, which is usually
|
|
not what you want. Try using \fImeson.current_build_dir\fR or \fImeson.project_build_root\fR.
|
|
In the rare cases where the root of the main project is needed,
|
|
use \fImeson.global_build_root\fR that has the same behaviour but with a more explicit
|
|
name.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.can_run_host_binaries()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR meson.can_run_host_binaries()
|
|
|
|
since 0.55.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if the build machine can run binaries compiled for the host.
|
|
This returns `true` unless you are
|
|
cross compiling, need a helper to run host binaries, and don't have one.
|
|
For example when cross compiling from Linux to Windows, one can use `wine`
|
|
as the helper.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.current_build_dir()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.current_build_dir()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string with the absolute path to the current build directory.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.current_source_dir()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.current_source_dir()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string to the current source directory.
|
|
.RE
|
|
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
\fB\fRYou do not need to use this function!\fB\fR
|
|
|
|
When passing files from the current source directory to a function since
|
|
that is the default. Also, you can use the \fIfiles\fR function to
|
|
refer to files in the current or any other source directory instead
|
|
of constructing paths manually with \fImeson.current_source_dir\fR.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.get_compiler()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIcompiler\fR meson.get_compiler(language, native: \fBfalse\fR)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a \fIcompiler\fR object describing a compiler.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBlanguage\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The language of the compiler to return.
|
|
|
|
See our \fIlist of supported languages\fR[34].
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
When set to `true` Meson returns the compiler for the build
|
|
machine (the "native" compiler) and when `false` it returns the host
|
|
compiler (the "cross" compiler). If `native` is omitted, Meson
|
|
returns the "cross" compiler if we're currently cross-compiling and
|
|
the "native" compiler if we're not.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.get_cross_property()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIany\fR meson.get_cross_property(propname, [fallback_value])
|
|
|
|
\fBdeprecated\fR since 0.58.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the given property from a cross file, the optional fallback_value
|
|
is returned if not cross compiling or the given property is not found.
|
|
|
|
This method is replaced by \fImeson.get_external_property\fR.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBpropname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the property in the cross / native file.
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBfallback_value\fR
|
|
\fIany\fR
|
|
.br
|
|
.RS 2
|
|
Value to return if `propname` is not set in the machine file.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.get_external_property()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIany\fR meson.get_external_property(
|
|
.br
|
|
.RS 4
|
|
propname,
|
|
.br
|
|
[fallback_value],
|
|
.br
|
|
native:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.54.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the given property from a native or cross file.
|
|
The optional fallback_value is returned if the given property is not found.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBpropname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the property in the cross / native file.
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBfallback_value\fR
|
|
\fIany\fR
|
|
.br
|
|
.RS 2
|
|
Value to return if `propname` is not set in the machine file.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBnative\fR
|
|
\fIbool\fR
|
|
.br
|
|
.RS 2
|
|
Setting `native` to `true` forces retrieving a variable from the
|
|
native file, even when cross-compiling.
|
|
If `native: false` or not specified, the variable is retrieved from the
|
|
cross-file if cross-compiling, and from the native-file when not cross-compiling.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.global_build_root()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.global_build_root()
|
|
|
|
since 0.58.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string with the absolute path to the build root directory.
|
|
This function will return the build root of the
|
|
main project if called from a subproject, which is usually not what you want.
|
|
It is usually preferable to use \fImeson.current_build_dir\fR or \fImeson.project_build_root\fR.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.global_source_root()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.global_source_root()
|
|
|
|
since 0.58.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string with the absolute path to the source root directory
|
|
This function will return the source root of the
|
|
main project if called from a subproject, which is usually not what you want.
|
|
It is usually preferable to use \fImeson.current_source_dir\fR or \fImeson.project_source_root\fR.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.has_exe_wrapper()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR meson.has_exe_wrapper()
|
|
|
|
\fBdeprecated\fR since 0.55.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Use \fImeson.can_run_host_binaries\fR instead.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.has_external_property()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR meson.has_external_property(propname, native:)
|
|
|
|
since 0.58.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Checks whether the given property exist in a native or cross file.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBpropname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the property in the cross / native file.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBnative\fR
|
|
\fIbool\fR
|
|
.br
|
|
.RS 2
|
|
Setting `native` to `true` forces retrieving a variable from the
|
|
native file, even when cross-compiling.
|
|
If `native: false` or not specified, the variable is retrieved from the
|
|
cross-file if cross-compiling, and from the native-file when not cross-compiling.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.install_dependency_manifest()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR meson.install_dependency_manifest(output_name)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Installs a manifest file
|
|
containing a list of all subprojects, their versions and license
|
|
files to the file name given as the argument.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBoutput_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
Name of the manifest file to install
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.is_cross_build()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR meson.is_cross_build()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the current build is a \fIcross build\fR[35] and `false` otherwise.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.is_subproject()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR meson.is_subproject()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the current project is being built as a subproject of some other project and `false` otherwise.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.is_unity()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR meson.is_unity()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` when doing a \fIunity build\fR[36] (multiple sources are combined before compilation to reduce build time) and `false` otherwise.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.override_dependency()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR meson.override_dependency(
|
|
.br
|
|
.RS 4
|
|
name,
|
|
.br
|
|
dep_object,
|
|
.br
|
|
native: \fBfalse\fR,
|
|
.br
|
|
static:,
|
|
.br
|
|
.RE
|
|
)
|
|
|
|
since 0.54.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Specifies that whenever \fIdependency\fR with `name` is used, Meson should not
|
|
look it up on the system but instead return `dep_object`, which may either be
|
|
the result of \fIdependency\fR or \fIdeclare_dependency\fR.
|
|
|
|
Doing this in a subproject allows the parent
|
|
project to retrieve the dependency without having to know the dependency
|
|
variable name: `dependency(name, fallback : subproject_name)`.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the dependency to override.
|
|
.RE
|
|
|
|
\fBdep_object\fR
|
|
\fIdep\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The dependency to set as the override for `name`.
|
|
.RE
|
|
|
|
.RE
|
|
\fBKWARGS\fR
|
|
.RS 4
|
|
\fBnative\fR
|
|
\fIbool\fR, default: false
|
|
.br
|
|
.RS 2
|
|
If set to `true`, the dependency is always overwritten for the build machine.
|
|
Otherwise, the dependency is overwritten for the host machine, which
|
|
differs from the build machine when cross-compiling.
|
|
.RE
|
|
|
|
\fBstatic\fR
|
|
\fIbool\fR, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
Used to override static and/or shared dependencies separately.
|
|
If not specified it is assumed
|
|
`dep_object` follows `default_library` option value.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.override_find_program()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIvoid\fR meson.override_find_program(progname, program)
|
|
|
|
since 0.46.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
specifies that whenever \fIfind_program\fR is used to find a program
|
|
named `progname`, Meson should not look it up on the system but
|
|
instead return `program`, which may either be the result of
|
|
\fIfind_program\fR, \fIconfigure_file\fR or \fIexecutable\fR.
|
|
|
|
\fB(since 0.55.0)\fR If a version
|
|
check is passed to \fIfind_program\fR for a program that has been overridden with
|
|
an executable, the current project version is used.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBprogname\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the program to override.
|
|
.RE
|
|
|
|
\fBprogram\fR
|
|
\fIexe | file | external_program\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The program to set as the override for `progname`.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.project_build_root()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.project_build_root()
|
|
|
|
since 0.56.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string with the absolute path to the build root directory of the current (sub)project.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.project_license()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR meson.project_license()
|
|
|
|
since 0.45.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the array of licenses specified in \fIproject\fR function call.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.project_name()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.project_name()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the project name specified in the \fIproject\fR function call.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.project_source_root()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.project_source_root()
|
|
|
|
since 0.56.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string with the absolute path to the source root directory of the current (sub)project.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.project_version()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.project_version()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns the version string specified in \fIproject\fR function call.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS meson.source_root()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.source_root()
|
|
|
|
\fBdeprecated\fR since 0.56.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a string with the absolute path to the source root directory.
|
|
|
|
This function will return the source root of the
|
|
parent project if called from a subproject, which is usually not what you want.
|
|
Try using \fImeson.current_source_dir\fR or \fImeson.project_source_root\fR.
|
|
In the rare cases where the root of the main project is needed,
|
|
use \fImeson.global_source_root\fR that has the same behaviour but with a more explicit
|
|
name.
|
|
.RE
|
|
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
You should use the \fIfiles\fR function
|
|
to refer to files in the root source directory instead of
|
|
constructing paths manually with \fImeson.source_root\fR.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS meson.version()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR meson.version()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Return a string with the version of Meson.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS module.found()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR module.found()
|
|
|
|
since 0.59.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if the module was successfully imported, otherwise `false`.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS runresult.compiled()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR runresult.compiled()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
If `true`, the compilation succeeded, if `false` it did not
|
|
and the other methods return unspecified data. This is only available
|
|
for `compiler.run()` results.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS runresult.returncode()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIint\fR runresult.returncode()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
The return code of executing the compiled binary
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS runresult.stderr()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR runresult.stderr()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
The standard error produced when the command was run.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS runresult.stdout()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR runresult.stdout()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
The standard out produced when the command was run.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS str.contains()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR str.contains(fragment)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns `true` if string contains the string specified as the argument.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBfragment\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The string fragment to check
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
target = 'x86_FreeBSD'
|
|
.br
|
|
is_fbsd = target.to_lower().contains('freebsd')
|
|
.br
|
|
# is_fbsd now has the boolean value 'true'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.endswith()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR str.endswith(fragment)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if string ends with the string specified as the argument.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBfragment\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The string fragment to check
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
target = 'x86_FreeBSD'
|
|
.br
|
|
is_bsd = target.to_lower().endswith('bsd') # boolean value 'true'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.format()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.format(fmt, value...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Strings can be built using the string formatting functionality.
|
|
|
|
See \fIthe Meson syntax entry\fR[37] for more
|
|
information.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBfmt\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The string to format.
|
|
|
|
The formatting works by replacing placeholders of type `@number@` with
|
|
the corresponding varargs.
|
|
.RE
|
|
|
|
.RE
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBvalue\fR
|
|
\fIint | bool | str\fR, 0...N times
|
|
.br
|
|
.RS 2
|
|
The values to replace the @number@ placeholders in the format string.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
template = 'string: @0@, number: @1@, bool: @2@'
|
|
.br
|
|
res = template.format('text', 1, true)
|
|
.br
|
|
# res now has value 'string: text, number: 1, bool: true'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.join()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.join(strings...)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
The opposite of split,
|
|
for example `'.'.join(['a', 'b', 'c']` yields `'a.b.c'`.
|
|
.RE
|
|
|
|
\fBVARARGS\fR
|
|
.RS 4
|
|
\fBstrings\fR
|
|
\fIstr\fR, 0...N times, since 0.60.0
|
|
.br
|
|
.RS 2
|
|
The strings to join with the current string.
|
|
|
|
Before Meson \fB0.60.0\fR this function only accepts a single positional
|
|
argument of the type \fIlist[str\fR].
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
# Similar to the Python str.join()
|
|
.br
|
|
output = ' '.join(['foo', 'bar'])
|
|
.br
|
|
# Output value is 'foo bar'
|
|
.br
|
|
pathsep = ':'
|
|
.br
|
|
path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin'])
|
|
.br
|
|
# path now has the value '/usr/bin:/bin:/usr/local/bin'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.replace()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.replace(old, new)
|
|
|
|
since 0.58.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Search all occurrences of `old` and and replace it with `new`
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBold\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The substring to search
|
|
.RE
|
|
|
|
\fBnew\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The replacement string
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
# Replaces all instances of one substring with another
|
|
.br
|
|
s = 'semicolons;as;separators'
|
|
.br
|
|
s = s.replace('as', 'are')
|
|
.br
|
|
# 's' now has the value of 'semicolons;are;separators'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.split()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIlist[str]\fR str.split([split_string])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Splits the string at the specified character
|
|
(or whitespace if not set) and returns the parts in an
|
|
array.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBsplit_string\fR
|
|
\fIstr\fR
|
|
.br
|
|
.RS 2
|
|
Specifies the character / substring where to split the string.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
# Similar to the Python str.split()
|
|
.br
|
|
components = 'a b c d '.split()
|
|
.br
|
|
# components now has the value ['a', 'b', 'c', 'd']
|
|
.br
|
|
components = 'a b c d '.split(' ')
|
|
.br
|
|
# components now has the value ['a', 'b', '', '', 'c', 'd', '']
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.startswith()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR str.startswith(fragment)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns true if string starts with the string specified as the argument.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBfragment\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The string fragment to check
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
target = 'x86_FreeBSD'
|
|
.br
|
|
is_x86 = target.startswith('x86') # boolean value 'true'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.strip()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.strip([strip_chars])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Removes leading/ending spaces and newlines from the string.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBstrip_chars\fR
|
|
\fIstr\fR, since 0.43.0
|
|
.br
|
|
.RS 2
|
|
All characters in this string will be stripped.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
# Similar to the Python str.strip(). Removes leading/ending spaces and newlines
|
|
.br
|
|
define = ' -Dsomedefine '
|
|
.br
|
|
stripped_define = define.strip()
|
|
.br
|
|
# 'stripped_define' now has the value '-Dsomedefine'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.substring()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.substring([start], [end])
|
|
|
|
since 0.56.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns a substring specified from `start` to `end`.
|
|
Both `start` and `end` arguments are optional, so, for example, `'foobar'.substring()` will return `'foobar'`.
|
|
|
|
The method accepts negative values where negative `start` is relative to the end of
|
|
string `len(string) - start` as well as negative `end`.
|
|
.RE
|
|
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBstart\fR
|
|
\fIint\fR
|
|
.br
|
|
.RS 2
|
|
The start position
|
|
.RE
|
|
|
|
\fBend\fR
|
|
\fIint\fR
|
|
.br
|
|
.RS 2
|
|
The end position
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
# Similar to the Python str[start:end] syntax
|
|
.br
|
|
target = 'x86_FreeBSD'
|
|
.br
|
|
platform = target.substring(0, 3) # prefix string value 'x86'
|
|
.br
|
|
system = target.substring(4) # suffix string value 'FreeBSD'
|
|
.br
|
|
.RE
|
|
Example with negative values:
|
|
.RS 4
|
|
string = 'foobar'
|
|
.br
|
|
string.substring(-5, -3) # => 'oo'
|
|
.br
|
|
string.substring(1, -1) # => 'ooba'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.to_int()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIint\fR str.to_int()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Converts the string to an int and throws an error if it can't be
|
|
.RE
|
|
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
version = '1'
|
|
.br
|
|
# Converts the string to an int and throws an error if it can't be
|
|
.br
|
|
ver_int = version.to_int()
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.to_lower()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.to_lower()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Converts all characters to lower case
|
|
.RE
|
|
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
target = 'x86_FreeBSD'
|
|
.br
|
|
lower = target.to_lower() # t now has the value 'x86_freebsd'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.to_upper()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.to_upper()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Converts all characters to upper case
|
|
.RE
|
|
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
target = 'x86_FreeBSD'
|
|
.br
|
|
upper = target.to_upper() # t now has the value 'X86_FREEBSD'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.underscorify()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIstr\fR str.underscorify()
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Creates a string where every non-alphabetical non-number character is replaced with `_`.
|
|
.RE
|
|
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
name = 'Meson Docs.txt#Reference-manual'
|
|
.br
|
|
# Replaces all characters other than `a-zA-Z0-9` with `_` (underscore)
|
|
.br
|
|
# Useful for substituting into #defines, filenames, etc.
|
|
.br
|
|
underscored = name.underscorify()
|
|
.br
|
|
# underscored now has the value 'Meson_Docs_txt_Reference_manual'
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS str.version_compare()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR str.version_compare(compare_string)
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Does semantic version comparison.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBcompare_string\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The string to compare to.
|
|
.RE
|
|
|
|
.RE
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
version = '1.2.3'
|
|
.br
|
|
# Compare version numbers semantically
|
|
.br
|
|
is_new = version.version_compare('>=2.0')
|
|
.br
|
|
# is_new now has the boolean value false
|
|
.br
|
|
# Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '='
|
|
.br
|
|
.RE
|
|
Meson version comparison conventions include:
|
|
.RS 4
|
|
\'3.6'.version_compare('>=3.6.0') == false
|
|
.br
|
|
.RE
|
|
It is best to be unambiguous and specify the full revision level to compare.
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS subproject.found()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIbool\fR subproject.found()
|
|
|
|
since 0.48.0
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
Returns whether the subproject was successfully setup.
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.SS subproject.get_variable()
|
|
.RS 0
|
|
\fBSYNOPSIS\fR
|
|
.RS 4
|
|
\fIany\fR subproject.get_variable(var_name, [fallback])
|
|
.RE
|
|
|
|
\fBDESCRIPTION\fR
|
|
.RS 4
|
|
fetches the specified variable from inside the subproject.
|
|
This is useful to, for instance, get a
|
|
\fIdeclare_dependency\fR from the \fIsubproject\fR[24].
|
|
|
|
If the variable does not exist, the variable `fallback` is returned.
|
|
If a fallback is not specified, then attempting to read a non-existing
|
|
variable will cause a fatal error.
|
|
.RE
|
|
|
|
\fBPOSARGS\fR
|
|
.RS 4
|
|
\fBvar_name\fR
|
|
\fIstr\fR, \fBrequired\fR
|
|
.br
|
|
.RS 2
|
|
The name of the variable to query
|
|
.RE
|
|
|
|
.RE
|
|
\fBOPTARGS\fR
|
|
.RS 4
|
|
\fBfallback\fR
|
|
\fIany\fR
|
|
.br
|
|
.RS 2
|
|
The fallback value to return if `var_name` does not exist.
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SH OBJECTS
|
|
.P
|
|
.SS alias_tgt
|
|
.RS 2
|
|
\fBextends: \fRtgt
|
|
.br
|
|
\fBreturned_by: \fRalias_target
|
|
.br
|
|
|
|
Opaque object returned by \fIalias_target\fR.
|
|
|
|
.RE
|
|
.P
|
|
.SS any
|
|
.RS 2
|
|
\fBreturned_by: \fRget_variable, get, get, get_cross_property, get_external_property, get_variable
|
|
.br
|
|
|
|
A placeholder representing all types.
|
|
This includes builtin, as well as returned objects.
|
|
|
|
.RE
|
|
.P
|
|
.SS bool
|
|
.RS 2
|
|
\fBreturned_by: \fRadd_languages, get_option, is_disabler, is_variable, found, get, get_unquoted, has, check_header, compiles, has_argument, has_function, has_function_attribute, has_header, has_header_symbol, has_link_argument, has_member, has_members, has_multi_arguments, has_multi_link_arguments, has_type, links, symbols_have_underscore_prefix, found, has_key, found, found, allowed, auto, disabled, enabled, is_even, is_odd, contains, can_run_host_binaries, has_exe_wrapper, has_external_property, is_cross_build, is_subproject, is_unity, found, compiled, contains, endswith, startswith, version_compare, found
|
|
.br
|
|
|
|
A boolean object which is either `true` or `false`
|
|
|
|
.RE
|
|
.P
|
|
.SS both_libs
|
|
.RS 2
|
|
since 0.46.0
|
|
.br
|
|
\fBextends: \fRlib
|
|
.br
|
|
\fBreturned_by: \fRboth_libraries
|
|
.br
|
|
|
|
Container for both a static and shared library.
|
|
|
|
.RE
|
|
.P
|
|
.SS build_machine
|
|
.RS 2
|
|
\fBextended_by: \fRhost_machine, target_machine
|
|
.br
|
|
|
|
Provides information about the build machine -- the machine that is doing the actual compilation.
|
|
See \fICross-compilation\fR[34].
|
|
|
|
Currently, these values are populated using
|
|
\fI`platform.system()`\fR[38] and
|
|
\fI`platform.machine()`\fR[39].
|
|
If you think the returned values for any of these are incorrect for
|
|
your system or CPU, or if your OS is not in the linked table, please
|
|
\fIfile a bug\fR[40] report
|
|
with details and we'll look into it.
|
|
|
|
.RE
|
|
.P
|
|
.SS build_tgt
|
|
.RS 2
|
|
\fBextends: \fRtgt
|
|
.br
|
|
\fBreturned_by: \fRbuild_target, shared_module
|
|
.br
|
|
\fBextended_by: \fRexe, jar, lib
|
|
.br
|
|
|
|
A build target is either an executable, shared library, static library,
|
|
both shared and static library or shared module.
|
|
|
|
.RE
|
|
.P
|
|
.SS cfg_data
|
|
.RS 2
|
|
\fBreturned_by: \fRconfiguration_data
|
|
.br
|
|
|
|
This object encapsulates
|
|
configuration values to be used for generating configuration files. A
|
|
more in-depth description can be found in the \fIthe configuration wiki
|
|
page\fR[8].
|
|
|
|
.RE
|
|
.P
|
|
.SS cmake
|
|
.RS 2
|
|
|
|
The CMake module
|
|
|
|
.RE
|
|
.P
|
|
.SS cmake_options
|
|
.RS 2
|
|
since 0.55.0
|
|
.br
|
|
\fBreturned_by: \fRsubproject_options
|
|
.br
|
|
|
|
Central configuration object for CMake subprojects
|
|
|
|
.RE
|
|
.P
|
|
.SS compiler
|
|
.RS 2
|
|
\fBreturned_by: \fRget_compiler
|
|
.br
|
|
|
|
This object is returned by \fImeson.get_compiler\fR.
|
|
It represents a compiler for a given language and allows you to query its properties.
|
|
|
|
\fBNOTES\fR
|
|
.RS 4
|
|
These compiler checks do not use compiler arguments added
|
|
with `add_*_arguments()`, via `-Dlang_args` on the command-line, or
|
|
through `CFLAGS`/`LDFLAGS`, etc in the environment. Hence, you can
|
|
trust that the tests will be fully self-contained, and won't fail
|
|
because of custom flags added by other parts of the build file or by
|
|
users.
|
|
Note that if you have a single prefix with all your dependencies, you
|
|
might find it easier to append to the environment variables
|
|
`C_INCLUDE_PATH` with GCC/Clang and `INCLUDE` with MSVC to expand the
|
|
default include path, and `LIBRARY_PATH` with GCC/Clang and `LIB` with
|
|
MSVC to expand the default library search path.
|
|
|
|
However, with GCC, these variables will be ignored when
|
|
cross-compiling. In that case you need to use a specs file. See:
|
|
http://www.mingw.org/wiki/SpecsFileHOWTO
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS custom_idx
|
|
.RS 2
|
|
\fBreturned_by: \fR[index]
|
|
.br
|
|
|
|
References a specific output file of a \fIcustom_tgt\fR object.
|
|
|
|
.RE
|
|
.P
|
|
.SS custom_tgt
|
|
.RS 2
|
|
\fBextends: \fRtgt
|
|
.br
|
|
\fBreturned_by: \fRcustom_target, vcs_tag
|
|
.br
|
|
|
|
This object is returned by \fIcustom_target\fR and contains a target with the following methods:
|
|
|
|
.RE
|
|
.P
|
|
.SS dep
|
|
.RS 2
|
|
\fBreturned_by: \fRdeclare_dependency, dependency, find_library, as_link_whole, as_system, partial_dependency
|
|
.br
|
|
|
|
Abstract representation of a dependency
|
|
|
|
.RE
|
|
.P
|
|
.SS dict
|
|
.RS 2
|
|
since 0.47.0
|
|
.br
|
|
|
|
Stores a mapping of strings to other objects. See \fIdictionaries\fR[41].
|
|
|
|
You can also iterate over dictionaries with the \fI`foreach`
|
|
statement\fR[28].
|
|
|
|
\fB(since 0.48.0)\fR Dictionaries can be added (e.g. `d1 = d2 + d3` and `d1 += d2`).
|
|
Values from the second dictionary overrides values from the first.
|
|
|
|
.RE
|
|
.P
|
|
.SS disabler
|
|
.RS 2
|
|
\fBreturned_by: \fRdisabler
|
|
.br
|
|
|
|
A disabler object is an object that behaves in much the same way as
|
|
NaN numbers do in floating point math. That is when used in any
|
|
statement (function call, logical op, etc) they will cause the
|
|
statement evaluation to immediately short circuit to return a disabler
|
|
object. A disabler object has one method:
|
|
|
|
.RE
|
|
.P
|
|
.SS env
|
|
.RS 2
|
|
\fBreturned_by: \fRenvironment
|
|
.br
|
|
|
|
This object is returned by \fIenvironment\fR and stores
|
|
detailed information about how environment variables should be set
|
|
during tests. It should be passed as the `env` keyword argument to
|
|
tests and other functions.
|
|
|
|
\fBSince 0.58.0\fR \fIenv.append\fR and \fIenv.prepend\fR can be called multiple times
|
|
on the same `varname`. Earlier Meson versions would warn and only the last
|
|
operation took effect.
|
|
|
|
\fBEXAMPLE\fR
|
|
.RS 4
|
|
|
|
.RS 4
|
|
env = environment()
|
|
.br
|
|
|
|
.br
|
|
# MY_PATH will be '0:1:2:3'
|
|
.br
|
|
env.set('MY_PATH', '1')
|
|
.br
|
|
env.append('MY_PATH', '2')
|
|
.br
|
|
env.append('MY_PATH', '3')
|
|
.br
|
|
env.prepend('MY_PATH', '0')
|
|
.br
|
|
.RE
|
|
|
|
.RE
|
|
.RE
|
|
.P
|
|
.SS exe
|
|
.RS 2
|
|
\fBextends: \fRbuild_tgt
|
|
.br
|
|
\fBreturned_by: \fRexecutable
|
|
.br
|
|
|
|
An executable
|
|
|
|
.RE
|
|
.P
|
|
.SS external_program
|
|
.RS 2
|
|
\fBreturned_by: \fRfind_program
|
|
.br
|
|
|
|
Opaque object representing an external program
|
|
|
|
.RE
|
|
.P
|
|
.SS extracted_obj
|
|
.RS 2
|
|
\fBreturned_by: \fRextract_all_objects, extract_objects
|
|
.br
|
|
|
|
Opaque object representing extracted object files from build targets
|
|
|
|
.RE
|
|
.P
|
|
.SS feature
|
|
.RS 2
|
|
since 0.47.0
|
|
.br
|
|
\fBreturned_by: \fRget_option, disable_auto_if, require
|
|
.br
|
|
|
|
Meson object representing a \fI`feature` options\fR[0]
|
|
|
|
.RE
|
|
.P
|
|
.SS file
|
|
.RS 2
|
|
\fBreturned_by: \fRconfigure_file
|
|
.br
|
|
|
|
Opaque object that stores the path to an existing file
|
|
|
|
.RE
|
|
.P
|
|
.SS generated_list
|
|
.RS 2
|
|
\fBreturned_by: \fRprocess
|
|
.br
|
|
|
|
Opaque object representing the result of a \fIgenerator.process\fR call.
|
|
|
|
.RE
|
|
.P
|
|
.SS generator
|
|
.RS 2
|
|
\fBreturned_by: \fRgenerator
|
|
.br
|
|
|
|
This object is returned by \fIgenerator\fR and contains a
|
|
generator that is used to transform files from one type to another by
|
|
an executable (e.g. `idl` files into source code and headers).
|
|
|
|
.RE
|
|
.P
|
|
.SS host_machine
|
|
.RS 2
|
|
\fBextends: \fRbuild_machine
|
|
.br
|
|
|
|
Provides information about the host machine -- the machine on which the
|
|
compiled binary will run. See
|
|
\fICross-compilation\fR[34].
|
|
|
|
It has the same methods as \fIbuild_machine\fR.
|
|
|
|
When not cross-compiling, all the methods return the same values as
|
|
\fIbuild_machine\fR (because the build machine is the host machine)
|
|
|
|
Note that while cross-compiling, it simply returns the values defined
|
|
in the cross-info file.
|
|
|
|
.RE
|
|
.P
|
|
.SS inc
|
|
.RS 2
|
|
\fBreturned_by: \fRinclude_directories, private_dir_include
|
|
.br
|
|
|
|
Opaque wrapper for storing include directories
|
|
|
|
.RE
|
|
.P
|
|
.SS int
|
|
.RS 2
|
|
\fBreturned_by: \fRget_option, to_int, get, get_unquoted, alignment, compute_int, sizeof, length, returncode, to_int
|
|
.br
|
|
|
|
All integer numbers. See \fINumbers\fR[42] for more information.
|
|
|
|
.RE
|
|
.P
|
|
.SS jar
|
|
.RS 2
|
|
\fBextends: \fRbuild_tgt
|
|
.br
|
|
\fBreturned_by: \fRjar
|
|
.br
|
|
|
|
A Java JAR build target
|
|
|
|
.RE
|
|
.P
|
|
.SS lib
|
|
.RS 2
|
|
\fBextends: \fRbuild_tgt
|
|
.br
|
|
\fBreturned_by: \fRlibrary, shared_library, static_library, get_shared_lib, get_static_lib
|
|
.br
|
|
\fBextended_by: \fRboth_libs
|
|
.br
|
|
|
|
Represents either a shared or static library
|
|
|
|
.RE
|
|
.P
|
|
.SS list
|
|
.RS 2
|
|
\fBreturned_by: \fRfiles, get_option, keys, cmd_array, first_supported_argument, first_supported_link_argument, get_supported_arguments, get_supported_function_attributes, get_supported_link_arguments, preprocess, to_list, keys, project_license, split
|
|
.br
|
|
|
|
An array of elements. See \fIarrays\fR[43].
|
|
|
|
.RE
|
|
.P
|
|
.SS meson
|
|
.RS 2
|
|
|
|
The `meson` object allows you to introspect various properties of the
|
|
system. This object is always mapped in the `meson` variable.
|
|
|
|
.RE
|
|
.P
|
|
.SS module
|
|
.RS 2
|
|
\fBreturned_by: \fRimport
|
|
.br
|
|
|
|
Base type for all modules.
|
|
|
|
Modules provide their own specific implementation methods, but all modules
|
|
proivide the following methods:
|
|
|
|
.RE
|
|
.P
|
|
.SS range
|
|
.RS 2
|
|
since 0.58.0
|
|
.br
|
|
\fBreturned_by: \fRrange
|
|
.br
|
|
|
|
Opaque object that can be used in a loop and accessed via `[num]`.
|
|
|
|
.RE
|
|
.P
|
|
.SS run_tgt
|
|
.RS 2
|
|
\fBextends: \fRtgt
|
|
.br
|
|
\fBreturned_by: \fRrun_target
|
|
.br
|
|
|
|
Opaque object returned by \fIrun_target\fR.
|
|
|
|
.RE
|
|
.P
|
|
.SS runresult
|
|
.RS 2
|
|
\fBreturned_by: \fRrun_command, run
|
|
.br
|
|
|
|
This object encapsulates the result of trying to compile and run a
|
|
sample piece of code with \fIcompiler.run\fR or
|
|
\fIrun_command\fR.
|
|
|
|
.RE
|
|
.P
|
|
.SS str
|
|
.RS 2
|
|
\fBreturned_by: \fRget_option, join_paths, to_string, cpu, cpu_family, endian, system, full_path, name, path, get, get_unquoted, get_argument_syntax, get_define, get_id, get_linker_id, version, full_path, full_path, get_configtool_variable, get_pkgconfig_variable, get_variable, include_type, name, type_name, version, full_path, path, version, to_string, backend, build_root, current_build_dir, current_source_dir, global_build_root, global_source_root, project_build_root, project_name, project_source_root, project_version, source_root, version, stderr, stdout, format, join, replace, strip, substring, to_lower, to_upper, underscorify
|
|
.br
|
|
|
|
All \fIstrings\fR[44] have the following methods. Strings
|
|
are immutable, all operations return their results as a new string.
|
|
|
|
.RE
|
|
.P
|
|
.SS structured_src
|
|
.RS 2
|
|
\fBreturned_by: \fRstructured_sources
|
|
.br
|
|
|
|
Opaque object returned by \fIstructured_sources\fR.
|
|
|
|
.RE
|
|
.P
|
|
.SS subproject
|
|
.RS 2
|
|
\fBreturned_by: \fRsubproject
|
|
.br
|
|
|
|
This object is returned by \fIsubproject\fR and is an opaque object representing it.
|
|
|
|
.RE
|
|
.P
|
|
.SS target_machine
|
|
.RS 2
|
|
\fBextends: \fRbuild_machine
|
|
.br
|
|
|
|
Provides information about the target machine -- the machine on which
|
|
the compiled binary's output will run. Hence, this object should only
|
|
be used while cross-compiling a compiler. See
|
|
\fICross-compilation\fR[34].
|
|
|
|
It has the same methods as \fIbuild_machine\fR.
|
|
|
|
When all compilation is 'native', all the methods return the same
|
|
values as \fIbuild_machine\fR (because the build machine is the host
|
|
machine and the target machine).
|
|
|
|
Note that while cross-compiling, it simply returns the values defined
|
|
in the cross-info file. If `target_machine` values are not defined in
|
|
the cross-info file, `host_machine` values are returned instead.
|
|
|
|
.RE
|
|
.P
|
|
.SS tgt
|
|
.RS 2
|
|
\fBextended_by: \fRalias_tgt, build_tgt, custom_tgt, run_tgt
|
|
.br
|
|
|
|
Opaque base object for all Meson targets
|
|
|
|
.RE
|
|
.P
|
|
.SS void
|
|
.RS 2
|
|
\fBreturned_by: \fRadd_global_arguments, add_global_link_arguments, add_project_arguments, add_project_dependencies, add_project_link_arguments, add_test_setup, assert, benchmark, debug, error, install_data, install_emptydir, install_headers, install_man, install_subdir, install_symlink, message, project, set_variable, subdir, subdir_done, summary, test, unset_variable, warning, merge_from, set, set10, set_quoted, add_cmake_defines, append, prepend, set, add_devenv, add_dist_script, add_install_script, add_postconf_script, install_dependency_manifest, override_dependency, override_find_program
|
|
.br
|
|
|
|
Indicates that the function does not return anything.
|
|
Similar to `void` in C and C++
|
|
|
|
.RE
|
|
.P
|
|
.SH SEE ALSO
|
|
[1] Build-options.md#features
|
|
.br
|
|
[2] Unit-tests.md
|
|
.br
|
|
[3] https://www.testanything.org/
|
|
.br
|
|
[4] https://ninja-build.org/manual.html#ref_dependencies
|
|
.br
|
|
[5] https://ninja-build.org/manual.html#ref_headers
|
|
.br
|
|
[6] https://dlang.org/spec/version.html#version
|
|
.br
|
|
[7] https://gcc.gnu.org/wiki/Visibility
|
|
.br
|
|
[8] https://docs.microsoft.com/en-us/cpp/build/reference/subsystem-specify-subsystem
|
|
.br
|
|
[9] Configuration.md
|
|
.br
|
|
[10] https://docs.python.org/3/library/codecs.html#standard-encodings
|
|
.br
|
|
[11] https://ninja-build.org/manual.html#_the_literal_console_literal_pool
|
|
.br
|
|
[12] Dependencies.md#cmake
|
|
.br
|
|
[13] Dependencies.md#dependencies-with-custom-lookup-functionality
|
|
.br
|
|
[14] Wrap-dependency-system-manual.md#provide-section
|
|
.br
|
|
[15]
|
|
Dependencies.md#dependencies-with-custom-lookup-functionality
|
|
.br
|
|
[16] Builtin-options.md#core-options
|
|
.br
|
|
[17] Machine-files.md#binaries
|
|
.br
|
|
[18] Build-options.md
|
|
.br
|
|
[19] Builtin-options.md#universal-options
|
|
.br
|
|
[20] Installing.md
|
|
.br
|
|
[21] https://mesonbuild.com/Builtin-options.html
|
|
.br
|
|
[22] https://spdx.dev/ids/
|
|
.br
|
|
[23] https://spdx.org/licenses/
|
|
.br
|
|
[24] External-commands.md
|
|
.br
|
|
[25] Subprojects.md
|
|
.br
|
|
[26] http://man7.org/linux/man-pages/man3/mallopt.3.html
|
|
.br
|
|
[27] Reference-tables.md#cpu-families
|
|
.br
|
|
[28] Reference-tables.md#operating-system-names
|
|
.br
|
|
[29] Syntax.md#foreach-statements
|
|
.br
|
|
[30] Reference-tables.md#compiler-ids
|
|
.br
|
|
[31] Reference-tables.md#linker-ids
|
|
.br
|
|
[32] Reference-tables.md#gcc-__attribute__
|
|
.br
|
|
[33] Commands.md#devenv
|
|
.br
|
|
[34] Reference-tables.md#language-arguments-parameter-names
|
|
.br
|
|
[35] Cross-compilation.md
|
|
.br
|
|
[36] Unity-builds.md
|
|
.br
|
|
[37] Syntax.md#string-formatting
|
|
.br
|
|
[38] https://docs.python.org/3.7/library/platform.html#platform.system
|
|
.br
|
|
[39] https://docs.python.org/3.7/library/platform.html#platform.machine
|
|
.br
|
|
[40] https://github.com/mesonbuild/meson/issues/new
|
|
.br
|
|
[41] Syntax.md#dictionaries
|
|
.br
|
|
[42] Syntax.md#numbers
|
|
.br
|
|
[43] Syntax.md#arrays
|
|
.br
|
|
[44] Syntax.md#strings
|
|
.br
|