Dependency object (dep)

Abstract representation of a dependency

Returned by

Dependency object objects are returned by the following functions and methods:

Dependency object methods

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.

Signature

(since 0.56.0)

dep as_link_whole()


dep.as_system()

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

Signature

(since 0.52.0)

# Returns a copy of the dependency object, which has changed the value of `include_type`
dep as_system(
  str [value],   # The new value. See dependency() for supported values.
)

Arguments

The method dep.as_system() accepts the following positional arguments:

Name Type Description Tags
value str

The new value. See dependency() for supported values.

[optional]


dep.found()

Returns whether the dependency was found.

Signature

bool found()


dep.get_configtool_variable()

Gets the command line argument from the config tool (with -- prepended), or, if invoked on a non config-tool dependency, error out.

Signature

(since 0.44.0)

DEPRECATED

in 0.56.0

# Gets the command line argument from the config tool (with `--` prepended), or,
str get_configtool_variable(
  str var_name,     # Name of the variable to query
)

Arguments

The method dep.get_configtool_variable() accepts the following positional arguments:

Name Type Description Tags
var_name str

Name of the variable to query


dep.get_pkgconfig_variable()

Gets the pkg-config variable specified, or, if invoked on a non pkg-config dependency, error out.

Signature

(since 0.36.0)

DEPRECATED

in 0.56.0

# Gets the pkg-config variable specified,
str get_pkgconfig_variable(
  str var_name,     # Name of the variable to query

  # Keyword arguments:
  default         : str        # The value to return if the variable was not found
  define_variable : list[str]  # You can also redefine a
)

Arguments

The method dep.get_pkgconfig_variable() accepts the following positional arguments:

Name Type Description Tags
var_name str

Name of the variable to query

Finally, dep.get_pkgconfig_variable() accepts the following keyword arguments:

Name Type Description Tags
default str

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.

(since 0.45.0)

define_variable list[str]

You can also redefine a variable by passing a list to this kwarg that can affect the retrieved variable: ['prefix', '/']).

(since 0.44.0)


dep.get_variable()

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.

Signature

(since 0.51.0)

# A generic variable getter method, which replaces the
str get_variable(
  str [varname],   # This argument is used as a default value

  # Keyword arguments:
  cmake            : str        # The CMake variable name
  configtool       : str        # The configtool variable name
  default_value    : str        # The default value to return when the variable does not exist
  internal         : str        # The internal variable name
  pkgconfig        : str        # The pkgconfig variable name
  pkgconfig_define : list[str]  # See dep.get_pkgconfig_variable()
)

Arguments

The method dep.get_variable() accepts the following positional arguments:

Name Type Description Tags
varname str

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

(since 0.58.0)

[optional]

Finally, dep.get_variable() accepts the following keyword arguments:

Name Type Description Tags
cmake str

The CMake variable name

configtool str

The configtool variable name

default_value str

The default value to return when the variable does not exist

internal str

The internal variable name

(since 0.54.0)

pkgconfig str

The pkgconfig variable name

pkgconfig_define list[str]

See dep.get_pkgconfig_variable()


dep.include_type()

Returns the value set by the include_type kwarg.

Signature

(since 0.52.0)

str include_type()


dep.name()

Returns the name of the dependency that was searched. Returns 'internal' for dependencies created with declare_dependency().

Signature

(since 0.48.0)

str name()


dep.partial_dependency()

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:

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

Signature

(since 0.46.0)

# Returns a new dependency object with the same name, version, found status,
dep partial_dependency(
  compile_args : bool  # Whether to include compile_args
  includes     : bool  # Whether to include includes
  link_args    : bool  # Whether to include link_args
  links        : bool  # Whether to include links
  sources      : bool  # Whether to include sources
)
Warning:

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

Arguments

The method dep.partial_dependency() accepts the following keyword arguments:

Name Type Description Tags
compile_args bool

Whether to include compile_args

default = false

includes bool

Whether to include includes

default = false

link_args bool

Whether to include link_args

default = false

links bool

Whether to include links

default = false

sources bool

Whether to include sources

default = false


dep.type_name()

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.

Signature

str type_name()


dep.version()

the version number as a string, for example 1.2.8. unknown if the dependency provider doesn't support determining the version.

Signature

str version()


The results of the search are