Home | History | Annotate | only in /external/chromium_org/tools/binary_size
Up to higher level directory
NameDateSize
binary_size_utils.py03-Dec-20142.2K
explain_binary_size_delta.py03-Dec-201411.1K
explain_binary_size_delta_unittest.py03-Dec-20148.8K
legacy_template/03-Dec-2014
PRESUBMIT.py03-Dec-20141.1K
README.txt03-Dec-20146.7K
run_binary_size_analysis.py03-Dec-201429.1K
template/03-Dec-2014

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 The Binary Size Tool does the following:
     29   1. Runs "nm" on a specified binary to dump the symbol table
     30   2. Runs a parallel pool of "addr2line" processes to map the symbols from the
     31      symbol table back to source code (way faster than running "nm -l")
     32   3. Creates (and optionally saves) an intermediate file that accurately mimcs
     33      (binary compatible with) the "nm" output format, with all the source code
     34      mappings present
     35   4. Parses, sorts and analyzes the results
     36   5. Generates an HTML-based report in the specified output directory
     37 
     38 
     39 --------------------------------------------------------------------------------
     40 How to Run
     41 --------------------------------------------------------------------------------
     42 Running the tool is fairly simply. For the sake of this example we will
     43 pretend that you are building the Content Shell APK for Android.
     44 
     45   1. Build your product as you normally would, e.g.:
     46        ninja -C out/Release -j 100 content_shell_apk
     47 
     48   2. Build the "binary_size_tool" target from ../../build/all_android.gyp, e.g.:
     49        ninja -C out/Release binary_size_tool
     50 
     51   3. Run the tool specifying the library and the output report directory.
     52      This command will run the analysis on the Content Shell native library for
     53      Android using the nm/addr2line binaries from the Android NDK for ARM,
     54      producing an HTML report in /tmp/report:
     55        tools/binary_size/run_binary_size_analysis.py \
     56          --library out/Release/lib/libcontent_shell_content_view.so \
     57          --destdir /tmp/report \
     58          --arch android-arm
     59 
     60 Of course, there are additional options that you can see by running the tool
     61 with "--help".
     62 
     63 This whole process takes about an hour on a modern (circa 2014) quad-core
     64 machine. If you have LOTS of RAM, you can use the "--jobs" argument to
     65 add more addr2line workers; doing so will *greatly* reduce the processing time
     66 but will devour system memory. If you've got the horsepower, 10 workers can
     67 thrash through the binary in about 5 minutes at a cost of around 60 GB of RAM.
     68 
     69 --------------------------------------------------------------------------------
     70 Analyzing the Output
     71 --------------------------------------------------------------------------------
     72 When the tool finishes its work you'll find an HTML report in the output
     73 directory that you specified with "--destdir". Open the index.html file in your
     74 *cough* browser of choice *cough* and have a look around. The index.html page
     75 is likely to evolve over time, but will always be your starting point for
     76 investigation. From here you'll find links to various views of the data such
     77 as treemap visualizations, overall statistics and "top n" lists of various
     78 kinds.
     79 
     80 The report is completely standalone. No external resources are required, so the
     81 report may be saved and viewed offline with no problems.
     82 
     83 --------------------------------------------------------------------------------
     84 Caveats
     85 --------------------------------------------------------------------------------
     86 The tool is not perfect and has several shortcomings:
     87 
     88   * Not all space in the binary is accounted for. The cause is still under
     89     investigation.
     90   * When dealing with inlining and such, the size cost is attributed to the
     91     resource in which the code gets inlined. Depending upon your goals for
     92     analysis, this may be either good or bad; fundamentally, the more trickery
     93     that the compiler and/or linker do, the less simple the relationship
     94     between the original source and the resultant binary.
     95   * The tool is partly written in Java, temporarily tying it to Android
     96     purely and solely because it needs Java build logic which is only defined
     97     in the Android part of the build system. The Java portions need to be
     98     rewritten in Python so we can decouple from Android, or we need to find
     99     an alternative (readelf, linker maps, etc) to running nm/addr2line.
    100   * The Java code assumes that the library file is within a Chromium release
    101     directory. This limits it to Chromium-based binaries only.
    102   * The Java code has a hack to accurately identify the source of ICU data
    103     within the Chromium source tree due to missing size information in the ICU
    104     ASM output in some build variants.
    105   * The Python script assumes that arm-based and mips-based nm/addr2line
    106     binaries exist in ../../third_party/android_tools/ndk/toolchains. This is
    107     true only when dealing with Android and again limits the tool to
    108     Chromium-based binaries.
    109   * The Python script uses build system variables to construct the classpath
    110     for running the Java code.
    111   * The Javascript code in the HTML report Assumes code lives in Chromium for
    112     generated hyperlinks and will not hyperlink any file that starts with the
    113     substring "out".
    114 
    115 --------------------------------------------------------------------------------
    116 Feature Requests and Bug Reports
    117 --------------------------------------------------------------------------------
    118 Please file bugs and feature requests here, making sure to use the label
    119 "Tools-BinarySize":
    120   https://code.google.com/p/chromium/issues/entry?labels=Tools-BinarySize
    121 
    122 View all open issues here:
    123   https://code.google.com/p/chromium/issues/list?can=2&q=label:Tools-BinarySize
    124