docs: Add documentation for variables keyword

In declare_dependency() and dependency.get_variables().

3 files changed, 42 insertions, 13 deletions

diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md
index e029a84..d21bb97 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -67,6 +67,7 @@ page](#dependencies-with-custom-lookup-functionality).
 # Arbitrary variables from dependencies that can be found multiple ways
 
 *Note* new in 0.51.0
+*new in 0.54.0, the `internal` keyword*
 
 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
@@ -79,13 +80,14 @@ var = foo.get_variable(cmake : 'CMAKE_VAR', pkgconfig : 'pkg-config-var', config
 ```
 
 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.
+'configtool', 'internal', 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
 
@@ -289,16 +291,16 @@ libraries that have been compiled for single-threaded use instead.
 
 *(added 0.53.0)*
 
-Enables compiling and linking against the CUDA Toolkit. The `version` 
-and `modules` keywords may be passed to request the use of a specific 
+Enables compiling and linking against the CUDA Toolkit. The `version`
+and `modules` keywords may be passed to request the use of a specific
 CUDA Toolkit version and/or additional CUDA libraries, correspondingly:
 
 ```meson
 dep = dependency('cuda', version : '>=10', modules : ['cublas'])
 ```
 
-Note that explicitly adding this dependency is only necessary if you are 
-using CUDA Toolkit from a C/C++ file or project, or if you are utilizing 
+Note that explicitly adding this dependency is only necessary if you are
+using CUDA Toolkit from a C/C++ file or project, or if you are utilizing
 additional toolkit libraries that need to be explicitly linked to.
 
 ## CUPS
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index d8a8d11..c73e5a5 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -413,6 +413,9 @@ keyword arguments.
   - `sources`, sources to add to targets (or generated header files
     that should be built before sources including them are built)
   - `version`, the version of this dependency, such as `1.2.3`
+  - `variables`, a dictionary of arbitrary strings, this is meant to be used
+    in subprojects where special variables would be provided via cmake or
+    pkg-config. Since 0.54.0
 
 ### dependency()
 
@@ -2364,14 +2367,16 @@ an external dependency with the following methods:
    - 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 replaces the
+   internal: str, default_value : str, pkgconfig_define : [str, str])`
+   *(Added in 0.51.0)* 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.
 
+   *New in 0.54.0, the `internal` keyword*
+
 ### `disabler` object
 
 A disabler object is an object that behaves in much the same way as
diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md
index 91b1843..8232da9 100644
--- a/docs/markdown/Subprojects.md
+++ b/docs/markdown/Subprojects.md
@@ -55,6 +55,28 @@ should be named as `<project_name>_dep` (e.g. `gtest_dep`), and others can have
 
 There may be exceptions to these rules where common sense should be applied.
 
+### Adding variables to the dependency
+
+*New in 0.54.0*
+
+In some cases a project may define special variables via pkg-config or cmake
+that a caller needs to know about. Meson provides a `dependency.get_variable`
+method to hide what kind of dependency is provided, and this is available to
+subprojects as well. Use the `variables` keyword to add a dict of strings:
+
+```meson
+my_dep = declare_dependency(..., variables : {'var': 'value', 'number': '3'})
+```
+
+Which another project can access via:
+
+```meson
+var = my_dep.get_variable(internal : 'var', cmake : 'CMAKE_VAR')
+```
+
+The values of the dict must be strings, as pkg-config and cmake will return
+variables as strings.
+
 ### Build options in subproject
 
 All Meson features of the subproject, such as project options keep