tools/binary_size/README.txt

   1 ================================================================================
   2               __________  .__
   3               \______   \ |__|   ____   _____    _______   ___.__.
   4                |    |  _/ |  |  /    \  \__  \   \_  __ \ <   |  |
   5                |    |   \ |  | |   |  \  / __ \_  |  | \/  \___  |
   6                |______  / |__| |___|  / (____  /  |__|     / ____|
   7                       \/            \/       \/            \/
   8     _________ .__                        ___________                   .__
   9    /   _____/ |__| ________   ____       \__    ___/   ____     ____   |  |
  10    \_____  \  |  | \___   / _/ __ \        |    |     /  _ \   /  _ \  |  |
  11    /        \ |  |  /    /  \  ___/        |    |    (  <_> ) (  <_> ) |  |__
  12   /_______  / |__| /_____ \  \___  >       |____|     \____/   \____/  |____/
  13           \/             \/      \/
  14 ================================================================================
  15
  16 --------------------------------------------------------------------------------
  17 Introduction
  18 --------------------------------------------------------------------------------
  19 The ever-increasing size of binaries is a problem for everybody. Increased
  20 binary size means longer download times and a bigger on-disk footprint after
  21 installation. Mobile devices suffer the worst, as they frequently have
  22 sub-optimal connectivity and limited storage capacity. Developers currently
  23 have almost no visibility into how the space in the existing binaries is
  24 divided nor how their contributions change the space within those binaries.
  25 The first step to reducing the size of binaries is to make the size information
  26 accessible to everyone so that developers can take action.
  27
  28 There are two parts to the Binary Size Tool:
  29 1. run_binary_size_analysis.py
  30    This script will produce a detailed breakdown of a binary, including an HTML
  31    report and (optionally) a detailed ""nm"-formatted dump of all the symbols
  32    with their sources resolved by addr2line. This tool is great for finding the
  33    bloat in binaries.
  34
  35 2. explain_binary_size_delta.py
  36    This script takes the "nm"-formatted input from two runs of the first tool
  37    (run_binary_size_analysis.py) and produces a detailed breakdown of how the
  38    symbols have changed between the two binaries that were originally analyzed.
  39    The breakdown shows the size changes of symbols as well as which symbols have
  40    been added, removed, or changed. This tool is great for thoroughly
  41    characterizing the size change resulting from a code change.
  42
  43    Because this tool relies solely upon the "nm" output from
  44    run_binary_size_analysis.py, it can be run at any time even if the source
  45    code described by the "nm" output is no longer available. It is also much
  46    faster than run_binary_size_analysis.py, typically completing in a few
  47    seconds for even very large binaries.
  48
  49 --------------------------------------------------------------------------------
  50 How to Run: run_binary_size_analysis.py
  51 --------------------------------------------------------------------------------
  52 Running the tool is fairly simple. For the sake of this example we will
  53 pretend that you are building the Content Shell APK for Android.
  54
  55   1. Build your product as you normally would*, e.g.:
  56        ninja -C out/Release -j 100 content_shell_apk
  57
  58      * For results that are as spatially accurate as possible, you should always
  59      build with a Release configuration so that the end product is as close to
  60      the real thing as possible. However, it can sometimes be useful to improve
  61      consistency and accuracy of symbol lookup even if it perturbs the overall
  62      accuracy of the tool. Consider adding these defines (e.g., via GYP_DEFINES
  63      or GN build arguments):
  64        clang=1
  65          Anecdotally produces more stable symbol names over time.
  66        profiling=1
  67          Anecdotally makes symbol lookup more accurate (note that profiling=1
  68          doesn't work with clang on ARM/Android builds, see
  69          https://crbug.com/417323 for more information.
  70        profiling_full_stack_frames=1
  71          With profiling=1, should further improve symbol lookup accuracy but
  72          will completely disable inlining, further decreasing spatial accuracy.
  73
  74   2. Run the tool specifying the library and the output report directory.
  75      This command will run the analysis on the Content Shell native library for
  76      Android, producing an HTML report in /tmp/report and saving the NM output
  77      (useful for re-running the tool or analyzing deltas between two builds)
  78      under /tmp/nm.out:
  79        tools/binary_size/run_binary_size_analysis.py \
  80          --library out/Release/lib/libcontent_shell_content_view.so \
  81          --destdir /tmp/report \
  82          --nm-out /tmp/nm.out
  83
  84 Of course, there are additional options that you can see by running the tool
  85 with "--help".
  86
  87 This whole process takes about an hour on a modern (circa 2014) machine. If you
  88 have LOTS of RAM, you can use the "--jobs" argument to add more addr2line
  89 workers; doing so will *greatly* reduce the processing time but will devour
  90 system memory. If you've got the horsepower, 10 workers can thrash through the
  91 binary in about 5 minutes at a cost of around 60 GB of RAM. The default number
  92 of jobs is 1. Patches to job number auto-selection are welcome!
  93
  94 When the tool finishes its work you'll find an HTML report in the output
  95 directory that you specified with "--destdir". Open the index.html file in your
  96 *cough* browser of choice *cough* and have a look around. The index.html page
  97 is likely to evolve over time, but will always be your starting point for
  98 investigation. From here you'll find links to various views of the data such
  99 as treemap visualizations, overall statistics and "top n" lists of various
 100 kinds.
 101
 102 The report is completely standalone. No external resources are required, so the
 103 report may be saved and viewed offline with no problems.
 104
 105 --------------------------------------------------------------------------------
 106 How to Run: explain_binary_size_delta.py
 107 --------------------------------------------------------------------------------
 108 Continuing the example, assume that explain_binary_size_delta.py has been run
 109 both before and after a code change and that the "nm.out" files have been saved
 110 to "nm.out.before" and "nm.out.after". To generate an explanation of the symbol
 111 differences between the two runs:
 112
 113   tools/binary_size/explain_binary_size_delta.py \
 114   --nm1 nm.out.before --nm2 nm.out.after
 115
 116 This will output a concise summary of the symbol changes between the two
 117 libraries. Much more information is available by specifying flags like
 118 "--showsources" and (for the comprehensive answer) "--showsymbols". Use "--help"
 119 for a full list of options.
 120
 121 Unlike run_binary_size_analysis.py, this tool doesn't (yet) produce any kind of
 122 HTML report. Contributions are welcome.
 123
 124 --------------------------------------------------------------------------------
 125 Caveats
 126 --------------------------------------------------------------------------------
 127 The tool is not perfect and has several shortcomings:
 128
 129   * Not all space in the binary is accounted for. The causes are still under
 130     investigation, but there are of course sections in the binary that do not
 131     contain symbol information, etceteras. The vast majority of the binary is
 132     generally symbols, though, so the discrepancy should be very small.
 133   * When dealing with inlining and such, the size cost is attributed to the
 134     resource in which the code gets inlined. Depending upon your goals for
 135     analysis, this may be either good or bad; fundamentally, the more trickery
 136     that the compiler and/or linker do, the less simple the relationship
 137     between the original source and the resultant binary.
 138   * The Javascript code in the HTML report assumes code lives in Chromium for
 139     generated hyperlinks and will not hyperlink any file that starts with the
 140     substring "out".
 141   * There is as yet no way to configure project-specific bindings for symbols/
 142     source files to locations on disk. Such configuration would be useful for
 143     manually deduping and disambiguating results. Some day, hopefully, this will
 144     be supported.
 145
 146 --------------------------------------------------------------------------------
 147 Feature Requests and Bug Reports
 148 --------------------------------------------------------------------------------
 149 Please file bugs and feature requests here, making sure to use the label
 150 "Tools-BinarySize":
 151   https://code.google.com/p/chromium/issues/entry?labels=Tools-BinarySize
 152
 153 View all open issues here:
 154   https://code.google.com/p/chromium/issues/list?can=2&q=label:Tools-BinarySize