1.. _module-pw_bloat:
2
3--------
4pw_bloat
5--------
6The bloat module provides tools to generate size report cards for output
7binaries using `Bloaty McBloatface <https://github.com/google/bloaty>`_ and
8Pigweed's GN build system.
9
10Bloat report cards allow tracking the memory usage of a system over time as code
11changes are made and provide a breakdown of which parts of the code have the
12largest size impact.
13
14.. _bloat-howto:
15
16Defining size reports
17=====================
18Size reports are defined using the GN template ``pw_size_report``. The template
19requires at least two executable targets on which to perform a size diff. The
20base for the size diff can be specified either globally through the top-level
21``base`` argument, or individually per-binary within the ``binaries`` list.
22
23**Arguments**
24
25* ``title``: Title for the report card.
26* ``base``: Optional default base target for all listed binaries.
27* ``binaries``: List of binaries to size diff. Each binary specifies a target,
28  a label for the diff, and optionally a base target that overrides the default
29  base.
30* ``source_filter``: Optional regex to filter labels in the diff output.
31* ``full_report``: Boolean flag indicating whether to output a full report of
32  all symbols in the binary, or a summary of the segment size changes. Default
33  false.
34
35.. code::
36
37  import("$dir_pw_bloat/bloat.gni")
38
39  executable("empty_base") {
40    sources = [ "empty_main.cc" ]
41  }
42
43  exectuable("hello_world_printf") {
44    sources = [ "hello_printf.cc" ]
45  }
46
47  exectuable("hello_world_iostream") {
48    sources = [ "hello_iostream.cc" ]
49  }
50
51  pw_size_report("my_size_report") {
52    title = "Hello world program using printf vs. iostream"
53    base = ":empty_base"
54    binaries = [
55      {
56        target = ":hello_world_printf"
57        label = "Hello world using printf"
58      },
59      {
60        target = ":hello_world_iostream"
61        label = "Hello world using iostream"
62      },
63    ]
64  }
65
66When the size report target runs, it will print its report card to stdout.
67Additionally, size report targets also generate ReST output, which is described
68below.
69
70Documentation integration
71=========================
72Bloat reports are easy to add to documentation files. All ``pw_size_report``
73targets output a file containing a tabular report card. This file can be
74imported directly into a ReST documentation file using the ``include``
75directive.
76
77For example, the ``simple_bloat_loop`` and ``simple_bloat_function`` size
78reports under ``//pw_bloat/examples`` are imported into this file as follows:
79
80.. code:: rst
81
82  Simple bloat loop example
83  ^^^^^^^^^^^^^^^^^^^^^^^^^
84  .. include:: examples/simple_bloat_loop
85
86  Simple bloat function example
87  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88  .. include:: examples/simple_bloat_function
89
90Resulting in this output:
91
92Simple bloat loop example
93^^^^^^^^^^^^^^^^^^^^^^^^^
94.. include:: examples/simple_bloat_loop
95
96Simple bloat function example
97^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98.. include:: examples/simple_bloat_function
99