Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_bloat: |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 2 | |
Wyatt Hepler | b82f995 | 2019-11-25 13:56:31 -0800 | [diff] [blame] | 3 | -------- |
| 4 | pw_bloat |
| 5 | -------- |
Alexei Frolov | 4c035b0 | 2019-11-14 16:36:15 -0800 | [diff] [blame] | 6 | The bloat module provides tools to generate size report cards for output |
Alexei Frolov | fa34a82 | 2020-02-28 14:25:04 -0800 | [diff] [blame] | 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. |
Alexei Frolov | 4c035b0 | 2019-11-14 16:36:15 -0800 | [diff] [blame] | 13 | |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 14 | .. _bloat-howto: |
| 15 | |
| 16 | Defining size reports |
| 17 | ===================== |
Alexei Frolov | fa34a82 | 2020-02-28 14:25:04 -0800 | [diff] [blame] | 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. |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 22 | |
Alexei Frolov | fa34a82 | 2020-02-28 14:25:04 -0800 | [diff] [blame] | 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 | |
Wyatt Hepler | 6230fa1 | 2021-05-11 18:41:51 -0700 | [diff] [blame] | 66 | Size reports are typically included in ReST documentation, as described in |
| 67 | `Documentation integration`_. Size reports may also be printed in the build |
| 68 | output if desired. To enable this in the GN build, set the |
| 69 | ``pw_bloat_SHOW_SIZE_REPORTS`` build arg to ``true``. |
Alexei Frolov | 4c035b0 | 2019-11-14 16:36:15 -0800 | [diff] [blame] | 70 | |
| 71 | Documentation integration |
| 72 | ========================= |
Alexei Frolov | 0944784 | 2019-11-15 15:09:05 -0800 | [diff] [blame] | 73 | 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] | 74 | targets output a file containing a tabular report card. This file can be |
| 75 | imported directly into a ReST documentation file using the ``include`` |
Alexei Frolov | 4c035b0 | 2019-11-14 16:36:15 -0800 | [diff] [blame] | 76 | directive. |
| 77 | |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 78 | For example, the ``simple_bloat_loop`` and ``simple_bloat_function`` size |
| 79 | reports under ``//pw_bloat/examples`` are imported into this file as follows: |
Alexei Frolov | 4c035b0 | 2019-11-14 16:36:15 -0800 | [diff] [blame] | 80 | |
| 81 | .. code:: rst |
| 82 | |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 83 | Simple bloat loop example |
| 84 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
Alexei Frolov | 725b85b | 2020-03-19 13:37:10 -0700 | [diff] [blame] | 85 | .. include:: examples/simple_bloat_loop |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 86 | |
| 87 | Simple bloat function example |
| 88 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Alexei Frolov | 725b85b | 2020-03-19 13:37:10 -0700 | [diff] [blame] | 89 | .. include:: examples/simple_bloat_function |
Alexei Frolov | 4c035b0 | 2019-11-14 16:36:15 -0800 | [diff] [blame] | 90 | |
| 91 | Resulting in this output: |
| 92 | |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 93 | Simple bloat loop example |
| 94 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
Alexei Frolov | 725b85b | 2020-03-19 13:37:10 -0700 | [diff] [blame] | 95 | .. include:: examples/simple_bloat_loop |
Alexei Frolov | 3fde6b1 | 2019-12-18 16:13:38 -0800 | [diff] [blame] | 96 | |
| 97 | Simple bloat function example |
| 98 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Alexei Frolov | 725b85b | 2020-03-19 13:37:10 -0700 | [diff] [blame] | 99 | .. include:: examples/simple_bloat_function |