Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/summary.yaml

raw
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.