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