diff options
author | Xavier Claessens <xavier.claessens@collabora.com> | 2020-07-04 12:39:24 -0400 |
---|---|---|
committer | Jussi Pakkanen <jpakkane@gmail.com> | 2020-07-05 18:02:20 +0300 |
commit | 1993fb602e447f8b6123f6dad3e0e9ca34bf6970 (patch) | |
tree | 1d2061830a52788fc5cd8434f54bf7a82e093a65 /docs | |
parent | 40319c963447f7632753e694f606dc6d41a9f168 (diff) | |
download | meson-1993fb602e447f8b6123f6dad3e0e9ca34bf6970.zip meson-1993fb602e447f8b6123f6dad3e0e9ca34bf6970.tar.gz meson-1993fb602e447f8b6123f6dad3e0e9ca34bf6970.tar.bz2 |
doc: Improve documentation of [provide] section in wrap files
Explicitly document the behaviour of dependency('foo-1.0', required:
false).
Diffstat (limited to 'docs')
-rw-r--r-- | docs/markdown/Wrap-dependency-system-manual.md | 67 | ||||
-rw-r--r-- | docs/markdown/snippets/implicit_fallback.md | 2 |
2 files changed, 49 insertions, 20 deletions
diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md index 0ff304d..54ef811 100644 --- a/docs/markdown/Wrap-dependency-system-manual.md +++ b/docs/markdown/Wrap-dependency-system-manual.md @@ -136,25 +136,60 @@ thousands of lines of code. Once you have a working build definition, just zip up the Meson build files (and others you have changed) and put them somewhere where you can download them. -Meson build patches are only supported for wrap-file mode. When using -wrap-git, the repository must contain all Meson build definitions. +Prior to *0.55.0* Meson build patches were only supported for wrap-file mode. +When using wrap-git, the repository must contain all Meson build definitions. +Since *0.55.0* Meson build patches are supported for any wrap modes, including +wrap-git. ## `provide` section *Since *0.55.0* Wrap files can define the dependencies it provides in the `[provide]` section. -When a wrap file provides the dependency `foo` any call do `dependency('foo')` -will automatically fallback to that subproject even if no `fallback` keyword -argument is given. It is recommended for subprojects to call -`meson.override_dependency('foo', foo_dep)`, dependency name can then be added into -the special `dependency_names` entry which takes comma separated list of dependency -names. For backward compatibility with subprojects that does not call -`meson.override_dependency()`, the variable name can be provided in the wrap file -with entries in the format `dependency_name = variable_name`, -where `dependency_name` usually match the corresponding pkg-config name and -`variable_name` is the name of a variable defined in the subproject that should -be returned for that dependency. + +``` +[provide] +dependency_names = foo-1.0 +``` + +When a wrap file provides the dependency `foo-1.0`, as above, any call to +`dependency('foo-1.0')` will automatically fallback to that subproject even if +no `fallback` keyword argument is given. A wrap file named `foo.wrap` implicitly +provides the dependency name `foo` even when the `[provide]` section is missing. + +Optional dependencies, like `dependency('foo-1.0', required: get_option('foo_opt'))` +where `foo_opt` is a feature option set to `auto`, will not fallback to the +subproject defined in the wrap file, for 2 reasons: +- It allows for looking the dependency in other ways first, for example using + `cc.find_library('foo')`, and only fallback if that fails: +``` +# this won't use fallback defined in foo.wrap +foo_dep = dependency('foo-1.0', required: false) +if not foo_dep.found() + foo_dep = cc.find_library('foo', has_headers: 'foo.h', required: false) + if not foo_dep.found() + # This will use the fallback + foo_dep = dependency('foo-1.0') + # or + foo_dep = dependency('foo-1.0', required: false, fallback: 'foo') + endif +endif +``` +- Sometimes not-found dependency is preferable to a fallback when the feature is + not explicitly requested by the user. In that case + `dependency('foo-1.0', required: get_option('foo_opt'))` will only fallback + when the user sets `foo_opt` to `enabled` instead of `auto`. + +If it is desired to fallback for an optional dependency, the `fallback` keyword +argument must be passed explicitly. For example +`dependency('foo-1.0', required: get_option('foo_opt'), fallback: 'foo')` will +use the fallback even when `foo_opt` is set to `auto`. + +This mechanism assumes the subproject calls `meson.override_dependency('foo-1.0', foo_dep)` +so Meson knows which dependency object should be used as fallback. Since that +method was introduced in version *0.54.0*, as a transitional aid for projects +that do not yet make use of it the variable name can be provided in the wrap file +with entries in the format `foo-1.0 = foo_dep`. For example when using a recent enough version of glib that uses `meson.override_dependency()` to override `glib-2.0`, `gobject-2.0` and `gio-2.0`, @@ -180,14 +215,8 @@ gobject-2.0=gobject_dep gio-2.0=gio_dep ``` -With such wrap file, `dependency('glib-2.0')` will automatically fallback to use -`glib.wrap` and return `glib_dep` variable from the subproject. - Programs can also be provided by wrap files, with the `program_names` key: ```ini -[wrap-git] -... - [provide] program_names = myprog, otherprog ``` diff --git a/docs/markdown/snippets/implicit_fallback.md b/docs/markdown/snippets/implicit_fallback.md index 3d5a833..a6cbaf0 100644 --- a/docs/markdown/snippets/implicit_fallback.md +++ b/docs/markdown/snippets/implicit_fallback.md @@ -11,7 +11,7 @@ should be used for `foo`. ## Wrap file `provide` section Wrap files can define the dependencies it provides in the `[provide]` section. -When a wrap file provides the dependency `foo` any call do `dependency('foo')` +When `foo.wrap` provides the dependency `foo-1.0` any call do `dependency('foo-1.0')` will automatically fallback to that subproject even if no `fallback` keyword argument is given. See [Wrap documentation](Wrap-dependency-system-manual.md#provide_section). |