================================================================================ __________ .__ \______ \ |__| ____ _____ _______ ___.__. | | _/ | | / \ \__ \ \_ __ \ < | | | | \ | | | | \ / __ \_ | | \/ \___ | |______ / |__| |___| / (____ / |__| / ____| \/ \/ \/ \/ _________ .__ ___________ .__ / _____/ |__| ________ ____ \__ ___/ ____ ____ | | \_____ \ | | \___ / _/ __ \ | | / _ \ / _ \ | | / \ | | / / \ ___/ | | ( <_> ) ( <_> ) | |__ /_______ / |__| /_____ \ \___ > |____| \____/ \____/ |____/ \/ \/ \/ ================================================================================ -------------------------------------------------------------------------------- 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. There are two parts to the Binary Size Tool: 1. run_binary_size_analysis.py This script will produce a detailed breakdown of a binary, including an HTML report and (optionally) a detailed ""nm"-formatted dump of all the symbols with their sources resolved by addr2line. This tool is great for finding the bloat in binaries. 2. explain_binary_size_delta.py This script takes the "nm"-formatted input from two runs of the first tool (run_binary_size_analysis.py) and produces a detailed breakdown of how the symbols have changed between the two binaries that were originally analyzed. The breakdown shows the size changes of symbols as well as which symbols have been added, removed, or changed. This tool is great for thoroughly characterizing the size change resulting from a code change. Because this tool relies solely upon the "nm" output from run_binary_size_analysis.py, it can be run at any time even if the source code described by the "nm" output is no longer available. It is also much faster than run_binary_size_analysis.py, typically completing in a few seconds for even very large binaries. -------------------------------------------------------------------------------- How to Run: run_binary_size_analysis.py -------------------------------------------------------------------------------- Running the tool is fairly simple. 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 * For results that are as spatially accurate as possible, you should always build with a Release configuration so that the end product is as close to the real thing as possible. However, it can sometimes be useful to improve consistency and accuracy of symbol lookup even if it perturbs the overall accuracy of the tool. Consider adding these defines (e.g., via GYP_DEFINES or GN build arguments): clang=1 Anecdotally produces more stable symbol names over time. profiling=1 Anecdotally makes symbol lookup more accurate (note that profiling=1 doesn't work with clang on ARM/Android builds, see https://crbug.com/417323 for more information. profiling_full_stack_frames=1 With profiling=1, should further improve symbol lookup accuracy but will completely disable inlining, further decreasing spatial accuracy. 2. 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, producing an HTML report in /tmp/report and saving the NM output (useful for re-running the tool or analyzing deltas between two builds) under /tmp/report/nm.out: tools/binary_size/run_binary_size_analysis.py \ --library out/Release/lib/libcontent_shell_content_view.so \ --destdir /tmp/report 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) 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. The default number of jobs is 1. Patches to job number auto-selection are welcome! 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. -------------------------------------------------------------------------------- How to Run: explain_binary_size_delta.py -------------------------------------------------------------------------------- Continuing the example, assume that run_binary_size_analysis.py has been run both before and after a code change and that the "nm.out" files have been saved to "nm.out.before" and "nm.out.after". To generate an explanation of the symbol differences between the two runs: tools/binary_size/explain_binary_size_delta.py \ --nm1 nm.out.before --nm2 nm.out.after This will output a concise summary of the symbol changes between the two libraries. Much more information is available by specifying flags like "--showsources" and (for the comprehensive answer) "--showsymbols". Use "--help" for a full list of options. Unlike run_binary_size_analysis.py, this tool doesn't (yet) produce any kind of HTML report. Contributions are welcome. -------------------------------------------------------------------------------- Caveats -------------------------------------------------------------------------------- The tool is not perfect and has several shortcomings: * Not all space in the binary is accounted for. The causes are still under investigation, but there are of course sections in the binary that do not contain symbol information, etceteras. The vast majority of the binary is generally symbols, though, so the discrepancy should be very small. * When dealing with inlining and such, the size cost is attributed to the resource in which the code gets inlined. Depending upon your goals for analysis, this may be either good or bad; fundamentally, the more trickery that the compiler and/or linker do, the less simple the relationship between the original source and the resultant binary. * 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". * There is as yet no way to configure project-specific bindings for symbols/ source files to locations on disk. Such configuration would be useful for manually deduping and disambiguating results. Some day, hopefully, this will be supported. -------------------------------------------------------------------------------- Feature Requests and Bug Reports -------------------------------------------------------------------------------- Please file bugs and feature requests here, making sure to use the label "Tools-BinarySize": https://code.google.com/p/chromium/issues/entry?labels=Tools-BinarySize View all open issues here: https://code.google.com/p/chromium/issues/list?can=2&q=label:Tools-BinarySize