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

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


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

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

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

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

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

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

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

- 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_inherit: _build_target_base
  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