diff options
Diffstat (limited to 'docs/yaml/objects/dep.yaml')
| -rw-r--r-- | docs/yaml/objects/dep.yaml | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/docs/yaml/objects/dep.yaml b/docs/yaml/objects/dep.yaml new file mode 100644 index 0000000..23092c2 --- /dev/null +++ b/docs/yaml/objects/dep.yaml @@ -0,0 +1,212 @@ +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', '/'])`. + + 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. + + 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 davault value to return when the variable does not exist + + pkgconfig_define: + type: list[str] + description: See [[dep.get_pkgconfig_variable]] |