From d3dcef7efc1df3b7a645eb6dc75c4a66a9131cb9 Mon Sep 17 00:00:00 2001 From: Jussi Pakkanen Date: Sat, 2 Dec 2017 22:17:21 +0200 Subject: [PATCH] Added documentation for disabler objects. --- docs/markdown/Disabler.md | 65 ++++++++++++++++++++++++++++++ docs/markdown/Reference-manual.md | 13 ++++++ docs/markdown/snippets/disabler.md | 33 +++++++++++++++ docs/sitemap.txt | 1 + 4 files changed, 112 insertions(+) create mode 100644 docs/markdown/Disabler.md create mode 100644 docs/markdown/snippets/disabler.md diff --git a/docs/markdown/Disabler.md b/docs/markdown/Disabler.md new file mode 100644 index 000000000..2d50c5cf8 --- /dev/null +++ b/docs/markdown/Disabler.md @@ -0,0 +1,65 @@ +--- +short-description: Disabling options +... + +# Disabling parts of the build (available since 0.44.0) + +The following is a common fragment found in many projects: + +```meson +dep = dependency('foo') + +# In some different directory + +lib = shared_library('mylib', 'mylib.c', + dependencies : dep) + +# And ín a third directory + +exe = executable('mytest', 'mytest.c', + link_with : lib) +test('mytest', exe) +``` + +This works fine but gets a bit inflexible when you want to make this +part of the build optional. Basically it reduces to adding `if/else` +statements around all target invocations. Meson provides a simpler way +of achieving the same with a disabler object. + +A disabler object is created with the `disabler` function: + +```meson +d = disabler() +``` + +The only thing you can do to a disabler object is to ask if it has +been found: + +```meson +f = d.found() # returns false +``` + +Any other statement that uses a disabler object will immediately +return a disabler. For example assuming that `d` contains a disabler +object then + +```meson +d2 = some_func(d) # value of d2 will be disabler +d3 = true or d2 # value of d3 will be disabler +if d # neither branch is evaluated +``` + +Thus to disable every target that depends on the dependency given +above, you can do something like this: + +```meson +if use_foo_feature + d = dependency('foo') +else + d = disabler() +endif +``` + +This concentrates the handling of this option in one place and other +build definition files do not need to be sprinkled with `if` +statements. \ No newline at end of file diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index e6aa9d330..ec5db03d0 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -319,6 +319,10 @@ otherwise. This function supports the following keyword arguments: The returned object also has methods that are documented in the [object methods section](#dependency-object) below. +### disabler() + +Returns a [disabler object]((#disabler-object)). Added in 0.44.0. + ### error() ``` meson @@ -1627,6 +1631,15 @@ an external dependency with the following methods: - `version()` is the version number as a string, for example `1.2.8` +### `disabler` object + +A disabler object is an object that behaves in much the same way as +NaN numbers do in floating point math. That is when used in any +statement (function call, logical op, etc) they will cause the +statement evaluation to immediately short circuit to return a disabler +object. A disabler object has one method: + + - `found()`, always returns `false` ### `external program` object diff --git a/docs/markdown/snippets/disabler.md b/docs/markdown/snippets/disabler.md new file mode 100644 index 000000000..1323048cc --- /dev/null +++ b/docs/markdown/snippets/disabler.md @@ -0,0 +1,33 @@ +# Added disabler object + +A disabler object is a new kind of object that has very specific +semantics. If it is used as part of any other operation such as an +argument to a function call, logical operations etc, it will cause the +operation to not be evaluated. Instead the return value of said +operation will also be the disabler object. + +For example if you have an setup like this: + +```meson +dep = dependency('foo') +lib = shared_library('mylib', 'mylib.c', + dependencies : dep) +exe = executable('mytest', 'mytest.c', + link_with : lib) +test('mytest', exe) +``` + +If you replace the dependency with a disabler object like this: + +```meson +dep = disabler() +lib = shared_library('mylib', 'mylib.c', + dependencies : dep) +exe = executable('mytest', 'mytest.c', + link_with : lib) +test('mytest', exe) +``` + +Then the shared library, executable and unit test are not +created. This is a handy mechanism to cut down on the number of `if` +statements. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 6b155afb7..9c86d60c5 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -26,6 +26,7 @@ index.md Localisation.md Build-options.md Subprojects.md + Disabler.md Modules.md Gnome-module.md i18n-module.md