From 202c89d0b665a536a738c59dcde1f374047a346e Mon Sep 17 00:00:00 2001 From: Dylan Baker Date: Tue, 7 Jan 2020 11:43:31 -0800 Subject: docs: Add documentation for variables keyword In declare_dependency() and dependency.get_variables(). --- docs/markdown/Dependencies.md | 24 +++++++++++++----------- docs/markdown/Reference-manual.md | 9 +++++++-- docs/markdown/Subprojects.md | 22 ++++++++++++++++++++++ 3 files changed, 42 insertions(+), 13 deletions(-) (limited to 'docs') 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 `_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 -- cgit v1.1