From 6e865a233099a00e9ea08f6a2f911ede3c7b4215 Mon Sep 17 00:00:00 2001 From: Xavier Claessens Date: Wed, 11 Dec 2019 16:19:10 -0500 Subject: Add a summary() function for configuration summarization Based on patch from Dylan Baker. Fixes #757 --- docs/markdown/Reference-manual.md | 52 +++++++++++++++++++++++++++++++++++++++ docs/markdown/snippets/summary.md | 37 ++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 docs/markdown/snippets/summary.md (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 4f98025..e4c18a1 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1206,6 +1206,58 @@ This function prints its argument to stdout prefixed with WARNING:. *Added 0.44.0* +### summary() + +``` meson + void summary(section_name, dictionary) +``` + +This function is used to summarize build configuration at the end of the build +process. This function provides a way for projects (and subprojects) to report +this information in a clear way. + +The first argument is a section name, the second argument is a dictionary. +`summary()` can be called multiple times as long as the same dict key doesn't +appear twice in the same section. All sections will be collected and printed at +the end of the configuration in the same order as they have been called. + +Dictionary values can only be lists, integers, booleans or strings. + +Example: +```meson +project('My Project', version : '1.0') +summary('Directories', {'bindir': get_option('bindir'), + 'libdir': get_option('libdir'), + 'datadir': get_option('datadir'), + }) +summary('Configuration', {'Some boolean': false, + 'Another boolean': true, + 'Some string': 'Hello World', + 'A list': ['string', 1, true], + }) +``` + +Output: +``` +My Project 1.0 + + Directories + prefix: /opt/gnome + bindir: bin + libdir: lib/x86_64-linux-gnu + datadir: share + + Configuration + Some boolean: False + Another boolean: True + Some string: Hello World + A list: string + 1 + True +``` + +*Added 0.53.0* + ### project() ``` meson diff --git a/docs/markdown/snippets/summary.md b/docs/markdown/snippets/summary.md new file mode 100644 index 0000000..c5d64fd --- /dev/null +++ b/docs/markdown/snippets/summary.md @@ -0,0 +1,37 @@ +## Add a new summary() function + +A new function [`summary()`](Reference-manual.md#summary) has been added to +summarize build configuration at the end of the build process. + +Example: +```meson +project('My Project', version : '1.0') +summary('Directories', {'bindir': get_option('bindir'), + 'libdir': get_option('libdir'), + 'datadir': get_option('datadir'), + }) +summary('Configuration', {'Some boolean': false, + 'Another boolean': true, + 'Some string': 'Hello World', + 'A list': ['string', 1, true], + }) +``` + +Output: +``` +My Project 1.0 + + Directories + prefix: /opt/gnome + bindir: bin + libdir: lib/x86_64-linux-gnu + datadir: share + + Configuration + Some boolean: False + Another boolean: True + Some string: Hello World + A list: string + 1 + True +``` -- cgit v1.1 From 49082f96698fbb74b587ca774dae45b7b5943a16 Mon Sep 17 00:00:00 2001 From: Xavier Claessens Date: Wed, 11 Dec 2019 21:00:46 -0500 Subject: summary: Allow section with no title, and passing key/value separately --- docs/markdown/Reference-manual.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index e4c18a1..cf5585b 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1209,6 +1209,9 @@ This function prints its argument to stdout prefixed with WARNING:. ### summary() ``` meson + void summary(key, value) + void summary(dictionary) + void summary(section_name, key, value) void summary(section_name, dictionary) ``` @@ -1216,12 +1219,16 @@ This function is used to summarize build configuration at the end of the build process. This function provides a way for projects (and subprojects) to report this information in a clear way. -The first argument is a section name, the second argument is a dictionary. -`summary()` can be called multiple times as long as the same dict key doesn't -appear twice in the same section. All sections will be collected and printed at -the end of the configuration in the same order as they have been called. +The content is a serie of key/value pairs grouped into sections. If the section +argument is omitted, those key/value pairs are implicitly grouped into a section +with no title. key/value pairs can optionally be grouped into a dictionary, +but keep in mind that dictionaries does not guarantee ordering. +`section_name` and `key` must be strings, `value` can only be lists, integers, +booleans or strings. -Dictionary values can only be lists, integers, booleans or strings. +`summary()` can be called multiple times as long as the same section_name/key +pair doesn't appear twice. All sections will be collected and printed at +the end of the configuration in the same order as they have been called. Example: ```meson -- cgit v1.1 From 38953d8ee32bf025018c44e1e5a5edc04319dd90 Mon Sep 17 00:00:00 2001 From: Xavier Claessens Date: Wed, 11 Dec 2019 21:21:21 -0500 Subject: summary: Add bool_yn keyword argument --- docs/markdown/Reference-manual.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index cf5585b..d1fe55b 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1230,6 +1230,10 @@ booleans or strings. pair doesn't appear twice. All sections will be collected and printed at the end of the configuration in the same order as they have been called. +Keyword arguments: +- `bool_yn` if set to true, all boolean values will be replaced by green YES + or red NO. + Example: ```meson project('My Project', version : '1.0') -- cgit v1.1