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/report/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
  83 Of course, there are additional options that you can see by running the tool
  84 with "--help".
  85
  86 This whole process takes about an hour on a modern (circa 2014) machine. If you
  87 have LOTS of RAM, you can use the "--jobs" argument to add more addr2line
  88 workers; doing so will *greatly* reduce the processing time but will devour
  89 system memory. If you've got the horsepower, 10 workers can thrash through the
  90 binary in about 5 minutes at a cost of around 60 GB of RAM. The default number
  91 of jobs is 1. Patches to job number auto-selection are welcome!
  92
  93 When the tool finishes its work you'll find an HTML report in the output
  94 directory that you specified with "--destdir". Open the index.html file in your
  95 *cough* browser of choice *cough* and have a look around. The index.html page
  96 is likely to evolve over time, but will always be your starting point for
  97 investigation. From here you'll find links to various views of the data such
  98 as treemap visualizations, overall statistics and "top n" lists of various
  99 kinds.
 100
 101 The report is completely standalone. No external resources are required, so the
 102 report may be saved and viewed offline with no problems.
 103
 104 --------------------------------------------------------------------------------
 105 How to Run: explain_binary_size_delta.py
 106 --------------------------------------------------------------------------------
 107 Continuing the example, assume that run_binary_size_analysis.py has been run
 108 both before and after a code change and that the "nm.out" files have been saved
 109 to "nm.out.before" and "nm.out.after". To generate an explanation of the symbol
 110 differences between the two runs:
 111
 112   tools/binary_size/explain_binary_size_delta.py \
 113   --nm1 nm.out.before --nm2 nm.out.after
 114
 115 This will output a concise summary of the symbol changes between the two
 116 libraries. Much more information is available by specifying flags like
 117 "--showsources" and (for the comprehensive answer) "--showsymbols". Use "--help"
 118 for a full list of options.
 119
 120 Unlike run_binary_size_analysis.py, this tool doesn't (yet) produce any kind of
 121 HTML report. Contributions are welcome.
 122
 123 --------------------------------------------------------------------------------
 124 Caveats
 125 --------------------------------------------------------------------------------
 126 The tool is not perfect and has several shortcomings:
 127
 128   * Not all space in the binary is accounted for. The causes are still under
 129     investigation, but there are of course sections in the binary that do not
 130     contain symbol information, etceteras. The vast majority of the binary is
 131     generally symbols, though, so the discrepancy should be very small.
 132   * When dealing with inlining and such, the size cost is attributed to the
 133     resource in which the code gets inlined. Depending upon your goals for
 134     analysis, this may be either good or bad; fundamentally, the more trickery
 135     that the compiler and/or linker do, the less simple the relationship
 136     between the original source and the resultant binary.
 137   * The Javascript code in the HTML report assumes code lives in Chromium for
 138     generated hyperlinks and will not hyperlink any file that starts with the
 139     substring "out".
 140   * There is as yet no way to configure project-specific bindings for symbols/
 141     source files to locations on disk. Such configuration would be useful for
 142     manually deduping and disambiguating results. Some day, hopefully, this will
 143     be supported.
 144
 145 --------------------------------------------------------------------------------
 146 Feature Requests and Bug Reports
 147 --------------------------------------------------------------------------------
 148 Please file bugs and feature requests here, making sure to use the label
 149 "Tools-BinarySize":
 150   https://code.google.com/p/chromium/issues/entry?labels=Tools-BinarySize
 151
 152 View all open issues here:
 153   https://code.google.com/p/chromium/issues/list?can=2&q=label:Tools-BinarySize