Chiebot-Mirror
/
meson
mirror of https://github.com/mesonbuild/meson.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity
The Meson Build System http://mesonbuild.com/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
15087 Commits
76 Branches
171 Tags
76 MiB
 
 
 
 
 
 
Tag: Branch: Tree: 8c5505c28a
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '8c5505c28a'
${ noResults }
meson/docs/yaml/objects/compiler.yaml

710 lines
21 KiB
Raw Blame History

name: compiler
long_name: Compiler object
description: |
This object is returned by [[meson.get_compiler]].
It represents a compiler for a given language and allows you to query its properties.
notes:
- |
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
methods:
# Helper methods to pre-define common posargs
- name: _code
returns: void
description: You have found a bug if you can see this!
posargs:
code:
type: str | file
description: |
The source code to check.
If a string is passed, the code is used directly. If a [[@file]] object
is passed, its content is used for the compiler check.
# Helper methods to pre-define common kwargs
- name: _args
returns: void
description: You have found a bug if you can see this!
kwargs:
args:
type: list[str]
description: |
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`.
- name: _include_directories
returns: void
description: You have found a bug if you can see this!
kwargs:
include_directories:
type: inc | list[inc]
since: 0.38.0
description: Extra directories for header searches.
- name: _dependencies
returns: void
description: You have found a bug if you can see this!
kwargs:
dependencies:
type: dep | list[dep]
description: Additionally dependencies required for compiling and / or linking.
- name: _prefix
returns: void
description: You have found a bug if you can see this!
kwargs:
prefix:
type: str | list[str]
description: |
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).
- name: _no_builtin_args
returns: void
description: You have found a bug if you can see this!
kwargs:
no_builtin_args:
type: bool
default: false
description: When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
- name: _name
returns: void
description: You have found a bug if you can see this!
kwargs:
name:
type: str
description: |
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.
# Even more convenient
- name: _common
returns: void
description: You have found a bug if you can see this!
kwargs_inherit:
- compiler._args
- compiler._include_directories
- compiler._dependencies
- compiler._no_builtin_args
- compiler._prefix
- name: _compiles
returns: void
description: You have found a bug if you can see this!
kwargs:
required:
type: bool | feature
default: false
since: 1.5.0
description:
When set to `true`, Meson will halt if the check fails.
When set to a [`feature`](Build-options.md#features) option, the feature
will control if it is searched and whether to fail if not found.
kwargs_inherit:
- compiler._args
- compiler._include_directories
- compiler._dependencies
- compiler._no_builtin_args
- compiler._name
- compiler._werror
- name: _header
returns: void
description: You have found a bug if you can see this!
kwargs_inherit: compiler._common
kwargs:
required:
type: bool | feature
default: false
since: 0.50.0
description:
When set to `true`, Meson will halt if the header check fails.
When set to a [`feature`](Build-options.md#features) option, the feature
will control if it is searched and whether to fail if not found.
- name: _required
returns: void
description: You have found a bug if you can see this!
kwargs:
required:
type: bool | feature
default: false
since: 1.3.0
description:
When set to `true`, Meson will halt if the check fails.
When set to a [`feature`](Build-options.md#features) option, the feature
will control if it is searched and whether to fail if not found.
- name: _werror
returns: void
description: You have found a bug if you can see this!
kwargs:
werror:
type: bool
default: false
description: When set to `true`, compiler warnings are treated as error.
since: 1.3.0
# Star of the actual functions
- name: version
returns: str
description: Returns the compiler's version number as a string.
- name: cmd_array
returns: list[str]
description: Returns an array containing the command(s) for the compiler.
- name: alignment
returns: int
description: |
Returns the alignment of the specified type. For C-like languages,
For C-like languages, the header `stddef.h` and `stdio.h` are included
implicitly for native compilation, only `stddef.h` is included when
cross-compiling.
posargs:
typename:
type: str
description: The name of the type to check.
kwargs_inherit:
- compiler._args
- compiler._prefix
- compiler._dependencies
# TODO: why not also allow passing `include_directories`?
- name: run
returns: runresult
description: Attempts to compile and execute the given code fragment.
posargs_inherit: compiler._code
kwargs_inherit: compiler._compiles
- name: get_id
returns: str
description: |
Returns a string identifying the compiler.
For example, `gcc`, `msvc`, [and more](Reference-tables.md#compiler-ids).
- name: get_linker_id
returns: str
since: 0.53.0
description: |
Returns a string identifying the linker.
For example, `ld.bfd`, `link`, [and more](Reference-tables.md#linker-ids).
- name: symbols_have_underscore_prefix
returns: bool
since: 0.37.0
description: Returns `true` if the C symbol mangling is one underscore (`_`) prefixed to the symbol.
- name: has_member
returns: bool
description: Returns true if the type has the specified member.
kwargs_inherit:
- compiler._common
- compiler._required
posargs:
typename:
type: str
description: The type to check.
membername:
type: str
description: The member to check.
- name: has_members
returns: bool
description: Returns `true` if the type has *all* the specified members.
kwargs_inherit:
- compiler._common
- compiler._required
posargs:
typename:
type: str
description: The type to check.
varargs:
name: member
type: str
min_varargs: 1
description: The members to check
- name: has_function
returns: bool
description: |
Returns true if the given function is provided
by the standard library or a library passed in with the `args` keyword.
kwargs_inherit:
- compiler._common
- compiler._required
posargs:
funcname:
type: str
description: The function to check.
- name: has_type
returns: bool
description: Returns `true` if the specified token is a type.
kwargs_inherit:
- compiler._common
- compiler._required
posargs:
typename:
type: str
description: The type to check.
- name: compute_int
returns: int
since: 0.40.0
kwargs_inherit: compiler._common
description: |
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.
For C-like languages, the header `stddef.h` and `stdio.h` are included
implicitly for native compilation, only `stddef.h` is included when
cross-compiling.
posargs:
expr:
type: str
description: The expression to compute.
kwargs:
low:
type: int
default: -1024
description: The min value.
high:
type: int
default: 1024
description: The max value.
guess:
type: int
description: The value to try first.
- name: sizeof
returns: int
description: |
returns the size of the given type (e.g. `'int'`) or -1 if the type is unknown.
For C-like languages, the header `stddef.h` and `stdio.h` are included
implicitly for native compilation, only `stddef.h` is included when
cross-compiling.
kwargs_inherit: compiler._common
posargs:
typename:
type: str
description: The type to compute.
- name: get_define
returns: str
since: 0.40.0
description: |
Returns the given preprocessor symbol's value
as a string or empty string if it is not defined.
*(since 0.47.0)* This method will concatenate string literals as
the compiler would. E.g. `"a" "b"` will become `"ab"`.
kwargs_inherit: compiler._common
posargs:
definename:
type: str
description: The define to check.
- name: has_define
returns: bool
since: 1.3.0
description: |
Returns true if the given preprocessor symbol is *defined*.
kwargs_inherit: compiler._common
posargs:
definename:
type: str
description: The define to check.
- name: compiles
returns: bool
description: Returns true if the code compiles.
posargs_inherit: compiler._code
kwargs_inherit: compiler._compiles
- name: links
returns: bool
description: |
Returns true if the code compiles and links.
*Since 0.60.0*, 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.
posargs_inherit: compiler._code
kwargs_inherit: compiler._compiles
- name: check_header
returns: bool
since: 0.47.0
description: |
Returns true if the specified header is *usable*
with the specified prefix, dependencies, and arguments.
kwargs_inherit: compiler._header
posargs:
header_name:
type: str
description: The header to check.
- name: has_header
returns: bool
description: |
Returns true if the specified header is *exists*
with the specified prefix, dependencies, and arguments.
This method is faster than [[compiler.check_header]] since it only does a
pre-processor check.
kwargs_inherit: compiler._header
posargs_inherit: compiler.check_header
- name: has_header_symbol
returns: bool
description: |
Detects whether a particular symbol is declared in the specified header.
Symbols here include function, variable, `#define`, type definition, etc.
kwargs_inherit: compiler._header
posargs:
header:
type: str
description: The header to check.
symbol:
type: str
description: The symbol to check.
- name: find_library
returns: dep
description: Tries to find the library specified in the positional argument.
posargs:
libname:
type: str
description: The library to find.
kwargs:
required:
type: bool | feature
default: true
description: |
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 [`feature`](Build-options.md#features) option, the feature
will control if it is searched and whether to fail if not found.
*(since 0.47.0)* The value of a `feature` option can also be passed here.
has_headers:
type: list[str]
since: 0.50.0
description: |
List of headers that must be found as well.
This check is equivalent to checking each header with a
[[compiler.has_header]] call.
When used, kwargs that [[compiler.has_header]] would accept can be
passed here prefixed with `header_`, and will have the same effect on
the header check.
static:
type: bool
default: false
since: 0.51.0
description: |
If `true`, the search is limited to static libraries only.
Setting this value to `false` (the default) will search for both shared
*and* static libraries.
disabler:
type: bool
default: false
since: 0.49.0
description: If `true`, this method will return a [[@disabler]] on a failed check.
dirs:
type: list[str]
description: |
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.
# does not work, since all _common kwargs need to be prefixed `header_` here
# kwargs_inherit: compiler._common
header_args:
type: list[str]
since: 0.51.0
description: |
When the `has_headers` kwarg is also used, this argument is passed to
[[compiler.has_header]] as `args`.
header_include_directories:
type: inc | list[inc]
since: 0.51.0
description: |
When the `has_headers` kwarg is also used, this argument is passed to
[[compiler.has_header]] as `include_directories`.
header_dependencies:
type: dep | list[dep]
since: 0.51.0
description: |
When the `has_headers` kwarg is also used, this argument is passed to
[[compiler.has_header]] as `dependencies`.
header_no_builtin_args:
type: bool
default: false
since: 0.51.0
description: |
When the `has_headers` kwarg is also used, this argument is passed to
[[compiler.has_header]] as `no_builtin_args`.
header_prefix:
type: str
since: 0.51.0
description: |
When the `has_headers` kwarg is also used, this argument is passed to
[[compiler.has_header]] as `prefix`.
# Compiler arguments
- name: has_argument
returns: bool
description: |
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.
posargs:
argument:
type: str
description: The argument to check.
kwargs_inherit:
- compiler._required
- name: has_multi_arguments
since: 0.37.0
returns: bool
description: |
the same as [[compiler.has_argument]] but takes multiple arguments
and uses them all in a single compiler invocation.
varargs:
name: arg
type: str
description: The arguments to check.
kwargs_inherit:
- compiler._required
- name: get_supported_arguments
returns: list[str]
since: 0.43.0
varargs_inherit: compiler.has_multi_arguments
description: |
Returns an array containing only the arguments supported by the compiler,
as if [[compiler.has_argument]] were called on them individually.
kwargs:
checked:
type: str
since: 0.59.0
default: "'off'"
description: |
Supported values:
- `'off'`: Quietly ignore unsupported arguments
- `'warn'`: Print a warning for unsupported arguments
- `'require'`: Abort if at least one argument is not supported
- name: first_supported_argument
returns: list[str]
since: 0.43.0
varargs_inherit: compiler.has_multi_arguments
description: |
Given a list of strings, returns a single-element list containing the first
argument that passes the [[compiler.has_argument]] test or an empty array if
none pass.
# Linker arguments
- name: has_link_argument
since: 0.46.0
returns: bool
description: |
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.
posargs:
argument:
type: str
description: The argument to check.
kwargs_inherit:
- compiler._required
- name: has_multi_link_arguments
since: 0.46.0
returns: bool
description: |
the same as [[compiler.has_link_argument]] but takes multiple arguments
and uses them all in a single compiler invocation.
varargs:
name: arg
type: str
description: The link arguments to check.
kwargs_inherit:
- compiler._required
- name: get_supported_link_arguments
returns: list[str]
since: 0.46.0
varargs_inherit: compiler.has_multi_link_arguments
description: |
Returns an array containing only the arguments supported by the compiler,
as if [[compiler.has_link_argument]] were called on them individually.
# TODO: why is this not present here?
# kwargs:
# checked:
# type: str
# since: 0.59.0
# default: "'off'"
# description: |
# Supported values:
# - `'off'`: Quietly ignore unsupported arguments
# - `'warn'`: Print a warning for unsupported arguments
# - `'require'`: Abort if at least one argument is not supported
- name: first_supported_link_argument
returns: list[str]
since: 0.46.0
varargs_inherit: compiler.has_multi_link_arguments
description: |
Given a list of strings, returns the first argument that passes the
[[compiler.has_link_argument]] test or an empty array if none pass.
- name: has_function_attribute
returns: bool
since: 0.48.0
description: |
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.
[This table](Reference-tables.md#gcc-__attribute__) lists all of the supported attributes.
posargs:
name:
type: str
description: The attribute name to check.
kwargs_inherit:
- compiler._required
- name: get_supported_function_attributes
returns: list[str]
since: 0.48.0
description: |
Returns an array containing any names that are supported GCC style attributes.
Equivalent to [[compiler.has_function_attribute]] was called on each of
them individually.
# TODO: Again why doesn't this function have the checked kwarg?
- name: get_argument_syntax
returns: str
since: 0.49.0
description: |
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.
- name: preprocess
returns: list[custom_idx]
since: 0.64.0
description: |
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`.
varargs:
name: source
type: str | file | custom_tgt | custom_idx | generated_list
description: |
Input source to preprocess. The following types are supported:
- Strings relative to the current source directory
- [[@file]] objects defined in any preceding build file
- The return value of configure-time generators such as [[configure_file]]
- The return value of build-time generators such as
[[custom_target]] or [[generator.process]]
kwargs_inherit:
- compiler._include_directories
kwargs:
output:
type: str
description: |
Template for name of preprocessed files: `@PLAINNAME@` is replaced by
the source filename and `@BASENAME@` is replaced by the source filename
without its extension.
compile_args:
type: list[str]
description: |
Extra flags to pass to the preprocessor
dependencies:
type: dep | list[dep]
description: Additionally dependencies required.
since: 1.1.0
depends:
type: list[build_tgt | custom_tgt]
description: |
Specifies that this target depends on the specified
target(s). These targets should be built before starting
to preprocess an input.
since: 1.4.0