JavaScript:New to SpiderMonkey
Contents
Tutorial: your first patch
The first step to getting involved with SpiderMonkey is to make your first patch. This guides you through it, and at the end you should have learnt a lot of the procedures and formalisms involved in getting things done here.
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
Spidermonkey development happens in the "mozilla-central" mercurial repository:
hg clone http://hg.mozilla.org/mozilla-central spidermonkey
See Mercurial bundles for information about downloading a single large file instead of using "hg clone". Recent versions of Mercurial will do this automatically.
Build the js shell
Most of the time, you'll be working with the JavaScript shell, instead of the full Firefox browser. See the SpiderMonkey build documentation for how to build the shell.
Fix something
At this point, you're ready to make your first fix.
TODO: something useless. Maybe adding a datemicrosecond function.
Building your changes
Having made the change, build the shell again.
./mach build
Testing your changes
It builds. Hurray. Time to run the tests to check you haven't broken anything.
./mach jit-test
The jit-tests are pretty quick, and should give you an idea if you've gotten something wrong. Assuming nothing goes wrong, try the ref-tests:
./mach jstests
Benchmark your changes
Tests all pass. Congrats, you didn't break anything. Now, did you make it faster or slower? We benchmark using a number of different benchmark suites.
- v8
- SunSpider: One of the original js benchmarks. No real value left.
- Octane: Another js benchmark that we heavily optimized for in the past. Isn't representative of current web workloads.
- speedometer: A full browser benchmark. Testing react, ember, etc. Intended to be a better measure of "responsiveness". We are currently optimizing for version 2 it.
Get the benchmarks:
svn checkout http://svn.webkit.org/repository/webkit/trunk/PerformanceTests/SunSpider
And now run them:
cd SunSpider ./sunspider --shell=<path-to-shell>/dist/bin/js --run=30 --suite=sunspider-0.9.1 cd ..
Optimized build
Whoops, we benchmarked the debug version. Let's make an optimized build. Follow the build instructions and make sure your MOZCONFIG file has:
ac_add_options --disable-debug ac_add_options --enable-optimize
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.
Compare
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 --shell=<path-to-shell>/dist/bin/js --suite=sunspider-0.9.1 FILE1-withoutPatch FILE2-withPatch
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. You can get a bug on Bugs Ahoy.
Fix the bug, updating the bug report with your progress, and asking questions as you go (either in the bug comments, or in the SpiderMonkey room on Matrix). 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 diff # if you're not
Add push it using moz-phab. See https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html#to-submit-a-patch for more information.
Get a review
Nothing gets into the tree without a review, so you'll need one. The SpiderMonkey hackers list is a good place to start: if your patch changes something listed as an area of expertise for someone there, that's a good person to ask for a review.
Alternatively run hg blame on the files you've changed, and check who has been changing related code recently. They're likely to be good candidates. An irc bot can automate this process for a single file if you enter "/msg mrgiggles who can review something.cpp?" into your irc client.
The review will consist of comments on your changes, suggesting or requesting alternative ways to do something and asking you to make changes where needed. They might also request additional changes, for example tests. Fix what they ask, resubmit the patch to bugzilla, and ask for another review. After you repeat this step a few times, they will mark the patch as "r+" meaning it's now good to commit.
Commit
You can't commit to mozilla-central / mozilla-inbound until you have "level 3" access, so you'll need someone to do this for you. Try asking in #jsapi, or add the checkin-needed keyword to the bug. After you have been contributing for a while, you can get level 3 access by applying for it.
After committing, a large series of tests will be run to make sure you didn't break anything. You will need to hang around to make sure you didn't break something. It is difficult to determine what failures are real and what are what we call "intermittent oranges" ("orange" because that is the color used on our continuous integration dashboard for test failures). If you do break something, a sheriff will probably let you know via IRC and will probably back your patch out. You can always ask for help determining what is going on. (Over time you'll get a feel for figuring out when breakage is real on your own.)
Overview of the JS engine
The JS engine is a swiftly moving target. The most detailed information is available at https://developer.mozilla.org/en/SpiderMonkey. Here are some particularly interesting, mostly up-to-date resources:
High level overviews
(Outdated) http://hacks.mozilla.org/2010/03/a-quick-note-on-javascript-engine-components/
https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Internals
Medium level documentation
jsapi.h: http://hg.mozilla.org/mozilla-central/file/tip/js/src/jsapi.h and the files in http://hg.mozilla.org/mozilla-central/file/tip/js/public
Frequently used coding recipes and mappings from JS idioms to SpiderMonkey code: https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Cookbook
Detailed documentation
Build: https://developer.mozilla.org/en/SpiderMonkey/Build_Documentation
Testing: https://developer.mozilla.org/en/SpiderMonkey/Running_Automated_JavaScript_Tests
Shell: https://developer.mozilla.org/En/SpiderMonkey/Introduction_to_the_JavaScript_shell
Function reference: https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference
Collaboration and teamwork
Communication (in descending order of information content)
Nearly all communication is handled through Bugzilla. All bugs, feature requests, issues, enhancements, etc, are all referred to as bugs. No code may enter the Mozilla repository without being a patch attached to a bugzilla bug first. To follow all SpiderMonkey related bugs:
Go to email preferences Watch the user general@spidermonkey.bugs Or watch one of the JS components in the Core product: JavaScript Engine, JavaScript Engine: JIT, JavaScript: GC, or JavaScript: Standard Library
SpiderMonkey contributors generally hang out in the very active #jsapi IRC channel.
The js-internals mailing list is used for communicating with other SpiderMonkey hackers. (Internals as in discussing the internals of the SpiderMonkey engine. All are welcome on the list.).
Reading Planet Mozilla is the best way to keep up with the Mozilla project, which includes some SpiderMonkey related blogs:
General JavaScript blog Jason Orendorff Nicholas Nethercote Jeff Walden Jim Blandy Jan de Mooij Hannes Verschore Shu-yu Guo Benjamin Bouvier
The js-engine mailing list is generally used for communicating with people who embed SpiderMonkey, such as asking questions and announcing API changes. No actual development happens on the list.
Code considerations
Repository
Most active work on SpiderMonkey is done in the mozilla-central branch of the mozilla repository.
Coding Style
SpiderMonkey uses the same coding style as Firefox. Please see https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html for more details
Workflow
Everything goes through bugzilla. We find a bug or have an idea, then submit it to bugzilla, then file patches to solve it. When it is solved, the patch is reviewed by team members, and is then committed to the mozilla-inbound repository. A link to the commit is then automatically added as a comment to the bug. mozilla-inbound is periodically merged to mozilla-central by a Sheriff. This exempts us from watching treeherder to check for failures caused by our patches, and commits are automatically backed out if errors are found.
Sample Workflows
I (Paul Bone) suggest stating with a unified repository checkout with the extensions and customization from Steve's workflow, using hg share to create workspaces, use bookmarks to track your new feature developments, and using hg histedit and hg rebase to prepare your patches for publication.
Policy
The following docs are for the Mozilla project, and differ ever so slightly from what you should do for SpiderMonkey. For example, you should find reviewers in #jsapi rather than #developers.
.hgrc file
This .hgrc file contains a lot of the wisdom distilled through the wiki:
[ui] username = First Last <email@domain.tld> [alias] qfulldiff = diff --rev qparent:. [defaults] diff = -p -U 8 qdiff = -p -U 8 qnew = -U commit = -v [diff] git = true showfunc = true unified = 8 [paths] try = ssh://email@domain.tld@hg.mozilla.org/try/
Try server
Often, you may be a little wary of breaking things. Mozilla has a Try Server where you can send a patch, and it'll be built and tested on tons of machines, which report to TreeHerder. Although you don't have access to TryServer just yet, you can get someone else to push it there for you. Just attach a patch to your bug, and ask in a comment, or on #jsapi. To be able to push to try-server yourself, you will need "level 1" access, which you can request once you've contributed a patch or two.
Example workflow
The workflow is detailed on the contribution page: https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html
