Running the Rooting Hazard Analysis

The js/src/devtools/rootAnalysis directory contains scripts for running Brian Hackett's static GC rooting and thread heap write safety analyses on a JS source directory.

To run the analysis on SpiderMonkey:

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

unset MOZCONFIG

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

mach hazards bootstrap

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

mach hazards build-shell

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

mach hazards gather --project=js

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

mach hazards analyze --project=js

Output goes to $srctop/haz-js/hazards.txt. This will run the analysis on the js/src tree only; if you wish to analyze the full browser, use

--project=browser

(or leave it off; --project=browser is the default)

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

mach hazards view --project=js

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

be relatively free with

mach hazards clobber

to remove potentially broken files.

After running the analysis once, you can reuse the *.xdb database files generated, using modified analysis scripts, by running either the `mach hazards analyze command above, or by adding on mach hazards analyze <step>` to run a subset of the analysis steps; mach hazards analyze -- --list to see step names.

Also, you can pass -- -v to get exact command lines to cut & paste for running the various stages, which is helpful for running under a debugger.

Incremental Analyses

Once you have an analysis, you can make code changes and rebuild with mach hazards gather. This will add to the existing *.xdb files, which will usually work ok, but sometimes older compilations will have left around information that will get in the way. A typical example is with lambda functions: you may get hazards reported due to lambdas that no longer exist, but the newer compile will not replace them. Although this could be fixed with some amount of effort, you're fighting against something of a fundamental problem where the analysis is depending on certain things NOT happening (eg calls to the GC) and incremental compilation only adds and replaces existing information. It does not remove information unless it is replacing it with something of a matching name (and things like lambdas have autogenerated numbers in their names that vary between compiles.)

In short: for development speed, feel free to use incremental analyses but don't trust them. If the hazard analysis starts claiming the impossible is happening, try mach hazards clobber and do a full rebuild.

Overview of what is going on here

So what does this actually do?

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

downloaded GCC, generating a few database files containing control flow graphs of the full compile, along with type information etc.

1. analyze the .xdb files with scripts in js/src/devtools/rootAnalysis

which actually perform the analysis -- the tricky parts. (Those scripts are written in JS.)

The easiest way to get this running is to not try to do the instrumented compilation locally. Instead, grab the relevant files from a try server push and analyze them locally.

Local Analysis of Downloaded Intermediate Files

Another useful path is to let the continuous integration system do the hard work of generating the intermediate files and analyze them locally. This is particularly useful if you are working on the analysis itself.

• Do a try push with "--upload-xdbs" appended to the try: ..." line.

mach try fuzzy -q "'haz" --upload-xdbs

• Create an empty directory to run the analysis.

• When the try job is complete, download the resulting src_body.xdb.bz2,

src_comp.xdb.bz2, and file_source.xdb.bz2 files into your directory.

• Fetch a compiler and sixgill plugin to use:

mach hazards bootstrap

If you are on osx, these will not be available. Instead, build sixgill manually (these directions are a little stale):

hg clone https://hg.mozilla.org/users/sfink_mozilla.com/sixgill cd sixgill CC=$HOME/.mozbuild/hazard-tools/gcc/bin/gcc ./release.sh --build # This will fail horribly. make bin/xdb.so CXX=clang++

• Build an optimized JS shell with ctypes. Note that this does not need to

match the source you are analyzing in any way; in fact, you pretty much never need to update this once you've built it. (Though I reserve the right to use any new JS features implemented in Spidermonkey in the future...)

mach hazards build-shell

The shell will be placed by default in $topsrcdir/obj-haz-shell.

• Make a defaults.py file containing the following, with your own paths filled in:

js = "<objdir>/dist/bin/js" sixgill_bin = "<sixgill-dir>/bin"

• For the rooting analysis, run

python <srcdir>/js/src/devtools/rootAnalysis/analyze.py gcTypes

• For the heap write analysis, run

python <srcdir>/js/src/devtools/rootAnalysis/analyze.py heapwrites

Also, you may wish to run with -v (aka --verbose) to see the exact commands executed that you can cut & paste if needed. (I use them to run under the JS debugger when I'm working on the analysis.)