| 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_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 |
| # sinec: 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 |