name: summary
returns: void
since: 0.53.0
description: |
  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 content is a series of key/value pairs grouped into sections. If
  the section keyword 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. `key` must be string,
  `value` can be:

  - an integer, boolean or string
  - *since 0.57.0* an external program or a dependency
  - *since 0.58.0* a feature option
  - a list of those.

  Instead of calling summary as `summary(key, value)`, it is also possible to
  directly pass a dictionary to the [[summary]] function, as seen in the example
  below.

  `summary()` can be called multiple times as long as the same
  section/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: |
  Example `meson.build`:
  ```meson
  project('My Project', version : '1.0')
  summary({'bindir': get_option('bindir'),
          'libdir': get_option('libdir'),
          'datadir': get_option('datadir'),
          }, section: 'Directories')
  summary({'Some boolean': false,
          'Another boolean': true,
          'Some string': 'Hello World',
          'A list': ['string', 1, true],
          }, section: 'Configuration')
  ```

  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
  ```

posargs:
  key:
    type: str
    description: The name of the new entry

  value:
    type: str | bool | int | dep | external_program | list[str | bool | int | dep | external_program]
    description: The value to print for the `key`