name: dep
long_name: Dependency object
description: Abstract representation of a dependency

methods:
  - name: found
    returns: bool
    description: Returns whether the dependency was found.

  - name: name
    since: 0.48.0
    returns: str
    description: |
      Returns the name of the dependency that was searched.
      Returns `'internal'` for dependencies created with
      [[declare_dependency]].

  - name: get_pkgconfig_variable
    since: 0.36.0
    deprecated: 0.56.0
    returns: str
    description: |
      Gets the pkg-config variable specified,
      or, if invoked on a non pkg-config
      dependency, error out.

    posargs:
      var_name:
        type: str
        description: Name of the variable to query

    kwargs:
      define_variable:
        type: list[str]
        since: 0.44.0
        description: |
          You can also redefine a
          variable by passing a list to this kwarg
          that can affect the retrieved variable: `['prefix', '/'])`.

          *(Since 1.3.0)* Multiple variables can be specified in pairs.

      default:
        type: str
        since: 0.45.0
        description: |
          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.

  - name: get_configtool_variable
    since: 0.44.0
    deprecated: 0.56.0
    returns: str
    description: |
      Gets the command line argument from the config tool (with `--` prepended), or,
      if invoked on a non config-tool dependency, error out.

    posargs:
      var_name:
        type: str
        description: Name of the variable to query

  - name: type_name
    returns: str
    description: |
      Returns a string describing the type of the
      dependency, the most common values are `internal` for deps created
      with [[declare_dependency]] and `pkgconfig` for system dependencies
      obtained with Pkg-config.

  - name: version
    returns: str
    description: |
      the version number as a string,
      for example `1.2.8`.
      `unknown` if the dependency provider doesn't support determining the
      version.

  - name: include_type
    returns: str
    since: 0.52.0
    description: Returns the value set by the `include_type` kwarg.

  - name: as_system
    returns: dep
    since: 0.52.0
    description: |
      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'`.

    optargs:
      value:
        type: str
        description: The new value. See [[dependency]] for supported values.

  - name: as_link_whole
    returns: dep
    since: 0.56.0
    description: |
      Only dependencies created with [[declare_dependency]],
      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.

  - name: partial_dependency
    returns: dep
    since: 0.46.0
    description: |
      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:

      ```meson
      dep1 = declare_dependency(compile_args : '-Werror=foo', link_with : 'libfoo')
      dep2 = declare_dependency(compile_args : '-Werror=bar', dependencies : dep1)
      dep3 = dep2.partial_dependency(compile_args : true)
      ```

      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
      - link_args: any arguments passed to the linker
      - links: anything passed via link_with or link_whole
      - includes: any include_directories
      - sources: any compiled or static sources the dependency has

    warnings:
      - A bug present until 0.50.1 results in the above behavior
        not working correctly.

    kwargs:
      compile_args:
        type: bool
        default: false
        description: Whether to include compile_args

      link_args:
        type: bool
        default: false
        description: Whether to include link_args

      links:
        type: bool
        default: false
        description: Whether to include links

      includes:
        type: bool
        default: false
        description: Whether to include includes

      sources:
        type: bool
        default: false
        description: Whether to include sources

  - name: get_variable
    returns: str
    since: 0.51.0
    description: |
      A generic variable getter method, which replaces the
      `get_*type*_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.

    warnings:
      - Before 1.3.0, specifying multiple pkgconfig_define pairs would silently
        malform the results. Only the first variable would be redefined, but
        its value would contain both the second variable name, as well as its
        value.

    optargs:
      varname:
        type: str
        since: 0.58.0
        description: |
          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')`.

    kwargs:
      cmake:
        type: str
        description: The CMake variable name

      pkgconfig:
        type: str
        description: The pkgconfig variable name

      configtool:
        type: str
        description: The configtool variable name

      internal:
        type: str
        since: 0.54.0
        description: The internal variable name

      default_value:
        type: str
        description: The default value to return when the variable does not exist

      pkgconfig_define:
        type: list[str]
        description: See [[dep.get_pkgconfig_variable]]