third_party/pigweed/repo/pw_bloat/docs.rst

   1 .. _module-pw_bloat:
   2
   3 --------
   4 pw_bloat
   5 --------
   6 The bloat module provides tools to generate size report cards for output
   7 binaries using `Bloaty McBloatface <https://github.com/google/bloaty>`_ and
   8 Pigweed's GN build system.
   9
  10 Bloat report cards allow tracking the memory usage of a system over time as code
  11 changes are made and provide a breakdown of which parts of the code have the
  12 largest size impact.
  13
  14 .. _bloat-howto:
  15
  16 Defining size reports
  17 =====================
  18 Size reports are defined using the GN template ``pw_size_report``. The template
  19 requires at least two executable targets on which to perform a size diff. The
  20 base 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
  66 When the size report target runs, it will print its report card to stdout.
  67 Additionally, size report targets also generate ReST output, which is described
  68 below.
  69
  70 Documentation integration
  71 =========================
  72 Bloat reports are easy to add to documentation files. All ``pw_size_report``
  73 targets output a file containing a tabular report card. This file can be
  74 imported directly into a ReST documentation file using the ``include``
  75 directive.
  76
  77 For example, the ``simple_bloat_loop`` and ``simple_bloat_function`` size
  78 reports 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
  90 Resulting in this output:
  91
  92 Simple bloat loop example
  93 ^^^^^^^^^^^^^^^^^^^^^^^^^
  94 .. include:: examples/simple_bloat_loop
  95
  96 Simple bloat function example
  97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  98 .. include:: examples/simple_bloat_function