pjs/js/src
Graydon Hoare 3eaeae3baf Bug 444023, Add JS functions to stop/start callgrind, r=sayrer 2008-07-08 15:58:08 -07:00
..
config Bug 436263 - cannot convert __va_list_tag** to __va_list_tag (*)[1] in jsapi.cpp building js shell (r=crowder+bclary) 2008-06-12 13:53:12 -05:00
editline
liveconnect [Bug 433382] More efficient interpreter switch when computed goto is not available. r=brendan 2008-06-20 11:55:49 +02:00
xpconnect Bug 444023, Add JS functions to stop/start callgrind, r=sayrer 2008-07-08 15:58:08 -07:00
Makefile.in Bug 422960: Add jemalloc_stats() and jemalloc.h, r=benjamin 2008-06-20 10:34:42 -07:00
Makefile.ref Bug 444023, Add JS functions to stop/start callgrind, r=sayrer 2008-07-08 15:58:08 -07:00
README.html Bug 434532 - Link errors building JS shell on WinXP (actually a documentation bug in js/src/README.html) (r=brendan, a=bsmedberg) 2008-06-03 10:33:00 -05:00
SpiderMonkey.rsp Bug 424399: Remove unused directory "js/src/fdlibm". r+a=shaver 2008-06-19 18:44:10 -07:00
Y.js
build.mk Bug 424399: Remove unused directory "js/src/fdlibm". r+a=shaver 2008-06-19 18:44:10 -07:00
config.mk [Bug 430617] Optimized shell uses the same options as the the non-debug browser build. r=mrbkap, not-part-of-browser-build 2008-07-08 11:15:43 +02:00
javascript-trace.d Bug 401806 - "support building with dtrace enabled on Mac OS X" [p=Ryan r=luser aM9=schrep] 2007-11-01 23:36:49 -07:00
js.cpp Bug 444023, Add JS functions to stop/start callgrind, r=sayrer 2008-07-08 15:58:08 -07:00
js.mdp
js.msg Bug 442333 - remove eval's optional second argument, r=brendan 2008-07-01 16:44:44 -07:00
js.pkg
js3240.rc
jsOS240.def
jsapi.cpp Bug 443746 – Optimizing the enumeration state allocation. r=brendan 2008-07-06 21:02:44 +02:00
jsapi.h [Bug 442242] SM: fixing INT_FITS_IN_JSVAL on 64 bit platforms 2008-06-30 18:36:59 +02:00
jsarena.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsarena.h Bug 417999 - removed JS_ArenaFreeAllocation, r+/a+=brendan 2008-02-18 13:14:15 -08:00
jsarray.cpp Don't use 'i' if the id was not an index. bug 443843, r=shaver 2008-07-07 23:01:09 +02:00
jsarray.h Bug 435345 - Cannot accurately watch the 'length' property of arrays, r=shaver 2008-07-01 12:47:09 -07:00
jsatom.cpp [Bug 432881] SM: JSVAL_VOID as a pseudo-boolean. r=brendan 2008-06-25 11:43:02 +02:00
jsatom.h Break bad old nested include cycle for good, by un-nesting (420554, r=jorendorff, a=vlad). 2008-03-04 15:40:10 -08:00
jsbit.h bug=422432 r=brenda,jag a1.9=blocking1.9 The local free lists for doubles now restricted to 32/64 entries, not 8, to minimize locking penaltties. 2008-03-13 13:07:29 -07:00
jsbool.cpp [Bug 432881] SM: JSVAL_VOID as a pseudo-boolean. r=brendan 2008-06-25 11:43:02 +02:00
jsbool.h [Bug 432881] SM: JSVAL_VOID as a pseudo-boolean. r=brendan 2008-06-25 11:43:02 +02:00
jsclist.h
jscntxt.cpp [Bug 378918] backing out to investigate the tinderbox leak problem 2008-06-24 18:55:06 +02:00
jscntxt.h Bug 443746 – Optimizing the enumeration state allocation. r=brendan 2008-07-06 21:02:44 +02:00
jscompat.h
jsconfig.h Final js1.8 feature: sugar for object destructuring (404734, r=mrbkap). 2008-01-29 22:27:13 -08:00
jsconfig.mk
jscpucfg.cpp Bug 436263 - cannot convert __va_list_tag** to __va_list_tag (*)[1] in jsapi.cpp building js shell (r=crowder+bclary) 2008-06-12 13:53:12 -05:00
jscpucfg.h Bug 415142: Mozilla build broken in mozilla/js/src/jsgc.c:2217. All the compilers we support can handle long long, so just go with that. Also remove ifdefs for compilers we no longer care about. r=/a=brendan 2008-02-19 21:11:01 -08:00
jsdate.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsdate.h NPOTB assertion for Date's 'friend' API, plus comments (410647, r=bclary). 2008-01-03 18:23:55 -08:00
jsdbgapi.cpp Bug 444023, Add JS functions to stop/start callgrind, r=sayrer 2008-07-08 15:58:08 -07:00
jsdbgapi.h Bug 444023, Add JS functions to stop/start callgrind, r=sayrer 2008-07-08 15:58:08 -07:00
jsdhash.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsdhash.h Remove unused getKey callback from PLDHashTableOps/JSDHashTableOps. b=374906 r=bsmedberg 2007-03-27 08:33:38 -07:00
jsdtoa.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsdtoa.h
jsdtracef.c [bug 425957] fixing dtrace breakage caused by incomplete backing out of bug 423874. r,a=none as the code is not apart of the build. 2008-03-29 10:21:39 -07:00
jsdtracef.h Bug 433964 - dtrace build fixes for C++ linkage, r=jorendorff 2008-05-19 12:59:09 -07:00
jsemit.cpp Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jsemit.h Fix bogus js_Emit return value tests (438986, r=igor). 2008-06-18 18:50:33 -07:00
jsexn.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsexn.h
jsfile.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsfile.h
jsfile.msg
jsfun.cpp [Bug 411575] SM: faster js_PutCallObject, r=brendan 2008-06-30 19:17:33 +02:00
jsfun.h Bug 430955 - "jsfun.h uses JSArenaPool without needed typename" [p=mh+mozilla@glandium.org (Mike Hommey) r=brendan a1.9=damons] 2008-05-09 00:40:10 -07:00
jsgc.cpp Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jsgc.h [Bug 378918] backing out to investigate the tinderbox leak problem 2008-06-24 18:55:06 +02:00
jshash.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jshash.h * Menu of -D flags for enabling instrumentation, as a commented-out CFLAGS += setting for convenient testing. * js_FindProperty and js_LookupPropertyWithFlags return indexes into the scope and prototype chains, respectively, to support internal instrumentation, and to pave the way for the return of the property cache (bug 365851).. * jsutil.[ch] JSBasicStats struct and functions for computing mean/sigma/max and auto-scaling histogram. * JS_SCOPE_DEPTH_METER instrumentation for compile- and run-time scope chain length instrumentation: + At compile time, rt->hostenvScopeDepthStats and rt->lexicalScopeDepthStats meter scope chains passed into the compile and evaluate APIs. + At runtime, rt->protoLookupDepthStats and rt->scopeSearchDepthStats track steps along the prototype and scope chains until the sought-after property is found. * JS_ARENAMETER uses JSBasicStats now. * Added rt->liveScopePropsPreSweep to fix the property tree stats code that rotted when property tree sweeping moved to after the finalization phase. * Un-bitrotted some DEBUG_brendan code, turned some off for myself via XXX. * Mac OS X toolchain requires initialized data shared across dynamic library member files, outlaws common data, so initialize extern metering vars. * Old HASHMETER code in jshash.[ch] is now JS_HASHMETER-controlled and based on JSBasicStats. * DEBUG_scopemeters macro renamed JS_DUMP_SCOPE_METERS; uses JSBasicStats now. * Disentangle DEBUG and DUMP_SCOPE_STATS (now JS_DUMP_PROPTREE_STATS) and fix inconsistent thread safety for liveScopeProps (sometimes atomic-incremented, sometimes runtime-locked). * Compiler-modeled maxScopeDepth will propagate via JSScript to runtime for capability-based, interpreter-inlined cache hit qualifier bits, to bypass scope and prototype chain lookup by optimizing for common monomorphic get, set, and call site referencing a prototype property in a well-named object (no shadowing or mutation in 99.9% of the cases). 2008-01-12 16:31:31 -08:00
jsify.pl
jsinterp.cpp Follow the invariant that we flow through label exit2. bug 442358, r=igor 2008-07-08 14:04:02 +02:00
jsinterp.h [Bug 432881] SM: JSVAL_VOID as a pseudo-boolean. r=brendan 2008-06-25 11:43:02 +02:00
jsinvoke.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsiter.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsiter.h Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jskeyword.tbl
jskwgen.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jslibmath.h Bug 424399: Remove unused directory "js/src/fdlibm". r+a=shaver 2008-06-19 18:44:10 -07:00
jslock.cpp b=429387, add --with-arm-kuser; use it in JS, and pass it down to NSPR's configure; r=shaver,r=ted 2008-06-04 14:14:11 -07:00
jslock.h b=429387, add --with-arm-kuser; use it in JS, and pass it down to NSPR's configure; r=shaver,r=ted 2008-06-04 14:14:11 -07:00
jslocko.asm
jslog2.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jslong.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jslong.h Bug 428128 - Removal of legacy JSLL_ routines, r=brendan, a=mtschrep 2008-04-25 11:40:05 -07:00
jsmath.cpp Bug 424399: Remove unused directory "js/src/fdlibm". r+a=shaver 2008-06-19 18:44:10 -07:00
jsmath.h
jsnum.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsnum.h bug=419632 r=brendan a1.9=blockin1.9 avoiding weak roots for doubles 2008-03-10 12:27:44 -07:00
jsobj.cpp Bug 443746 – Optimizing the enumeration state allocation. r=brendan 2008-07-06 21:02:44 +02:00
jsobj.h Bug 443746 – Optimizing the enumeration state allocation. r=brendan 2008-07-06 21:02:44 +02:00
jsopcode.cpp Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jsopcode.h [Bug 433382] More efficient interpreter switch when computed goto is not available. r=brendan 2008-06-20 11:55:49 +02:00
jsopcode.tbl Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jsoplengen.cpp [Bug 433382] More efficient interpreter switch when computed goto is not available. r=brendan 2008-06-20 11:55:49 +02:00
jsotypes.h
jsparse.cpp Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jsparse.h Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jsprf.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsprf.h Bug 397215: Runtime option to switch to UTF-8 encoding in byte <-> jschar conversiions. Patch from Sam Ruby with some changes by me. r,a=brendan 2007-12-11 02:09:58 -08:00
jsproto.tbl bug=420399 r=brendan a1.9=blocking1.9 eliminating the pc stack in the interpreter 2008-03-04 15:30:58 -08:00
jsprvtd.h Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jspubtd.h Return of the property cache (365851, r=shaver). 2008-02-07 15:18:45 -08:00
jsregexp.cpp Don't do things to the object before we're sure it's the right type of object. bug 443569, r=brendan 2008-07-07 23:00:56 +02:00
jsregexp.h bug 397289: removing JSParseNode.pn_ts. r,a=brendan 2007-11-13 14:18:17 -08:00
jsreops.tbl Bug 397773 - mozilla-central has pedantic errors because of extra commas, r=mrbkap+brendan a=brendan 2007-10-05 06:58:51 -07:00
jsscan.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsscan.h bug 397289: removing JSParseNode.pn_ts. r,a=brendan 2007-11-13 14:18:17 -08:00
jsscope.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsscope.h Fix hang when GetPropertyTreeChild calls js_GenerateShape calls js_GC (424636, r=igor, a=beltzner). 2008-04-28 23:19:42 -07:00
jsscript.cpp Bug 440473 - Crash [@ Decompile][@ js_GetSrcNoteOffset] with firebug/jQuery, r=igor 2008-06-25 13:50:26 -07:00
jsscript.h [Bug 423874] Allocating functions together with JSObject. r=brendan a1.9=blocking1.9 2008-04-02 00:46:12 -07:00
jsshell.msg
jsstddef.h
jsstr.cpp Backout changeset 1f599577eca2 (bug 432525) due to mochitest failures 2008-06-13 20:38:33 +12:00
jsstr.h Fix hang when GetPropertyTreeChild calls js_GenerateShape calls js_GC (424636, r=igor, a=beltzner). 2008-04-28 23:19:42 -07:00
jstypes.h Bug 415142: Mozilla build broken in mozilla/js/src/jsgc.c:2217. All the compilers we support can handle long long, so just go with that. Also remove ifdefs for compilers we no longer care about. r=/a=brendan 2008-02-19 21:11:01 -08:00
jsutil.cpp Bug 441303 - jsutil.cpp does not compile with Visual Studio 2003. r=crowder 2008-06-25 15:06:43 +01:00
jsutil.h * Menu of -D flags for enabling instrumentation, as a commented-out CFLAGS += setting for convenient testing. * js_FindProperty and js_LookupPropertyWithFlags return indexes into the scope and prototype chains, respectively, to support internal instrumentation, and to pave the way for the return of the property cache (bug 365851).. * jsutil.[ch] JSBasicStats struct and functions for computing mean/sigma/max and auto-scaling histogram. * JS_SCOPE_DEPTH_METER instrumentation for compile- and run-time scope chain length instrumentation: + At compile time, rt->hostenvScopeDepthStats and rt->lexicalScopeDepthStats meter scope chains passed into the compile and evaluate APIs. + At runtime, rt->protoLookupDepthStats and rt->scopeSearchDepthStats track steps along the prototype and scope chains until the sought-after property is found. * JS_ARENAMETER uses JSBasicStats now. * Added rt->liveScopePropsPreSweep to fix the property tree stats code that rotted when property tree sweeping moved to after the finalization phase. * Un-bitrotted some DEBUG_brendan code, turned some off for myself via XXX. * Mac OS X toolchain requires initialized data shared across dynamic library member files, outlaws common data, so initialize extern metering vars. * Old HASHMETER code in jshash.[ch] is now JS_HASHMETER-controlled and based on JSBasicStats. * DEBUG_scopemeters macro renamed JS_DUMP_SCOPE_METERS; uses JSBasicStats now. * Disentangle DEBUG and DUMP_SCOPE_STATS (now JS_DUMP_PROPTREE_STATS) and fix inconsistent thread safety for liveScopeProps (sometimes atomic-incremented, sometimes runtime-locked). * Compiler-modeled maxScopeDepth will propagate via JSScript to runtime for capability-based, interpreter-inlined cache hit qualifier bits, to bypass scope and prototype chain lookup by optimizing for common monomorphic get, set, and call site referencing a prototype property in a well-named object (no shadowing or mutation in 99.9% of the cases). 2008-01-12 16:31:31 -08:00
jsxdrapi.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsxdrapi.h Clean up for-in ops and naming nit (443039, r=igor). 2008-07-01 18:59:18 -07:00
jsxml.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
jsxml.h Bug 309894: non-recursive XML-filtering implementation. r,a1.9=brendan 2008-02-13 06:32:31 -08:00
lock_SunOS.s
perfect.js
plify_jsdhash.sed Consolidate duplicated code into the beginning of the double-hashing loop. b=374906 r=brendan 2007-03-27 08:32:38 -07:00
prmjtime.cpp Return to building spidermonkey as C++, because we believe we found the cause of the perf regression elsewhere (non-code). 2008-05-27 16:58:12 -04:00
prmjtime.h Bug 398485 - "Date toLocaleString() clamps the year to -32767 .. 32767" [p=mats.palmgren@bredband.net (Mats Palmgren) r=crowder a1.9=schrep] 2007-11-12 22:39:16 -08:00
resource.h
rules.mk [Bug 433382] More efficient interpreter switch when computed goto is not available. r=brendan 2008-06-20 11:55:49 +02:00
win32.order Bug 416601: property cache is properly disabled under with statements with generators. r=brendan a1.9=blocking1.9 2008-02-15 03:38:40 -08:00

