1 files changed, 116 insertions, 0 deletions
diff --git a/js/src/doc/HazardAnalysis/running.md b/js/src/doc/HazardAnalysis/running.md
new file mode 100644
index 0000000000..d0fb006beb
--- /dev/null
+++ b/js/src/doc/HazardAnalysis/running.md
@@ -0,0 +1,116 @@
+# 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. Unset your $MOZCONFIG
+
+        unset MOZCONFIG
+
+2. Install prerequisites.
+
+        mach hazards bootstrap
+
+3. Build the shell to run the analysis.
+
+        mach hazards build-shell
+
+4. Compile all the code to gather info.
+
+        mach hazards gather --project=js
+
+5. Analyze the gathered info.
+
+        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)
+
+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.
+
+## Overview of what is going on here
+
+So what does this actually do?
+
+1.  It downloads a GCC compiler and plugin ("sixgill") from Mozilla servers.
+
+2. It runs `run_complete`, a script that builds the target codebase with the
+    downloaded GCC, generating a few database files containing control flow
+    graphs of the full compile, along with type information etc.
+
+3.  Then it runs `analyze.py`, a Python script, which runs all the scripts
+    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.)