You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
99 lines
2.9 KiB
99 lines
2.9 KiB
.. _module-pw_bloat:
|
|
|
|
--------
|
|
pw_bloat
|
|
--------
|
|
The bloat module provides tools to generate size report cards for output
|
|
binaries using `Bloaty McBloatface <https://github.com/google/bloaty>`_ and
|
|
Pigweed's GN build system.
|
|
|
|
Bloat report cards allow tracking the memory usage of a system over time as code
|
|
changes are made and provide a breakdown of which parts of the code have the
|
|
largest size impact.
|
|
|
|
.. _bloat-howto:
|
|
|
|
Defining size reports
|
|
=====================
|
|
Size reports are defined using the GN template ``pw_size_report``. The template
|
|
requires at least two executable targets on which to perform a size diff. The
|
|
base for the size diff can be specified either globally through the top-level
|
|
``base`` argument, or individually per-binary within the ``binaries`` list.
|
|
|
|
**Arguments**
|
|
|
|
* ``title``: Title for the report card.
|
|
* ``base``: Optional default base target for all listed binaries.
|
|
* ``binaries``: List of binaries to size diff. Each binary specifies a target,
|
|
a label for the diff, and optionally a base target that overrides the default
|
|
base.
|
|
* ``source_filter``: Optional regex to filter labels in the diff output.
|
|
* ``full_report``: Boolean flag indicating whether to output a full report of
|
|
all symbols in the binary, or a summary of the segment size changes. Default
|
|
false.
|
|
|
|
.. code::
|
|
|
|
import("$dir_pw_bloat/bloat.gni")
|
|
|
|
executable("empty_base") {
|
|
sources = [ "empty_main.cc" ]
|
|
}
|
|
|
|
exectuable("hello_world_printf") {
|
|
sources = [ "hello_printf.cc" ]
|
|
}
|
|
|
|
exectuable("hello_world_iostream") {
|
|
sources = [ "hello_iostream.cc" ]
|
|
}
|
|
|
|
pw_size_report("my_size_report") {
|
|
title = "Hello world program using printf vs. iostream"
|
|
base = ":empty_base"
|
|
binaries = [
|
|
{
|
|
target = ":hello_world_printf"
|
|
label = "Hello world using printf"
|
|
},
|
|
{
|
|
target = ":hello_world_iostream"
|
|
label = "Hello world using iostream"
|
|
},
|
|
]
|
|
}
|
|
|
|
When the size report target runs, it will print its report card to stdout.
|
|
Additionally, size report targets also generate ReST output, which is described
|
|
below.
|
|
|
|
Documentation integration
|
|
=========================
|
|
Bloat reports are easy to add to documentation files. All ``pw_size_report``
|
|
targets output a file containing a tabular report card. This file can be
|
|
imported directly into a ReST documentation file using the ``include``
|
|
directive.
|
|
|
|
For example, the ``simple_bloat_loop`` and ``simple_bloat_function`` size
|
|
reports under ``//pw_bloat/examples`` are imported into this file as follows:
|
|
|
|
.. code:: rst
|
|
|
|
Simple bloat loop example
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
.. include:: examples/simple_bloat_loop
|
|
|
|
Simple bloat function example
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
.. include:: examples/simple_bloat_function
|
|
|
|
Resulting in this output:
|
|
|
|
Simple bloat loop example
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
.. include:: examples/simple_bloat_loop
|
|
|
|
Simple bloat function example
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
.. include:: examples/simple_bloat_function
|