README.html

<!-- ***** BEGIN LICENSE BLOCK *****
   - Version: MPL 1.1/GPL 2.0/LGPL 2.1
   -
   - The contents of this file are subject to the Mozilla Public License Version
   - 1.1 (the "License"); you may not use this file except in compliance with
   - the License. You may obtain a copy of the License at
   - http://www.mozilla.org/MPL/
   -
   - Software distributed under the License is distributed on an "AS IS" basis,
   - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
   - for the specific language governing rights and limitations under the
   - License.
   - 
   - The Original Code is Mozilla Communicator client code, released
   - March 31, 1998.
   - 
   - The Initial Developer of the Original Code is
   - Netscape Communications Corporation.
   - Portions created by the Initial Developer are Copyright (C) 1998-1999
   - the Initial Developer. All Rights Reserved.
   - 
   - Contributor(s):
   - 
   - Alternatively, the contents of this file may be used under the terms of
   - either of the GNU General Public License Version 2 or later (the "GPL"),
   - or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
   - in which case the provisions of the GPL or the LGPL are applicable instead
   - of those above. If you wish to allow use of your version of this file only
   - under the terms of either the GPL or the LGPL, and not to allow others to
   - use your version of this file under the terms of the MPL, indicate your
   - decision by deleting the provisions above and replace them with the notice
   - and other provisions required by the GPL or the LGPL. If you do not delete
   - the provisions above, a recipient may use your version of this file under
   - the terms of any one of the MPL, the GPL or the LGPL.
   -
   - ***** END LICENSE BLOCK ***** -->
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; I) [Netscape]">
   <title>JavaScript Reference Implementation (JSRef) README</title>
