1# Spidermonkey JSAPI rooting analysis
2
3This directory contains scripts for running Brian Hackett's static GC rooting
4and thread heap write safety analyses on a JS source directory.
5
6The easiest way to get this running is to not try to do the instrumented
7compilation locally. Instead, grab the relevant files from a try server push
8and analyze them locally.
9
10Local Analysis of Downloaded Intermediate Files
11
121. Do a try push with "--upload-xdbs" appended to the try: ..." line.
13
142. Create an empty directory to run the analysis.
15
163. When the try job is complete, download the resulting src_body.xdb.bz2, src_comp.xdb.bz2,
17and file_source.xdb.bz2 files into your directory.
18
194. Build an optimized JS shell with ctypes. Note that this does not need to
20match the source you are analyzing in any way; in fact, you pretty much never
21need to update this once you've built it. (Though I reserve the right to use
22any new JS features implemented in Spidermonkey in the future...)
23
24    mkdir <objdir>
25    cd <objdir>
26    <srcpath>/js/src/configure --disable-debug --enable-optimize --enable-ctypes
27    make -j6 -s
28
295. Clone and build sixgill:
30
31    hg clone https://hg.mozilla.org/users/sfink_mozilla.com/sixgill
32    cd sixgill
33    ./release.sh --build
34
35If you are on osx, the sixgill build will fail horribly. Let it, then do
36
37    make bin/xdb.so CXX=clang++
38
396. Make a defaults.py file containing the following, with your own paths filled in:
40
41    js = "<objdir>/dist/bin/js"
42    sixgill_bin = "<sixgill-dir>/bin"
43
447a. For the rooting analysis, run
45
46    python <srcdir>/js/src/devtools/rootAnalysis/analyze.py gcTypes
47
487b. For the heap write analysis, run
49
50    python <srcdir>/js/src/devtools/rootAnalysis/analyze.py heapwrites
51
52Also, you may wish to run with -v (aka --verbose) to see the exact commands
53executed that you can cut & paste if needed. (I use them to run under the JS
54debugger when I'm working on the analysis.)
55
56----
57
58Or if you *do* want to run the full analysis locally, then you may face the
59dragons. To use it on SpiderMonkey:
60
611.  Be on Fedora/CentOS/RedHat Linux x86_64, or a Docker image of one of those.
62
63    Specifically, the prebuilt GCC **won't work on Ubuntu**
64    without the `CFLAGS` and `CXXFLAGS` settings from
65    <http://trac.wildfiregames.com/wiki/StaticRootingAnalysis>.
66
672.  Have the Gecko build prerequisites installed.
68
693.  Install taskcluster-vcs, eg by doing
70
71        npm install taskcluster-vcs
72        export PATH="$PATH:$(pwd)/node_modules/.bin"
73
744. In some directory, using $SRCDIR as the top of your Gecko source checkout,
75    run these commands:
76
77        mkdir work
78        cd work
79        ( export GECKO_PATH=$SRCDIR; $GECKO_PATH/taskcluster/scripts/builder/build-haz-linux.sh $(pwd) --dep )
80
81The `--dep` is optional, and will avoid rebuilding the JS shell used to run the
82analysis later.
83
84If you see the error ``/lib/../lib64/crti.o: unrecognized relocation (0x2a) in section .init`` then have a version mismatch between the precompiled gcc used in automation and your installed glibc. The easiest way to fix this is to delete the ld provided with the precompiled gcc (it will be in two places, one given in the first part of the error message), which will cause gcc to fall back to your system ld. But you will need to additionally pass ``--no-tooltool`` to build-haz-linux.sh. With the current package, you could do the deletion with
85
86    rm gcc/bin/ld
87    rm gcc/x86_64-unknown-linux-gnu/bin/ld
88
89Output goes to `analysis/hazards.txt`. This will run the
90analysis on the js/src tree only; if you wish to analyze the full browser, use
91
92    ( export GECKO_PATH=$SRCDIR; $GECKO_PATH/taskcluster/scripts/builder/build-haz-linux.sh --project browser $(pwd) )
93
94After running the analysis once, you can reuse the `*.xdb` database files
95generated, using modified analysis scripts, by running
96`analysis/run-analysis.sh` (or pass `--list` to see ways to select even more
97restrictive parts of the overall analysis; the default is `gcTypes` which will
98do everything but regenerate the xdb files).
99
100Also, you can pass `-v` to get exact command lines to cut & paste for running the
101various stages, which is helpful for running under a debugger.
102
103
104## Overview of what is going on here
105
106So what does this actually do?
107
1081.  It downloads a GCC compiler and plugin ("sixgill") from Mozilla servers, using
109    "tooltool" (a binary archive tool).
110
1112. It runs `run_complete`, a script that builds the target codebase with the
112    downloaded GCC, generating a few database files containing control flow
113    graphs of the full compile, along with type information etc.
114
1153.  Then it runs `analyze.py`, a Python script, which runs all the scripts
116    which actually perform the analysis -- the tricky parts.
117    (Those scripts are written in JS.)
118