V1 of //tools/binary_size rewrite

tools/binary_size/README.md

Index: tools/binary_size/README.md
diff --git a/tools/binary_size/README.md b/tools/binary_size/README.md
index 6bd2c5b6a5ccd21879ceb523b55aff134972407a..e545b33e1c69da055df159ab19e4fb3f14089910 100644
--- a/tools/binary_size/README.md
+++ b/tools/binary_size/README.md
@@ -1,49 +1,60 @@
-# run_binary_size_analysis.py
+# analyze.py
 
-## About:
-  * Uses `nm --print-size` and `addr2line` to extract size information
-    * nm's correctness can be somewhat suspect at times...
-  * Produces an html report with bloat grouped by source path.
-  * Produces an "nm"-formatted dump of symbols with their sources resolved by
-    addr2line.
-  * For Chrome, takes ~60 minutes on a z620, but --jobs=10 reduces to ~5 minutes
-    (**at the cost of 60GB of RAM**).
+Parses and processes a linker .map file and outputs the result as a .size file.
 
 ## Example Usage:
 
+    # Android:
+    gn gen out/Release --args='target_os="android" is_official_build=true'
     ninja -C out/Release -j 1000 libchrome.so
-    tools/binary_size/run_binary_size_analysis.py \
-        --library out/Release/lib.unstripped/libchrome.so \
-        --destdir out/Release/binary-size-report \
-        --jobs=10
-    xdg-open out/Release/binary-size-report/index.html
+    tools/binary_size/analyze.py out/Release/lib.unstripped/libchrome.so.map.gz --output chrome.size -v
+    # Linux:
+    gn gen out/Release --args='is_official_build=true'
+    ninja -C out/Release -j 1000 chrome
+    tools/binary_size/analyze.py out/Release/chrome.map.gz --output chrome.size -v
 
-## Recommanded GN Args:
+# create_html_breakdown.py
 
-    is_official_build = true
-    # There's not much point in measuring size without this flag :).
+Creates an interactive size breakdown as a stand-alone html report.
 
-## Optional GN Args:
+## Example Usage:
 
-     is_clang = true
-     # Anecdotally produces more stable symbol names over time.
-     enable_profiling = true
-     # Anecdotally makes symbol lookup more accurate.
-     enable_full_stack_frames_for_profiling = true
-     # With enable_profiling, further improves symbol lookup accuracy but
-     # will completely disable inlining, decreasing spatial accuracy.
+    tools/binary_size/create_html_breakdown.py chrome.size --report-dir size-report -v
+    xdg-open size-report/index.html
 
-# explain_binary_size_delta.py
+# query.py
 
-Prints a delta of two "nm"-formatted outputs from `run_binary_size_analysis.py`.
+Starts a Python interpreter where you can run custom queries.
 
 ## Example Usage:
 
-    tools/binary_size/explain_binary_size_delta.py \
-        --nm1 out/Release/size-report1/nm.out \
-        --nm2 out/Release/size-report2/nm.out \
-        --showsouces --showsymbols # Optional
-
-# Open Issues
-
-Use Monorail label [Tools-BinarySize](https://code.google.com/p/chromium/issues/list?can=2&q=label:Tools-BinarySize).
+    # Run a single query and exit rather than entering interactive mode:
+    tools/binary_size/query.py chrome.size --query 'all_syms.WhereBiggerThan(1000)'
+
+    # Enters a Python REPL:
+    tools/binary_size/query.py chrome.size
+
+# Roadmap:
+
+  Tracked in https://crbug.com/681694
+
+  1. Convert explain_binary_size_delta.py to use new data model.
+  1. More query.py features:
+      * Template Symbols - shows when templates lead to code bloat.
+      * Duplicate Symbols - shows when statics in headers are an issue.
+      * Overloaded Symbols - shows when overloads are excessive.
+      * Per-class / namespace size (no way to distinguish class vs namespace).
+      * Per-Chrome package (Chrome-specific grouping. e.g. name prefixes).
+      * An interactive UI (either drop into python or use a web server).
+  1. More create_html_breakdown.py features:
+      * Convert paths from .o path to .cc path (better breakdowns).
+      * Break down by query.py groupings (use query.py to define GroupBy()s,
+        then render to html graph)
+  1. More analysis.py features:
+      * Find out more about 0xffffffffffffffff addresses, and why such large
+        gaps exist after them.
+      * Use nm to get the full list of symbols that share the same address.
+  1. Integrate with `resource_sizes.py` so that it tracks size of major
+     components separately: chrome vs blink vs skia vs v8.
+  1. Speed up some steps (like normalizing names) via multiprocessing.
+  1. Use resource whitelist information to attribute .pak file size to .o files.