diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 50dbcf501..0cdd353da 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -64,6 +64,29 @@ pkg-config files. Meson has autodetection support for some of these, and they are described [later in this page](#dependencies-with-custom-lookup-functionality). +# Arbitrary variables from dependencies that can be found multiple ways + +*Note* new in 0.51.0 + +When you need to get an arbitrary variables from a dependency that can be +found multiple ways and you don't want to constrain the type you can use +the generic `get_variable` method. This currently supports cmake, pkg-config, +and config-tool based variables. + +```meson +foo_dep = dependency('foo') +var = foo.get_variable(cmake : 'CMAKE_VAR', pkgconfig : 'pkg-config-var', configtool : 'get-var', default_value : 'default') +``` + +It accepts the keywords 'cmake', 'pkgconfig', 'pkgconfig_define', +'configtool', and 'default_value'. 'pkgconfig_define' works just like the +'define_variable' argument to `get_pkgconfig_variable`. When this method is +invoked the keyword corresponding to the underlying type of the dependency +will be used to look for a variable. If that variable cannot be found or if +the caller does not provide an argument for the type of dependency, one of +the following will happen: If 'default_value' was provided that value will be +returned, if 'default_value' was not provided then an error will be raised. + # Declaring your own You can declare your own dependency objects that can be used diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 01fa3c38d..29da7c68e 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -2185,6 +2185,14 @@ an external dependency with the following methods: - includes: any include_directories - sources: any compiled or static sources the dependency has + - `get_variable(cmake : str, pkgconfig : str, configtool : str, + default_value : str, pkgconfig_define : [str, str]) *(Added in 0.51.0)* A + generic variable getter method, which repalces 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. + ### `disabler` object A disabler object is an object that behaves in much the same way as diff --git a/docs/markdown/snippets/dependency_get_variable_method.md b/docs/markdown/snippets/dependency_get_variable_method.md new file mode 100644 index 000000000..5804865cf --- /dev/null +++ b/docs/markdown/snippets/dependency_get_variable_method.md @@ -0,0 +1,17 @@ +## Dependency objects now have a get_variable method + +This is a generic replacement for type specific variable getters such as +`ConfigToolDependency.get_configtool_variable` and +`PkgConfigDependency.get_pkgconfig_variable`, and is the only way to query +such variables from cmake dependencies. + +This method allows you to get variables without knowing the kind of +dependency you have. + +```meson +dep = dependency('could_be_cmake_or_pkgconfig') +# cmake returns 'YES', pkg-config returns 'ON' +if ['YES', 'ON'].contains(dep.get_variable(pkg-config : 'var-name', cmake : 'COP_VAR_NAME', default : 'NO')) + error('Cannot build your project when dep is built with var-name support') +endif +```