Add tool to help analyze binary size

tools/binary_size/README.txt

Index: tools/binary_size/README.txt
diff --git a/tools/binary_size/README.txt b/tools/binary_size/README.txt
new file mode 100644
index 0000000000000000000000000000000000000000..e417e1277f05ae31b666d1d161644604dccf740d
--- /dev/null
+++ b/tools/binary_size/README.txt
@@ -0,0 +1,117 @@
+================================================================================
+              __________  .__
+              \______   \ |__|   ____   _____    _______   ___.__.
+               |    |  _/ |  |  /    \  \__  \   \_  __ \ <   |  |
+               |    |   \ |  | |   |  \  / __ \_  |  | \/  \___  |
+               |______  / |__| |___|  / (____  /  |__|     / ____|
+                      \/            \/       \/            \/
+    _________ .__                        ___________                   .__
+   /   _____/ |__| ________   ____       \__    ___/   ____     ____   |  |
+   \_____  \  |  | \___   / _/ __ \        |    |     /  _ \   /  _ \  |  |
+   /        \ |  |  /    /  \  ___/        |    |    (  <_> ) (  <_> ) |  |__
+  /_______  / |__| /_____ \  \___  >       |____|     \____/   \____/  |____/
+          \/             \/      \/
+================================================================================
+
+--------------------------------------------------------------------------------
+1. Introduction
+--------------------------------------------------------------------------------
+The ever-increasing size of binaries is a problem for everybody. Increased
+binary size means longer download times and a bigger on-disk footprint after
+installation. Mobile devices suffer the worst, as they frequently have
+sub-optimal connectivity and limited storage capacity. Developers currently
+have almost no visibility into how the space in the existing binaries is
+divided nor how their contributions change the space within those binaries.
+The first step to reducing the size of binaries is to make the size information
+accessible to everyone so that developers can take action.
+
+The Binary Size Tool does the following:
+  1. Runs "nm" on a specified binary to dump the symbol table
+  2. Runs a parallel pool of "addr2line" processes to map the symbols from the
+     symbol table back to source code (way faster than running "nm -l")
+  3. Creates (and optionally saves) an intermediate file that accurately mimcs
+     (binary compatible with) the "nm" output format, with all the source code
+     mappings present
+  4. Parses, sorts and analyzes the results
+  5. Generates an HTML-based report in the specified output directory
+
+
+--------------------------------------------------------------------------------
+2. How to Run
+--------------------------------------------------------------------------------
+Running the tool is fairly simply. For the sake of this example we will
+pretend that you are building the Content Shell APK for Android.
+
+  1. Build your product as you normally would, e.g.:
+       ninja -C out/Release -j 100 content_shell_apk
+
+  2. Build the "binary_size_tool" target from ../../build/all_android.gyp, e.g.:
+       ninja -C out/Release binary_size_tool
+
+  3. Run the tool specifying the library and the output report directory.
+     This command will run the analysis on the Content Shell native library for
+     Android using the nm/addr2line binaries from the Android NDK for ARM,
+     producing an HTMl report in /tmp/report:
+       tools/binary_size/run_binary_size_analysis.py \
+         --library out/Release/lib/libcontent_shell_content_view.so \
+         --destdir /tmp/report \
+         --arch android-arm
+
+Of course, there are additional options that you can see by running the tool
+with "--help".
+
+This whole process takes about an hour on a modern (circa 2014) quad-core
+machine. If you have LOTS of RAM, you can use the "--jobs" argument to
+add more addr2line workers; doing so will *greatly* reduce the processing time
+but will devour system memory. If you've got the horsepower, 10 workers can
+thrash through the binary in about 5 minutes at a cost of around 60 GB of RAM.
+
+--------------------------------------------------------------------------------
+3. Analyzing the Output
+--------------------------------------------------------------------------------
+When the tool finishes its work you'll find an HTML report in the output
+directory that you specified with "--destdir". Open the index.html file in your
+*cough* browser of choice *cough* and have a look around. The index.html page
+is likely to evolve over time, but will always be your starting point for
+investigation. From here you'll find links to various views of the data such
+as treemap visualizations, overall statistics and "top n" lists of various
+kinds.
+
+The report is completely standalone. No external resources are required, so the
+report may be saved and viewed offline with no problems.
+
+--------------------------------------------------------------------------------
+4. Caveats
+--------------------------------------------------------------------------------
+The tool is not perfect and has several shortcomings:
+
+  * Not all space in the binary is accounted for. The cause is still under
+    investigation.
+  * The tool is partly written in Java, temporarily tying it to Android
+    purely and solely because it needs Java build logic which is only defined
+    in the Android part of the build system. The Java portions need to be
+    rewritten in Python so we can decouple from Android, or we need to find
+    an alternative (readelf, linker maps, etc) to running nm/addr2line.
+  * The Java code assumes that the library file is within a Chromium release
+    directory. This limits it to Chromium-based binaries only.
+  * The Java code has a hack to accurately identify the source of ICU data
+    within the Chromium source tree due to missing symbols in the ICU ASM
+    output.
+  * The Python script assumes that arm-based and mips-based nm/addr2line
+    binaries exist in ../../third_party. This is true only when dealing with
+    Android and again limits the tool to Chromium-based binaries.
+  * The Python script uses build system variables to construct the classpath
+    for running the Java code.
+  * The Javascript code in the HTML report Assumes code lives in Chromium for
+    generated hyperlinks and will not hyperlink any file that starts with the
+    substring "out".
+
+--------------------------------------------------------------------------------
+4. Feature Requests and Bug Reports

[Andrew Hayden (chromium.org), 2014/01/16 14:56:57]

Gah.

+--------------------------------------------------------------------------------
+Please file bugs and feature requests here, making sure to use the label
+"Binary-Size-Tool":
+  https://code.google.com/p/chromium/issues/entry?labels=Binary-Size-Tool
+
+View all open issues here:
+  https://code.google.com/p/chromium/issues/list?can=2&q=label:Binary-Size-Tool