michael@0: This directory contains scripts and a makefile for running Brian Hackett's
michael@0: static GC rooting analysis on a JS source directory.
michael@0: 
michael@0: To use it:
michael@0: 
michael@0: 1. Download and compile sixgill. Make sure the gcc plugin is enabled. (The
michael@0:    configure output will tell you.)
michael@0: 
michael@0:   - [sfink] I needed a couple of patches to get it work on Fedora 16/17/18.
michael@0:     Ask me if you need them.
michael@0: 
michael@0: 2. Compile an optimized JS shell that includes the patch at
michael@0:    <http://people.mozilla.org/~sfink/data/bug-835552-cwd-snarf>. This does not
michael@0:    need to be in the same source tree as you are running these scripts from.
michael@0:    Remember the full path to the resulting JS binary; we'll call it $JS_SHELL
michael@0:    below.
michael@0: 
michael@0: 3. |make clean| in the objdir of the JS source tree that you're going to be
michael@0:    analyzing. (These analysis scripts will default to the tree they are within,
michael@0:    but you can point them at another tree.)
michael@0: 
michael@0: 4. in $objdir/js/src/devtools/analysis, |make JS=$JS_SHELL
michael@0:    SIXGILL=.../path/to/sixgill...|. You may need one or more of the following
michael@0:    additional settings in addition to the |JS| already given:
michael@0: 
michael@0:    - JSOBJDIR: if you are analyzing a different source tree, set this to the
michael@0:      objdir of the tree you want to analyze.
michael@0: 
michael@0:    - ANALYSIS_SCRIPT_DIR: by default, the *.js files within the directory
michael@0:      containing this README will be used, but you can point to a different
michael@0:      directory full. At the time of this writing, there are some changes not in
michael@0:      bhackett's git repo that are necessary, and you'll also need the
michael@0:      gen-hazards.sh shell script.
michael@0: 
michael@0:    - JOBS: set this to the number of parallel jobs you'd like to run the final
michael@0:      analysis pass with. This defaults to 6, somewhat randomly, which gave me a
michael@0:      large speedup even on a machine with only 2 cores.
michael@0: 
michael@0: The results will be in rootingHazards.txt