| 1 |
name: summary |
| 2 |
returns: void |
| 3 |
since: 0.53.0 |
| 4 |
description: | |
| 5 |
This function is used to summarize build configuration at the end of the build |
| 6 |
process. This function provides a way for projects (and subprojects) to report |
| 7 |
this information in a clear way. |
| 8 |
|
| 9 |
The content is a series of key/value pairs grouped into sections. If |
| 10 |
the section keyword argument is omitted, those key/value pairs are |
| 11 |
implicitly grouped into a section with no title. key/value pairs can |
| 12 |
optionally be grouped into a dictionary, but keep in mind that |
| 13 |
dictionaries do not guarantee ordering. `key` must be string, |
| 14 |
`value` can be: |
| 15 |
|
| 16 |
- an integer, boolean or string |
| 17 |
- *since 0.57.0* an external program or a dependency |
| 18 |
- *since 0.58.0* a feature option |
| 19 |
- a list of those. |
| 20 |
|
| 21 |
Instead of calling summary as `summary(key, value)`, it is also possible to |
| 22 |
directly pass a dictionary to the [[summary]] function, as seen in the example |
| 23 |
below. |
| 24 |
|
| 25 |
`summary()` can be called multiple times as long as the same |
| 26 |
section/key pair doesn't appear twice. All sections will be collected |
| 27 |
and printed at the end of the configuration in the same order as they |
| 28 |
have been called. |
| 29 |
|
| 30 |
example: | |
| 31 |
Example `meson.build`: |
| 32 |
```meson |
| 33 |
project('My Project', version : '1.0') |
| 34 |
summary({'bindir': get_option('bindir'), |
| 35 |
'libdir': get_option('libdir'), |
| 36 |
'datadir': get_option('datadir'), |
| 37 |
}, section: 'Directories') |
| 38 |
summary({'Some boolean': false, |
| 39 |
'Another boolean': true, |
| 40 |
'Some string': 'Hello World', |
| 41 |
'A list': ['string', 1, true], |
| 42 |
}, section: 'Configuration') |
| 43 |
``` |
| 44 |
|
| 45 |
Output: |
| 46 |
``` |
| 47 |
My Project 1.0 |
| 48 |
|
| 49 |
Directories |
| 50 |
prefix : /opt/gnome |
| 51 |
bindir : bin |
| 52 |
libdir : lib/x86_64-linux-gnu |
| 53 |
datadir : share |
| 54 |
|
| 55 |
Configuration |
| 56 |
Some boolean : False |
| 57 |
Another boolean: True |
| 58 |
Some string : Hello World |
| 59 |
A list : string |
| 60 |
1 |
| 61 |
True |
| 62 |
``` |
| 63 |
|
| 64 |
arg_flattening: false |
| 65 |
|
| 66 |
posargs: |
| 67 |
key_or_dict: |
| 68 |
type: str | dict[str | bool | int | dep | external_program | list[str | bool | int | dep | external_program]] |
| 69 |
description: | |
| 70 |
The name of the new entry, or a dict containing multiple entries. If a |
| 71 |
dict is passed it is equivalent to calling summary() once for each |
| 72 |
key-value pair. Keep in mind that dictionaries do not guarantee |
| 73 |
ordering. |
| 74 |
|
| 75 |
optargs: |
| 76 |
value: |
| 77 |
type: str | bool | int | dep | external_program | list[str | bool | int | dep | external_program] |
| 78 |
description: | |
| 79 |
The value to print for the `key`. Only valid if `key_or_dict` is a str. |
| 80 |
|
| 81 |
kwargs: |
| 82 |
bool_yn: |
| 83 |
type: bool |
| 84 |
default: false |
| 85 |
description: Convert bool values to yes and no |
| 86 |
section: |
| 87 |
type: str |
| 88 |
description: The section to put this summary information under. If the |
| 89 |
section keyword argument is omitted, key/value pairs are implicitly |
| 90 |
grouped into a section with no title. |
| 91 |
list_sep: |
| 92 |
type: str |
| 93 |
since: 0.54.0 |
| 94 |
description: | |
| 95 |
The separator to use when printing list values in this summary. If no |
| 96 |
separator is given, each list item will be printed on its own line. |