mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-20 05:41:06 +00:00
6230fa19cc
Size reports currently print when they're generated. This creates a fair amount of noise which will only increase over time. Add the pw_bloat_SHOW_SIZE_REPORTS build arg that controls whether to print size reports in the build. Change-Id: I82a2578e5412cf20c31f70d5eba058f84697f0a3 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/44820 Reviewed-by: Alexei Frolov <frolv@google.com> Reviewed-by: Keir Mierle <keir@google.com> Commit-Queue: Wyatt Hepler <hepler@google.com>
100 lines
3.0 KiB
ReStructuredText
100 lines
3.0 KiB
ReStructuredText
.. _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"
|
|
},
|
|
]
|
|
}
|
|
|
|
Size reports are typically included in ReST documentation, as described in
|
|
`Documentation integration`_. Size reports may also be printed in the build
|
|
output if desired. To enable this in the GN build, set the
|
|
``pw_bloat_SHOW_SIZE_REPORTS`` build arg to ``true``.
|
|
|
|
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
|