pw_bloat¶
The bloat module provides tools to generate size report cards for output binaries using Bloaty McBloatface 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.
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.
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:
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¶
Warning
The pw_size_report_toolchains
build variable is empty for this target.
Size reports will not be generated.
See Defining size reports for details on how to set up size reports.
Simple bloat function example¶
Warning
The pw_size_report_toolchains
build variable is empty for this target.
Size reports will not be generated.
See Defining size reports for details on how to set up size reports.