docs: Add docs for Dependency.get_variable

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

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

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
+```