JavaScript:New to SpiderMonkey

This is a page to help new member of the JS team or new contributors to SpiderMonkey to orient themselves. It's maintained by Paul Biggar (pbiggar@mozilla.com), who is currently new to SpiderMonkey. Please help by telling me what you found useful when you were new.

Quick getting started tutorial

We'll assume you're on a Unix-y platform, and that you know what you're doing. We'll ignore nearly all details.

Get the code from the repository.

hg clone http://hg.mozilla.org/tracemonkey

The tracemonkey directory is a full copy of all the firefox source code. So we'll need to build it.

cd tracemonkey 
make -f client.mk build # this takes about an hour if you throw 4 cores at it, so this might be a good time to fill in the assignment paperwork (TODO link).

This builds an "out-of-source" build, where the object files and binaries are in obj-i686-pc-linux-gnu.

Do we need a .mozconfig file?

Most of the time, you'll be working with the Javascript shell, instead of the full Firefox browser. So let's build the shell:

cd js/src 
mkdir build_DBG.OBJ 
cd build_DBG.OBJ 
../configure --enable-debug --disable-optimize

At this point, you're ready to make your first fix.

TODO: something useless. Maybe adding a datemicrosecond function.

Having made the change, build the shell again.

cd build_DBG.OBJ 
make

It builds. Hurray. Time to run the tests to check you haven't broken anything.

python trace-tests/trace-test.py build_DBG.OBJ/js

The trace tests are pretty quick, and should give you an idea if you've gotten something wrong. Assuming nothing goes wrong, try the ref-tests:

cd build_DBG.OBJ 
python ../tests/jstests.py ./js --args="-j"

Tests all pass. Congrats, you didn't break anything. Now, did you make it faster or slower? We benchmark using the v8 and SunSpider benchmarks. Get the benchmarks:

svn checkout http://svn.webkit.org/repository/webkit/trunk/SunSpider

And now run them:

cd SunSpider 
./sunspider --args="-j" --shell=../build_DBG.OBJ/js --run=30 --suite=sunspider-0.9.1 
cd ..

So there's a few problems here. First, we tested a debug version. Secondly, we need to compare it against the old version if we're going to see if it got faster. OK, first, let's make an optimized build:

mkdir build_OPT.OBJ 
cd build_OPT.OBJ 
../configure --disable-debug --enable-optimize
make 
cd ..

Repeat the sunspider steps above, and take note of the line that looks like:

Results are located at sunspider-0.9.1-results/sunspider-results-2010-08-07-17.56.48.js

You'll need that later.

So we now need to go back and time the baseline version. This calls for a brief introduction to mercurial queues, which most people think is a pretty good way of managing their SpiderMonkey workflow:

hg qinit
hg qnew my_first_patch -f
hg qrefresh

This puts your current work into a patch, managed by Mercurial, symbolically called my_first_patch. To pop the patch off:

hg qpop

And we're back to our pristine version. So build again and rerun SunSpider again. You should now have two files like:

sunspider-0.9.1-results/sunspider-results-2010-08-07-17.56.48.js

Compare them using the compare script:

cd SunSpider 
sunspider-compare-results FILE1 FILE2

Get a real bug

At this point, you've seen nearly everything you need to do hack on SpiderMonkey. So it's time to get a real bug to work on. Go to the IRC channel, #jsapi on irc.mozilla.org, and say the magic words:

"I'm a beginner who wants to hack on SpiderMonkey. Can anyone give me a starter bug?"

I'm hoping that works, I haven't tried it myself.

Fix the bug, updating the bug report with your progress. When it's done, repeat all the steps above. Then it's time to get your patch into the tree.

Submit a patch

To get the patch from mercurial, use:

hg qdiff # if you're using queues or
hg diff  # if you're not

Add it to the bug as an attachment.

Get a review

Nothing gets into the tree without a review, so you'll need one. The easiest way to get a review is to go to the #jsapi IRC channel on irc.mozilla.org and ask for a volunteer. Point them to the bug. In all likelyhood, they'll give you a review and ask you to change something. Fix what they ask, resubmit the patch to bugzilla, and ask for another review. After you repeat this step a few times, they'll say something like "review=me" meaning it's now good to commit.

Try server

On your first commit, you're likely to be a little wary of breaking things. Mozilla has a "tryserver" where you can send a patch, and it'll be built on tons of machines which will report back to you.

The guide for getting "level 1" access, which you need for the try server, is here. Ask your reviewer to vouch for you, and send in the paperwork ASAP.

Of course, your patch maybe small enough not to need the try server, so you don't always have to

https://wiki.mozilla.org/Build:TryServer

Commit

You can't commit until you have "level 2" access, and you don't have level 2 access (at time of writing, I don't have level 2 access), so you'll need someone to do this for you. The volunteer from IRC may do this, otherwise you'll need a new volunteer.

After committing, a large series of tests will be run to make sure you didn't break anything. You'll need to hang around to make sure you didn't break something. Check http://tests.themasta.com/tinderboxpushlog/?tree=TraceMonkey for red marks.

TODO: we don't want them worrying about false positives either, since there are plenty.

Everything you should know

- Overview
- repository
  - sharing
  - hgrc file
  - useful plugins
  - jaeger + trace + integration
- Tests
- benchmarks
- build a shell
- coding style
  - ignore old doc
  - link to recent doc: JavaScript:SpiderMonkey:C++ Coding Style
  - important compilers and platforms

Workflow

- bugzilla
  - fixed-in-tracemonkey
- following what other team members are doing
  - status page
  - Get alerted to new bugs: From bugzilla, go to your preferences, then click "Email Preferences" then, near the bottom, follow the user "general@spidermonkey.bugs"
- patch policy
- commit access
  - checkin needed
- reviewers
- mercurial queues
- irc
- mailing list

Community

team

- who are they, which faces in phonebook
- who's in "charge"
- blogs and twitterers, etc

users

- firefox is most important
- other users
- exposed APIs