</head>
<body>

<h2>
Table of Contents</h2>

<ul>
<li>
<a href="#Introduction">Introduction</a></li>

<li>
<a href="#Build">Build instructions</a></li>

<li>
<a href="#Debugging">Debugging notes</a></li>

<li>
<a href="#Conventions">Naming and coding conventions</a></li>

<li>
<a href="#JSAPI">Using the JS API</a></li>

<li>
<a href="#Design">Design walk-through</a></li>

<li>
<a href="#Resources">Additional Resources (links, API docs, and newsgroups)</a></li>

</ul>

<h2>
<a NAME="Introduction"></a>Introduction</h2>
This is the README file for the&nbsp;<span CLASS=LXRSHORTDESC>JavaScript
Reference (JSRef, now better known as SpiderMonkey) implementation.</span>
It consists of build instructions, source code conventions, a design
walk-through, and a brief file-by-file description of the source.
<p><span CLASS=LXRLONGDESC>JSRef builds a library or DLL containing the
JavaScript runtime (compiler, interpreter, decompiler, garbage collector,
atom manager, standard classes). It then compiles a small "shell" program
and links that with the library to make an interpreter that can be used
interactively and with test .js files to run scripts.&nbsp; The code has
no dependencies on the rest of the Mozilla codebase.</span>
<p><i>Quick start tip</i>: skip to "Using the JS API" below, build the
js shell, and play with the object named "it" (start by setting 'it.noisy
= true').

<h2>
<a NAME="Build"></a>Build instructions</h2>

<p>To build the standalone JavaScript engine, see the
<a href="http://developer.mozilla.org/en/docs/SpiderMonkey_Build_Documentation">SpiderMonkey
build documentation</a> page.</p>

<p>To build within the browser, use the
<a href="http://developer.mozilla.org/en/docs/Build_Documentation">Mozilla
build documentation</a> instead.</p>

<h2>
<a NAME="Debugging"></a>Debugging notes</h2>

<ul>
<li>
To turn on GC instrumentation, define <tt>JS_GCMETER</tt>.</li>

<li>
To dump the JS heap use the JS_DumpHeap API, available in DEBUG
builds. For an example of how to call it, see the DumpHeap function in
js.cpp.</li>

<li>
To turn on the arena package's instrumentation, define <tt>JS_ARENAMETER</tt>.</li>

<li>
To turn on the hash table package's metering, define <tt>JS_HASHMETER</tt>.</li>
</ul>

<h2>
<a NAME="Conventions"></a>Naming and coding conventions</h2>

<ul>
<li>
Public function names begin with <tt>JS_</tt> followed by capitalized "intercaps",
e.g. <tt>JS_NewObject</tt>.</li>

<li>
Extern but library-private function names use a <tt>js_</tt> prefix and
mixed case, e.g. <tt>js_SearchScope</tt>.</li>

<li>
Most static function names have unprefixed, mixed-case names: <tt>GetChar</tt>.</li>

<li>
But static native methods of JS objects have lowercase, underscore-separated
or intercaps names, e.g., <tt>str_indexOf</tt>.</li>

<li>
And library-private and static data use underscores, not intercaps (but
library-private data do use a <tt>js_</tt> prefix).</li>

<li>
Scalar type names are lowercase and js-prefixed: <tt>jsdouble</tt>.</li>

<li>
Aggregate type names are JS-prefixed and mixed-case: <tt>JSObject.</tt></li>

<li>
Macros are generally <tt>ALL_CAPS </tt>and underscored, to call out potential
side effects, multiple uses of a formal argument, etc.</li>

<li>
Four spaces of indentation per statement nesting level.</li>

<li>
Tabs are taken to be eight spaces, and an Emacs magic comment at the top
of each file tries to help. If you're using MSVC or similar, you'll want
to set tab width to 8, and help convert these files to be space-filled.
<font color="#CC0000">Do not add hard tabs to source files; do remove them
whenever possible.</font></li>

<li>
DLL entry points have their return type expanded within a <tt>JS_PUBLIC_API()</tt>
macro call, to get the right Windows secret type qualifiers in the right
places for all build variants.</li>

<li>
Callback functions that might be called from a DLL are similarly macroized
with <tt>JS_STATIC_DLL_CALLBACK</tt> (if the function otherwise would be
static to hide its name) or <tt>JS_DLL_CALLBACK</tt> (this macro takes
no type argument; it should be used after the return type and before the
function name).</li>
</ul>

<h2>
<a NAME="JSAPI"></a>Using the JS API</h2>

<p>The core JSAPI documentation is hosted on the Mozilla Developer Center.</p>

<ul>

<li><p>The <a href="http://developer.mozilla.org/en/docs/JSAPI_User_Guide">JSAPI
User Guide</a> explains the basic JSAPI concepts and includes large chunks
of sample code.</p></li>

<li><p>The <a href="http://developer.mozilla.org/en/docs/JSAPI_Phrasebook">JSAPI
Phrasebook</a> shows the JSAPI translation of some commonly used
JavaScript expressions and statements.</p></li>

<li><p>The <a href="http://developer.mozilla.org/en/docs/JSAPI_Reference">JSAPI
Reference</a> contains detailed documentation for each JSAPI
feature.</p></li>

</ul>

<h4>
Debugging API</h4>
See the<tt> trap, untrap, watch, unwatch, line2pc</tt>, and <tt>pc2line</tt>
commands in <tt>js.c</tt>. Also the (scant) comments in <i>jsdbgapi.h</i>.
<h2>
<a NAME="Design"></a>Design walk-through</h2>
This section must be brief for now -- it could easily turn into a book.
<h4>
JS "JavaScript Proper"</h4>
JS modules declare and implement the JavaScript compiler, interpreter,
decompiler, GC and atom manager, and standard classes.
<p>JavaScript uses untyped bytecode and runtime type tagging of data values.
The <tt>jsval</tt> type is a signed machine word that contains either a
signed integer value (if the low bit is set), or a type-tagged pointer
or boolean value (if the low bit is clear). Tagged pointers all refer to
8-byte-aligned things in the GC heap.
<p>Objects consist of a possibly shared structural description, called
the map or scope; and unshared property values in a vector, called the
slots. Object properties are associated with nonnegative integers stored
in <tt>jsval</tt>'s, or with atoms (unique string descriptors) if named
by an identifier or a non-integral index expression.
<p>Scripts contain bytecode, source annotations, and a pool of string,
number, and identifier literals. Functions are objects that extend scripts
or native functions with formal parameters, a literal syntax, and a distinct
primitive type ("function").
<p>The compiler consists of a recursive-descent parser and a random-logic
rather than table-driven lexical scanner. Semantic and lexical feedback
are used to disambiguate hard cases such as missing semicolons, assignable
expressions ("lvalues" in C parlance), etc. The parser generates bytecode
as it parses, using fixup lists for downward branches and code buffering
and rewriting for exceptional cases such as for loops. It attempts no error
recovery. The interpreter executes the bytecode of top-level scripts, and
calls itself indirectly to interpret function bodies (which are also scripts).
All state associated with an interpreter instance is passed through formal
parameters to the interpreter entry point; most implicit state is collected
in a type named JSContext. Therefore, all API and almost all other functions
in JSRef take a JSContext pointer as their first argument.
<p>The decompiler translates postfix bytecode into infix source by consulting
a separate byte-sized code, called source notes, to disambiguate bytecodes
that result from more than one grammatical production.
<p>The GC is a mark-and-sweep, non-conservative (exact) collector. It
can allocate only fixed-sized things -- the current size is two machine
words. It is used to hold JS object and string descriptors (but not property
lists or string bytes), and double-precision floating point numbers. It
runs automatically only when maxbytes (as passed to <tt>JS_NewRuntime()</tt>)
bytes of GC things have been allocated and another thing-allocation request
is made. JS API users should call <tt>JS_GC()</tt> or <tt>JS_MaybeGC()</tt>
between script executions or from the branch callback, as often as necessary.
<p>An important point about the GC's "exactness": you must add roots for
new objects created by your native methods if you store references to them
into a non-JS structure in the malloc heap or in static data. Also, if
you make a new object in a native method, but do not store it through the
<tt>rval</tt>
result parameter (see math_abs in the "Using the JS API" section above)
so that it is in a known root, the object is guaranteed to survive only
until another new object is created. Either lock the first new object when
making two in a row, or store it in a root you've added, or store it via
rval.
See the <a href="http://www.mozilla.org/js/spidermonkey/gctips.html">GC tips</a>
document for more.
<p>The atom manager consists of a hash table associating strings uniquely
with scanner/parser information such as keyword type, index in script or
function literal pool, etc. Atoms play three roles in JSRef: as literals
referred to by unaligned 16-bit immediate bytecode operands, as unique
string descriptors for efficient property name hashing, and as members
of the root GC set for exact GC.
<p>Native objects and methods for arrays, booleans, dates, functions, numbers,
and strings are implemented using the JS API and certain internal interfaces
used as "fast paths".
<p>In general, errors are signaled by false or unoverloaded-null return
values, and are reported using <tt>JS_ReportError()</tt> or one of its
variants by the lowest level in order to provide the most detail. Client
code can substitute its own error reporting function and suppress errors,
or reflect them into Java or some other runtime system as exceptions, GUI
dialogs, etc..
<h2>
File walk-through (OUT OF DATE!)</h2>

<h4>
jsapi.c, jsapi.h</h4>
The public API to be used by almost all client code.&nbsp; If your client
code can't make do with <tt>jsapi.h</tt>, and must reach into a friend
or private js* file, please let us know so we can extend <tt>jsapi.h</tt>
to include what you need in a fashion that we can support over the long
run.
<h4>
jspubtd.h, jsprvtd.h</h4>
These files exist to group struct and scalar typedefs so they can be used
everywhere without dragging in struct definitions from N different files.
The <tt>jspubtd.h</tt> file contains public typedefs, and is included by
<tt>jsapi.h</tt>.
The <tt>jsprvtd.h</tt> file contains private typedefs and is included by
various .h files that need type names, but not type sizes or declarations.
<h4>
jsdbgapi.c, jsdbgapi.h</h4>
The Debugging API, still very much under development. Provided so far:
<ul>
<li>
Traps, with which breakpoints, single-stepping, step over, step out, and
so on can be implemented. The debugger will have to consult jsopcode.def
on its own to figure out where to plant trap instructions to implement
functions like step out, but a future jsdbgapi.h will provide convenience
interfaces to do these things. At most one trap per bytecode can be set.
When a script (<tt>JSScript</tt>) is destroyed, all traps set in its bytecode
are cleared.</li>

<li>
Watchpoints, for intercepting set operations on properties and running
a debugger-supplied function that receives the old value and a pointer
to the new one, which it can use to modify the new value being set.</li>

<li>
Line number to PC and back mapping functions. The line-to-PC direction
"rounds" toward the next bytecode generated from a line greater than or
equal to the input line, and may return the PC of a for-loop update part,
if given the line number of the loop body's closing brace. Any line after
the last one in a script or function maps to a PC one byte beyond the last
bytecode in the script. An example, from perfect.js:</li>

<pre><tt>14&nbsp;&nbsp; function perfect(n)
15&nbsp;&nbsp; {
16&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print("The perfect numbers up to " +&nbsp; n + " are:");
17
18&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // We build sumOfDivisors[i] to hold a string expression for
19&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // the sum of the divisors of i, excluding i itself.
20&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; var sumOfDivisors = new ExprArray(n+1,1);
21&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; for (var divisor = 2; divisor &lt;= n; divisor++) {
22&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; for (var j = divisor + divisor; j &lt;= n; j += divisor) {
23&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sumOfDivisors[j] += " + " + divisor;
24&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
25&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // At this point everything up to 'divisor' has its sumOfDivisors
26&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // expression calculated, so we can determine whether it's perfect
27&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // already by evaluating.
28&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if (eval(sumOfDivisors[divisor]) == divisor) {
29&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print("" + divisor + " = " + sumOfDivisors[divisor]);
30&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
31&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
32&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; delete sumOfDivisors;
33&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print("That's all.");
34&nbsp;&nbsp; }</tt></pre>
The line number to PC and back mappings can be tested using the js program
with the following script:
<pre><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; load("perfect.js")
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print(perfect)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; dis(perfect)

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print()
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; for (var ln = 0; ln &lt;= 40; ln++) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; var pc = line2pc(perfect,ln)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; var ln2 = pc2line(perfect,pc)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print("\tline " + ln + " => pc " + pc + " => line " + ln2)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }</tt></pre>
The result of the for loop over lines 0 to 40 inclusive is:
<pre><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 0 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 1 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 2 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 3 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 4 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 5 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 6 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 7 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 8 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 9 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 10 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 11 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 12 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 13 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 14 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 15 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 16 => pc 0 => line 16
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 17 => pc 19 => line 20
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 18 => pc 19 => line 20
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 19 => pc 19 => line 20
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 20 => pc 19 => line 20
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 21 => pc 36 => line 21
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 22 => pc 53 => line 22
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 23 => pc 74 => line 23
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 24 => pc 92 => line 22
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 25 => pc 106 => line 28
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 26 => pc 106 => line 28
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 27 => pc 106 => line 28
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 28 => pc 106 => line 28
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 29 => pc 127 => line 29
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 30 => pc 154 => line 21
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 31 => pc 154 => line 21
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 32 => pc 161 => line 32
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 33 => pc 172 => line 33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 34 => pc 172 => line 33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 35 => pc 172 => line 33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 36 => pc 172 => line 33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 37 => pc 172 => line 33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 38 => pc 172 => line 33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 39 => pc 172 => line 33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; line 40 => pc 172 => line 33</tt></pre>
</ul>

<h4>
jsconfig.h</h4>
Various configuration macros defined as 0 or 1 depending on how <tt>JS_VERSION</tt>
is defined (as 10 for JavaScript 1.0, 11 for JavaScript 1.1, etc.). Not
all macros are tested around related code yet. In particular, JS 1.0 support
is missing from JSRef. JS 1.2 support will appear in a future JSRef release.
<br>&nbsp;
<h4>
js.c</h4>
The "JS shell", a simple interpreter program that uses the JS API and more
than a few internal interfaces (some of these internal interfaces could
be replaced by <tt>jsapi.h</tt> calls). The js program built from this
source provides a test vehicle for evaluating scripts and calling functions,
trying out new debugger primitives, etc.
<h4>
jsarray.*, jsbool.*, jdsdate.*, jsfun.*, jsmath.*, jsnum.*, jsstr.*</h4>
These file pairs implement the standard classes and (where they exist)
their underlying primitive types. They have similar structure, generally
starting with class definitions and continuing with internal constructors,
finalizers, and helper functions.
<h4>
jsobj.*, jsscope.*</h4>
These two pairs declare and implement the JS object system. All of the
following happen here:
<ul>
<li>
creating objects by class and prototype, and finalizing objects;</li>

<li>
defining, looking up, getting, setting, and deleting properties;</li>

<li>
creating and destroying properties and binding names to them.</li>
</ul>
The details of a native object's map (scope) are mostly hidden in
<tt>jsscope.[ch]</tt>.
<h4>
jsatom.c, jsatom.h</h4>
The atom manager. Contains well-known string constants, their atoms, the
global atom hash table and related state, the js_Atomize() function that
turns a counted string of bytes into an atom, and literal pool (<tt>JSAtomMap</tt>)
methods.
<h4>
jsgc.c, jsgc.h</h4>
[TBD]
<h4>
jsinterp.*, jscntxt.*</h4>
The bytecode interpreter, and related functions such as Call and AllocStack,
live in <i>jsinterp.c</i>. The JSContext constructor and destructor are
factored out into <i>jscntxt.c</i> for minimal linking when the compiler
part of JS is split from the interpreter part into a separate program.
<h4>
jsemit.*, jsopcode.tbl, jsopcode.*, jsparse.*, jsscan.*, jsscript.*</h4>
Compiler and decompiler modules. The <i>jsopcode.tbl</i> file is a C preprocessor
source that defines almost everything there is to know about JS bytecodes.
See its major comment for how to use it. For now, a debugger will use it
and its dependents such as <i>jsopcode.h</i> directly, but over time we
intend to extend <i>jsdbgapi.h</i> to hide uninteresting details and provide
conveniences. The code generator is split across paragraphs of code in
<i>jsparse.c</i>,
and the utility methods called on <tt>JSCodeGenerator</tt> appear in <i>jsemit.c</i>.
Source notes generated by <i>jsparse.c</i> and
<i>jsemit.c</i> are used
in <i>jsscript.c</i> to map line number to program counter and back.
<h4>
jstypes.h, jslog2.c</h4>
Fundamental representation types and utility macros. This file alone among
all .h files in JSRef must be included first by .c files. It is not nested
in .h files, as other prerequisite .h files generally are, since it is
also a direct dependency of most .c files and would be over-included if
nested in addition to being directly included. The one "not-quite-a-macro
macro" is the <tt>JS_CeilingLog2()</tt> function in <i>jslog2.c</i>.
<h4>
jsarena.c, jsarena.h</h4>
Last-In-First-Out allocation macros that amortize malloc costs and allow
for en-masse freeing. See the paper mentioned in prarena.h's major comment.
<h4>
jsutil.c, jsutil.h</h4>
The <tt>JS_ASSERT</tt> macro is used throughout JSRef source as a proof
device to make invariants and preconditions clear to the reader, and to
hold the line during maintenance and evolution against regressions or violations
of assumptions that it would be too expensive to test unconditionally at
run-time. Certain assertions are followed by run-time tests that cope with
assertion failure, but only where I'm too smart or paranoid to believe
the assertion will never fail...
<h4>
jsclist.h</h4>
Doubly-linked circular list struct and macros.
<h4>
jscpucfg.c</h4>
This standalone program generates <i>jscpucfg.h</i>, a header file containing
bytes per word and other constants that depend on CPU architecture and
C compiler type model. It tries to discover most of these constants by
running its own experiments on the build host, so if you are cross-compiling,
beware.
<h4>
prdtoa.c, prdtoa.h</h4>
David Gay's portable double-precision floating point to string conversion
code, with Permission To Use notice included.
<h4>
prhash.c, prhash.h</h4>
Portable, extensible hash tables. These use multiplicative hash for strength
reduction over division hash, yet with very good key distribution over
power of two table sizes. Collisions resolve via chaining, so each entry
burns a malloc and can fragment the heap.
<h4>
prlong.c, prlong.h</h4>
64-bit integer emulation, and compatible macros that use C's long long
type where it exists (my last company mapped long long to a 128-bit type,
but no real architecture does 128-bit ints yet).
<h4>
jsprf.*</h4>
Portable, buffer-overrun-resistant sprintf and friends. For no good reason
save lack of time, the %e, %f, and %g formats cause your system's native
sprintf, rather than <tt>JS_dtoa()</tt>, to be used. This bug doesn't affect
JSRef, because it uses its own <tt>JS_dtoa()</tt> call in <i>jsnum.c</i>
to convert from double to string, but it's a bug that we'll fix later,
and one you should be aware of if you intend to use a <tt>JS_*printf()</tt>&nbsp;
function with your own floating type arguments - various vendor sprintf's
mishandle NaN, +/-Inf, and some even print normal floating values inaccurately.
<h4>
prmjtime.c, prmjtime.h</h4>
Time functions. These interfaces are named in a way that makes local vs.
universal time confusion likely. Caveat emptor, and we're working on it.
To make matters worse, Java (and therefore JavaScript) uses "local" time
numbers (offsets from the epoch) in its Date class.


<h2>
<a NAME="Resources"></a>Additional Resources (links, API docs, and newsgroups)</h2>
<ul>
<li><a href ="http://developer.mozilla.org/en/docs/JavaScript">http://developer.mozilla.org/en/docs/JavaScript</a>
<li><a href ="http://developer.mozilla.org/en/docs/SpiderMonkey">http://developer.mozilla.org/en/docs/SpiderMonkey</a>
<li><a href ="news://news.mozilla.org/mozilla.dev.tech.js-engine">news://news.mozilla.org/mozilla.dev.tech.js-engine</a>
</ul>



</body>
</html>