JavaScript:New to SpiderMonkey: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(remove a bunch of old content)
 
(66 intermediate revisions by 21 users not shown)
Line 1: Line 1:
This is a page to help new members of the JS team or new contributors to SpiderMonkey to orient themselves. Please [[JavaScript:New_to_SpiderMonkey#Help_make_this_better|help out]].
== Tutorial: your first patch  ==
== Tutorial: your first patch  ==


Line 10: Line 7:
=== Get the code ===
=== Get the code ===


We work out of the "tracemonkey" branch of the Mozilla Mercurial repository. Download it:
Spidermonkey development happens in the "mozilla-central" mercurial repository:


  hg clone http://hg.mozilla.org/tracemonkey
  hg clone http://hg.mozilla.org/mozilla-central spidermonkey
 
See [https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code/Mercurial/Bundles 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 ===
=== Build the js shell ===


Most of the time, you'll be working with the Javascript shell, instead of the full Firefox browser. So build the shell:  
Most of the time, you'll be working with the JavaScript shell, instead of the full Firefox browser. See the [https://firefox-source-docs.mozilla.org/js/build.html SpiderMonkey build documentation] for how to build the shell.
 
cd tracemonkey/js/src
autoconf2.13
mkdir build_DBG.OBJ
cd build_DBG.OBJ
../configure --enable-debug --disable-optimize
cd ..
 
If you're having trouble or are missing dependencies, refer to [https://developer.mozilla.org/en/SpiderMonkey/Build_Documentation#Building_SpiderMonkey_tip Building SpiderMonkey Tip].


=== Fix something ===
=== Fix something ===
Line 37: Line 27:
Having made the change, build the shell again.  
Having made the change, build the shell again.  


  make -C build_DBG.OBJ
  ./mach build


==== Testing your changes ====
==== Testing your changes ====
Line 43: Line 33:
It builds. Hurray. Time to run the tests to check you haven't broken anything.  
It builds. Hurray. Time to run the tests to check you haven't broken anything.  


  jit-tests/jit_test.py build_DBG.OBJ/js
  ./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:


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:
./mach jstests


tests/jstests.py build_DBG.OBJ/js --args="-m -j -p"


==== Benchmark your changes ====
==== Benchmark your changes ====


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:  
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
  svn checkout http://svn.webkit.org/repository/webkit/trunk/PerformanceTests/SunSpider
Line 58: Line 56:


  cd SunSpider  
  cd SunSpider  
  ./sunspider --args="-m -j -p" --shell=../build_DBG.OBJ/js --run=30 --suite=sunspider-0.9.1  
  ./sunspider --shell=<path-to-shell>/dist/bin/js --run=30 --suite=sunspider-0.9.1  
  cd ..
  cd ..


===== Optimized build =====
===== Optimized build =====


Whoops, we benchmarked the debug version. Let's make an optimized build to test instead.
Whoops, we benchmarked the debug version. Let's make an optimized build. Follow the [https://firefox-source-docs.mozilla.org/js/build.html#optimized-builds build instructions] and make sure your MOZCONFIG file has:


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


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


You'll need that later.  
You'll need that later.  
===== Baseline version / Mercurial Queues =====
We need to time our optimized version against 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.


===== Compare =====
===== Compare =====
Line 100: Line 81:


  cd SunSpider  
  cd SunSpider  
  sunspider-compare-results --shell=build_DBG.OBJ/js FILE1-withoutPatch FILE2-withPatch
  ./sunspider-compare-results --shell=<path-to-shell>/dist/bin/js --suite=sunspider-0.9.1 FILE1-withoutPatch FILE2-withPatch


=== Get a real bug  ===
=== 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 [https://bugzilla.mozilla.org/buglist.cgi?list_id=246047&resolution=---&classification=Components&status_whiteboard_type=substring&query_format=advanced&status_whiteboard=%5Bmentor%3D&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=JavaScript%20Engine&product=Core mentored bug] or a "[https://bugzilla.mozilla.org/buglist.cgi?list_id=246036&resolution=---&classification=Components&status_whiteboard_type=substring&query_format=advanced&status_whiteboard=%5Bgood%20first%20bug%5D&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=JavaScript%20Engine&product=Core Good First 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 [http://www.joshmatthews.net/bugsahoy/?jseng=1&unowned=1 Bugs Ahoy].


Fix the bug, updating the bug report with your progress, and asking questions as you go (either in the bug comments, in [irc://irc.mozilla.org/#jsapi #jsapi], or on [http://infomonkey.cdleary.com InfoMonkey]. When it's done, repeat all the steps above. Then it's time to get your patch into the tree.
Fix the bug, updating the bug report with your progress, and asking questions as you go (either in the bug comments, or in the [https://chat.mozilla.org/#/room/#spidermonkey:mozilla.org 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  ===
=== Submit a patch  ===
Line 112: Line 93:
To get the patch from mercurial, use:  
To get the patch from mercurial, use:  


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


Add it to the bug as an attachment.  
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 ===
=== Get a review ===
Line 121: Line 101:
Nothing gets into the tree without a review, so you'll need one. The [[JavaScript:Hackers|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.
Nothing gets into the tree without a review, so you'll need one. The [[JavaScript:Hackers|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 <code>hg blame</code> on the files you've changed, and check who has been changing related code recently. They're likely to be good candidates.
Alternatively run <code>hg blame</code> 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're mark the patch as "<code>r+</code>" meaning it's now good to commit.
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 "<code>r+</code>" meaning it's now good to commit.


=== Commit ===
=== Commit ===


You can't commit until you have "level 2" access, and you don't have level 2 access, so you'll need someone to do this for you. Try asking in [irc://irc.mozilla.org/#jsapi #jsapi], or add the <code>checkin-needed</code> keyword to the bug. After 3 or 4 patches committed, you can get level 2 access by [https://www.mozilla.org/hacking/commit-access-policy/ applying for it].
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 [irc://irc.mozilla.org/#jsapi #jsapi], or add the <code>checkin-needed</code> keyword to the bug. After you have been contributing for a while, you can get level 3 access by [https://www.mozilla.org/hacking/commit-access-policy/ applying for it].


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://tbpl.mozilla.org/?tree=TraceMonkey the TraceMonkey tree] for failures. Sometimes failures will be spurious: ask [irc://irc.mozilla.org/#jsapi for help] determining when this is the case, to start. (Over time you'll figure out when this is and isn't the case yourself.)
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 [irc://irc.mozilla.org/#jsapi 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 ==
== Overview of the JS engine ==
Line 138: Line 118:
=== High level overviews ===
=== High level overviews ===


http://hacks.mozilla.org/2010/03/a-quick-note-on-javascript-engine-components/
(Outdated) http://hacks.mozilla.org/2010/03/a-quick-note-on-javascript-engine-components/
 
https://developer.mozilla.org/En/SpiderMonkey/Internals
 
http://users.alliedmods.net/~dvander/jm_presentation.pdf
 
http://hacks.mozilla.org/2009/07/tracemonkey-overview/


https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Internals


=== Medium level documentation ===
=== Medium level documentation ===


jsapi.h: http://hg.mozilla.org/tracemonkey/file/tip/js/src/jsapi.h
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
 
Mapping JS idioms to SpiderMonkey code: https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Phrasebook


Frequently used coding recipes and mappings from JS idioms to SpiderMonkey code: https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Cookbook


=== Detailed documentation ===
=== Detailed documentation ===
Line 173: Line 147:
  Go to [https://bugzilla.mozilla.org/userprefs.cgi?tab=email email preferences]
  Go to [https://bugzilla.mozilla.org/userprefs.cgi?tab=email email preferences]
  Watch the user general@spidermonkey.bugs
  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 [irc://irc.mozilla.org/jsapi #jsapi IRC channel].
SpiderMonkey contributors generally hang out in the very active [irc://irc.mozilla.org/jsapi #jsapi IRC channel].


The [https://www.mozilla.org/about/forums/#dev-tech-js-internals js-internals mailing list] is used for communicating with other SpiderMonkey hackers. (<i>Internals</a> as in discussing the internals of the SpiderMonkey engine. All are welcome on the list.).
The [https://www.mozilla.org/about/forums/#dev-tech-js-engine-internals js-internals mailing list] is used for communicating with other SpiderMonkey hackers. (<i>Internals</i> 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:
Reading Planet Mozilla is the best way to keep up with the Mozilla project, which includes some SpiderMonkey related blogs:


  [http://www.bailopan.net/blog/ David Anderson]
  [https://blog.mozilla.org/javascript General JavaScript blog]
[http://blog.mozilla.com/rob-sayre/ Rob Sayre]
  [http://blog.mozilla.com/jorendorff Jason Orendorff]
  [http://blog.mozilla.com/jorendorff Jason Orendorff]
[http://blog.mozilla.com/dmandelin/ David Mandelin]
  [http://blog.mozilla.com/nnethercote/ Nicholas Nethercote]
  [http://blog.mozilla.com/nnethercote/ Nicholas Nethercote]
  [http://whereswalden.com/ Jeff Walden]
  [http://whereswalden.com/ Jeff Walden]
  [https://itcouldbesomuchbetter.wordpress.com Jim Blandy]
  [https://itcouldbesomuchbetter.wordpress.com Jim Blandy]
  [http://blog.cdleary.com Chris Leary]
  [https://jandemooij.nl/ Jan de Mooij]
 
[https://h4writer.com/ Hannes Verschore]
 
[http://rfrn.org/~shu/ Shu-yu Guo]
The Mozilla platform team has a [https://wiki.mozilla.org/Platform#Meetings public weekly meeting] where SpiderMonkey progress is (occasionally) discussed.
[https://blog.benj.me/tag/mozilla.html Benjamin Bouvier]


The [https://developer.mozilla.org/en/SpiderMonkey#Community 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.
The [https://developer.mozilla.org/en/SpiderMonkey#Community 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.
Line 198: Line 171:
=== Repository ===
=== Repository ===


Most active work on SpiderMonkey is done in the [http://hg.mozilla.org/tracemonkey tracemonkey] branch of the mozilla repository. The main Mozilla branch is [http://hg.mozilla.org/mozilla-central Mozilla-central], to which cdleary merges our code each week.
Most active work on SpiderMonkey is done in the [http://hg.mozilla.org/mozilla-central mozilla-central] branch of the mozilla repository.


=== Coding Style ===
=== Coding Style ===


For many years, SpiderMonkey was written in C, and is gradually moving to C++. We still avoid many features such as run-time type information and virtual functions, but have come around to the glory of templates and namespaces relatively recently. Read the [[JavaScript:SpiderMonkey:C++ Coding Style|Coding Style]]. Do NOT read the portability guidelines, which I will not link to, since they are very out of date.
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 ===
=== Workflow ===


As stated above, 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 tracemonkey repository. A link to the commit id is then added as a comment to the bug.
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 [http://hg.mozilla.org/integration/mozilla-inbound 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 [https://treeherder.mozilla.org/#/jobs?repo=mozilla-inbound treeherder] to check for failures caused by our patches, and commits are automatically backed out if errors are found.


Bugs which are fixed in tracemonkey are marked as 'fixed-in-tracemonkey' on the bugzilla whiteboard for the bug. When sayrer merges the code into mozilla-central, those bugs are marked as fixed.
==== Sample Workflows ====


==== Sample Workflows ====
[https://blog.mozilla.org/sfink/2017/06/01/sfink-mozilla-workflow/ Steve Fink: Mozilla workflow]


[http://blog.mozilla.com/nnethercote/2009/07/27/how-i-work-on-tracemonkey/ Nicholas Nethercote: How I work on Tracemonkey]
I (Paul Bone) suggest stating with a [http://mozilla-version-control-tools.readthedocs.io/en/latest/hgmozilla/unifiedrepo.html unified repository] checkout with the extensions and customization from Steve's workflow, using [https://www.mercurial-scm.org/wiki/ShareExtension hg share] to create workspaces, use bookmarks to track your new feature developments, and using [https://www.mercurial-scm.org/wiki/HisteditExtension hg histedit] and [https://www.mercurial-scm.org/wiki/RebaseExtension hg rebase] to prepare your patches for publication.


=== Policy ===
=== Policy ===


The following docs are for the Mozilla project, and differ ever so slightly from what you should do for SpiderMonkey. For example, you may ignore the checkin-needed thing, and ask in #jsapi instead, and you should find reviewers in #jsapi rather than #developers.
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.


[http://www.mozilla.org/hacking/committer/ How to get commit access]
[http://www.mozilla.org/hacking/committer/ How to get commit access]
Line 230: Line 203:
This .hgrc file contains a lot of the wisdom distilled through the wiki:
This .hgrc file contains a lot of the wisdom distilled through the wiki:


[extensions]
mq =
   
   
  [ui]
  [ui]
Line 255: Line 226:
=== Try server  ===
=== Try server  ===


Often, you may be a little wary of breaking things. Mozilla has a [[Build:TryServer|Try Server]] where you can send a patch, and it'll be built on tons of machines which will report back to you.
Often, you may be a little wary of breaking things. Mozilla has a [[Build:TryServer|Try Server]] where you can send a patch, and it'll be built and tested on tons of machines, which report to [https://treeherder.mozilla.org/#/jobs?repo=try TreeHerder]. Although you don't have [https://www.mozilla.org/hacking/commit-access-policy/ 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 [irc://irc.mozilla.org/#jsapi #jsapi]. To be able to push to try-server yourself, you will need "level 1" access, which you can [https://www.mozilla.org/hacking/commit-access-policy/ request] once you've contributed a patch or two.
 
=== Mercurial Queues ===
 
Since most of our lives revolve around patches, and we use Mercurial, nearly everybody uses Mercurial queues.
 
Queues are based on the idea of patch management. Each queue consists of a series of patches, applied sequentially. The aim of the game is to split potential commits into simple, bite-sized chunks which are easy to review. This also makes it simple to experiment without polluting your existing work on a bug, to spin parts off into new bugs, and to rapidly apply and unapply patches (as demonstrated in the tutorial above).
 
==== Enabling ====
 
Add the following snippet to your .hgrc file to enable MQ
 
[extensions]
mq =
 
==== Example MQ workflow ====
 
Clone the repository to deal with a bug:
 
  hg clone http://hg.mozilla.org/tracemonkey
 
Initialize your queue:
 
  hg qinit -c
 
Create a new patch, with some name:
 
  hg qnew first_attempt
 
Work on the patch, try to fix the bug, test, compile, etc.
 
Refresh (save your work into the patch):
 
hg qrefresh
 
Repeat a few times.
 
Rename the patch (because your first name wasn't appliable):
 
hg qrename refactor_the_whatsit
 
Create a new patch to try a logically separate part of the same bug:
 
hg qnew rip_out_the_old_thing
 
Repeat the process a few times, until you have solved the problem. During this time, it can often be useful to go back and forth between patches:
 
hg qpop # unapply a patch
hg qpush # reapply a patch
hg qpop -a # unapply all patches
hg qpush -a # reapply all patches
 
 
Combine all the patches into a single patch, which you submit to bugzilla:
 
hg qpush -a
hg qdiff --rev qparent:. > my_wonderful_patch.patch
 
Commit the patches to your local patch repository, in case you make a mistake (You might do this periodically):
 
hg qcommit -m "Some message. Doesn't have to be good, this won't be committed to the repository, it's just for you"
 
Go back to the old patches and fiddle with them based on feedback:
 
hg qpop
hg qrefresh
etc
 
There are some more complex techniques that we won't go into in detail. You can enable only some patches using qguard and qselect, and you can reorder the patches by manually editing the .hg/patches/series file. But be careful!
 
== Useful information ==
 
[https://developer.mozilla.org/en/Building_with_static_checking Build with Dehydra to get Mozilla-specific static error checking].
 
== Help make this better ==
 
This page is maintained by Paul Biggar (pbiggar@mozilla.com), who is currently new to SpiderMonkey. Please make corrections as you see fit, or email pbiggar@mozilla.com to tell me what made life difficult when you were a newbie.
 
If you're a newbie, and have a question you'd like answered or topic you'd like addressed, please ask, and then add it to this page.
 
If you'd like to help newbies out by offering to review patches or answer newbie-level questions, please add your email address, name or IRC handle below:
 
Will review patches, commit code:
 
Volunteer!
 
Will answer newbie questions:
 
Paul Biggar - pbiggar - pbiggar@mozilla.com


== TODO ==
==== Example workflow ====


* Add tools section:
The workflow is detailed on the contribution page:
** Shark/valgrind
https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html
** Tinderbox/talos


* How do we get bugs for the newbies?


* Other blog posts which have good SpiderMonkey-related content
[[Category:New Contributor Landing Page]]
* List other blogs with a high proportion of SpiderMonkey

Latest revision as of 13:37, 21 September 2020

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

Steve Fink: Mozilla workflow

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.

How to get commit access

How to make patches

Submitting a patch

Supported Platforms

.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

Retrieved from "https://wiki.allizom.org/index.php?title=JavaScript:New_to_SpiderMonkey&oldid=1230966"