| blob | 3840cafa2318003294909f8370623958bd11c4b1 |
1 <!-- ***** BEGIN LICENSE BLOCK *****
2 - Version: MPL 1.1/GPL 2.0/LGPL 2.1
3 -
4 - The contents of this file are subject to the Mozilla Public License Version
5 - 1.1 (the "License"); you may not use this file except in compliance with
6 - the License. You may obtain a copy of the License at
7 - http://www.mozilla.org/MPL/
8 -
9 - Software distributed under the License is distributed on an "AS IS" basis,
10 - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11 - for the specific language governing rights and limitations under the
12 - License.
13 -
14 - The Original Code is Mozilla Communicator client code, released
15 - March 31, 1998.
16 -
17 - The Initial Developer of the Original Code is
18 - Netscape Communications Corporation.
19 - Portions created by the Initial Developer are Copyright (C) 1998-1999
20 - the Initial Developer. All Rights Reserved.
21 -
22 - Contributor(s):
23 -
24 - Alternatively, the contents of this file may be used under the terms of
25 - either of the GNU General Public License Version 2 or later (the "GPL"),
26 - or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 - in which case the provisions of the GPL or the LGPL are applicable instead
28 - of those above. If you wish to allow use of your version of this file only
29 - under the terms of either the GPL or the LGPL, and not to allow others to
30 - use your version of this file under the terms of the MPL, indicate your
31 - decision by deleting the provisions above and replace them with the notice
32 - and other provisions required by the GPL or the LGPL. If you do not delete
33 - the provisions above, a recipient may use your version of this file under
34 - the terms of any one of the MPL, the GPL or the LGPL.
35 -
36 - ***** END LICENSE BLOCK ***** -->
38 <html>
39 <head>
43 </head>
44 <body>
46 <h2>
47 Table of Contents</h2>
49 <ul>
50 <li>
53 <li>
56 <li>
59 <li>
62 <li>
65 <li>
68 <li>
71 </ul>
73 <h2>
76 Reference (JSRef, now better known as SpiderMonkey) implementation.</span>
77 It consists of build conventions
78 and instructions, source code conventions, a design walk-through, and a
79 brief file-by-file description of the source.
81 JavaScript runtime (compiler, interpreter, decompiler, garbage collector,
82 atom manager, standard classes). It then compiles a small "shell" program
83 and links that with the library to make an interpreter that can be used
84 interactively and with test .js files to run scripts. The code has
85 no dependencies on the rest of the Mozilla codebase.</span>
87 js shell, and play with the object named "it" (start by setting 'it.noisy
88 = true').
89 <h2>
91 (OUT OF DATE!)</h2>
92 These build directions refer only to building the standalone JavaScript
95 directions</a> on the mozilla.org website.
97 threadsafe. If you require thread-safety, you must also populate
98 the <tt>mozilla/dist</tt> directory with <a href="http://www.mozilla.org/projects/nspr/reference/html/"
100 headers and libraries. (NSPR implements a portable threading library,
101 among other things. The source is downloadable via <a href="http://www.mozilla.org/cvs.html">CVS</a>
102 from <tt><a href="http://lxr.mozilla.org/mozilla/source/nsprpub">mozilla/nsprpub</a></tt>.)
104 either on the command-line (gmake/nmake) or in a universal header file.
105 <h3>
106 Windows</h3>
108 <ul>
109 <li>
112 <li>
114 is an MSVC4.2 project file, but if you load it into MSVC5, it will be converted
116 is an nmake file used only for building the JS-engine in the Mozilla browser.
117 Don't attempt to use it to build the standalone JS-engine.</font></li>
119 <li>
122 <li>
125 </ul>
127 <h3>
128 Macintosh</h3>
130 <ul>
131 <li>
134 <li>
136 from the menu.</li>
137 </ul>
139 <h3>
140 Unix</h3>
142 <ul>
143 <li>
147 Do not attempt to use Makefile to build the standalone JavaScript engine.
148 This file is used only for building the JS-engine in the Mozilla browser.</font></li>
150 <li>
153 file specifies the compiler/linker to be used and allows for customization
154 of command-line options. To date, the build system has been tested
155 on Solaris, AIX, HP/UX, OSF, IRIX, x86 Linux and Windows NT.</font></li>
157 <li>
159 </font>or
161 (Except that HP builds only work using the native compiler. gcc won't
162 link correctly with shared libraries on that platform. If someone
166 <li>
168 descend into the liveconnect directory and build
170 after building the JS engine.</font></li>
172 <li>
173 To build a binary drop (a zip'ed up file of headers, libraries, binaries),
176 </ul>
178 <h2>
181 <ul>
182 <li>
185 <ul>
186 <li>
187 To dump JS heap use JS_DumpHeap API, available in DEBUG builds. For an example
188 how to call it see DumpHeap implementation in js.c.</li>
190 <li>
193 <li>
195 </ul>
197 <h2>
200 <ul>
201 <li>
205 <li>
209 <li>
212 <li>
213 But static native methods of JS objects have lowercase, underscore-separated
216 <li>
217 And library-private and static data use underscores, not intercaps (but
220 <li>
223 <li>
226 <li>
228 side effects, multiple uses of a formal argument, etc.</li>
230 <li>
231 Four spaces of indentation per statement nesting level.</li>
233 <li>
234 Tabs are taken to be eight spaces, and an Emacs magic comment at the top
235 of each file tries to help. If you're using MSVC or similar, you'll want
236 to set tab width to 8, and help convert these files to be space-filled.
238 whenever possible.</font></li>
240 <li>
242 macro call, to get the right Windows secret type qualifiers in the right
243 places for all build variants.</li>
245 <li>
246 Callback functions that might be called from a DLL are similarly macroized
249 no type argument; it should be used after the return type and before the
250 function name).</li>
251 </ul>
253 <h2>
256 <h4>
257 Starting up</h4>
260 * Tune this to avoid wasting space for shallow stacks, while saving on
261 * malloc overhead/fragmentation for deep or highly-variable stacks.
262 */
265 JSRuntime *rt;
266 JSContext *cx;
268 /* You need a runtime and one or more contexts to do anything with JS. */
270 if (!rt)
272 cx = JS_NewContext(rt, STACK_CHUNK_SIZE);
273 if (!cx)
276 /*
277 * The context definitely wants a global object, in order to have standard
278 * classes and functions like Date and parseInt. See below for details on
279 * JS_NewObject.
280 */
281 JSObject *globalObj;
286 <h4>
287 Defining objects and properties</h4>
290 JSClass my_class = {
293 /* All of these can be replaced with the corresponding JS_*Stub
294 function pointers. */
295 my_addProperty, my_delProperty, my_getProperty, my_setProperty,
296 my_enumerate, my_resolve, my_convert, my_finalize
297 };
299 JSObject *obj;
301 /*
302 * Define an object named in the global scope that can be enumerated by
303 * for/in loops. The parent object is passed as the second argument, as
304 * with all other API calls that take an object/name pair. The prototype
305 * passed in is null, so the default object prototype will be used.
306 */
308 JSPROP_ENUMERATE);
310 /*
311 * Define a bunch of properties with a JSPropertySpec array statically
312 * initialized and terminated with a null-name entry. Besides its name,
313 * each property has a "tiny" identifier (MY_COLOR, e.g.) that can be used
314 * in switch statements (in a common my_getProperty function, for example).
315 */
316 enum my_tinyid {
317 MY_COLOR, MY_HEIGHT, MY_WIDTH, MY_FUNNY, MY_ARRAY, MY_RDONLY
318 };
320 static JSPropertySpec my_props[] = {
321 {"color", MY_COLOR, JSPROP_ENUMERATE},
322 {"height", MY_HEIGHT, JSPROP_ENUMERATE},
323 {"width", MY_WIDTH, JSPROP_ENUMERATE},
324 {"funny", MY_FUNNY, JSPROP_ENUMERATE},
325 {"array", MY_ARRAY, JSPROP_ENUMERATE},
326 {"rdonly", MY_RDONLY, JSPROP_READONLY},
328 };
330 JS_DefineProperties(cx, obj, my_props);
332 /*
333 * Given the above definitions and call to JS_DefineProperties, obj will
334 * need this sort of "getter" method in its class (my_class, above). See
336 */
337 static JSBool
338 my_getProperty(JSContext *cx, JSObject *obj, jsval id, jsval *vp)
339 {
340 if (JSVAL_IS_INT(id)) {
341 switch (JSVAL_TO_INT(id)) {
342 case MY_COLOR: *vp = . . .; break;
343 case MY_HEIGHT: *vp = . . .; break;
344 case MY_WIDTH: *vp = . . .; break;
345 case MY_FUNNY: *vp = . . .; break;
346 case MY_ARRAY: *vp = . . .; break;
347 case MY_RDONLY: *vp = . . .; break;
348 }
349 }
350 return JS_TRUE;
353 <h4>
354 Defining functions</h4>
357 static JSBool
358 my_abs(JSContext *cx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
359 {
360 jsdouble x, z;
363 return JS_FALSE;
365 return JS_NewDoubleValue(cx, z, rval);
366 }
368 . . .
370 /*
371 * Use a JSFunctionSpec array terminated with a null name to define a
372 * bunch of native functions.
373 */
374 static JSFunctionSpec my_functions[] = {
375 /* name native nargs */
376 {"abs", my_abs, 1},
377 {"acos", my_acos, 1},
378 {"asin", my_asin, 1},
379 . . .
381 };
383 /*
384 * Pass a particular object to define methods for it alone. If you pass
385 * a prototype object, the methods will apply to all instances past and
386 * future of the prototype's class (see below for classes).
387 */
390 <h4>
391 Defining classes</h4>
394 * This pulls together the above API elements by defining a constructor
395 * function, a prototype object, and properties of the prototype and of
396 * the constructor, all with one API call.
397 *
398 * Initialize a class by defining its constructor function, prototype, and
399 * per-instance and per-class properties. The latter are called "static"
400 * below by analogy to Java. They are defined in the constructor object's
401 * scope, so that 'MyClass.myStaticProp' works along with 'new MyClass()'.
402 *
403 * JS_InitClass takes a lot of arguments, but you can pass null for any of
404 * the last four if there are no such properties or methods.
405 *
406 * Note that you do not need to call JS_InitClass to make a new instance of
407 * that class -- otherwise there would be a chicken-and-egg problem making
408 * the global object -- but you should call JS_InitClass if you require a
409 * constructor function for script authors to call via new, and/or a class
410 * prototype object ('MyClass.prototype') for authors to extend with new
411 * properties at run-time. In general, if you want to support multiple
412 * instances that share behavior, use JS_InitClass.
413 */
416 /* native constructor function and min arg count */
417 MyClass, 0,
419 /* prototype object properties and methods -- these
420 will be "inherited" by all instances through
421 delegation up the instance's prototype link. */
422 my_props, my_methods,
424 /* class constructor properties and methods */
425 my_static_props, my_static_methods);</tt></pre>
427 <h4>
428 Running scripts</h4>
431 char *filename;
432 uintN lineno;
434 /*
435 * The return value comes back here -- if it could be a GC thing, you must
436 * add it to the GC's "root set" with JS_AddRoot(cx, &thing) where thing
437 * is a JSString *, JSObject *, or jsdouble *, and remove the root before
438 * rval goes out of scope, or when rval is no longer needed.
439 */
440 jsval rval;
441 JSBool ok;
443 /*
444 * Some example source in a C string. Larger, non-null-terminated buffers
445 * can be used, if you pass the buffer length to JS_EvaluateScript.
446 */
449 ok = JS_EvaluateScript(cx, globalObj, source, strlen(source),
450 filename, lineno, &rval);
452 if (ok) {
453 /* Should get a number back from the example source. */
454 jsdouble d;
457 . . .
460 <h4>
461 Calling functions</h4>
473 <h4>
474 Shutting down</h4>
477 JS_DestroyContext(cx);
479 /* For each runtime: */
480 JS_DestroyRuntime(rt);
482 /* And finally: */
485 <h4>
486 Debugging API</h4>
489 <h2>
491 This section must be brief for now -- it could easily turn into a book.
492 <h4>
494 JS modules declare and implement the JavaScript compiler, interpreter,
495 decompiler, GC and atom manager, and standard classes.
496 <p>JavaScript uses untyped bytecode and runtime type tagging of data values.
498 signed integer value (if the low bit is set), or a type-tagged pointer
499 or boolean value (if the low bit is clear). Tagged pointers all refer to
500 8-byte-aligned things in the GC heap.
501 <p>Objects consist of a possibly shared structural description, called
502 the map or scope; and unshared property values in a vector, called the
503 slots. Object properties are associated with nonnegative integers stored
505 by an identifier or a non-integral index expression.
506 <p>Scripts contain bytecode, source annotations, and a pool of string,
507 number, and identifier literals. Functions are objects that extend scripts
508 or native functions with formal parameters, a literal syntax, and a distinct
509 primitive type ("function").
510 <p>The compiler consists of a recursive-descent parser and a random-logic
511 rather than table-driven lexical scanner. Semantic and lexical feedback
512 are used to disambiguate hard cases such as missing semicolons, assignable
513 expressions ("lvalues" in C parlance), etc. The parser generates bytecode
514 as it parses, using fixup lists for downward branches and code buffering
515 and rewriting for exceptional cases such as for loops. It attempts no error
516 recovery. The interpreter executes the bytecode of top-level scripts, and
517 calls itself indirectly to interpret function bodies (which are also scripts).
518 All state associated with an interpreter instance is passed through formal
519 parameters to the interpreter entry point; most implicit state is collected
520 in a type named JSContext. Therefore, all API and almost all other functions
521 in JSRef take a JSContext pointer as their first argument.
522 <p>The decompiler translates postfix bytecode into infix source by consulting
523 a separate byte-sized code, called source notes, to disambiguate bytecodes
524 that result from more than one grammatical production.
525 <p>The GC is a mark-and-sweep, non-conservative (exact) collector. It
526 can allocate only fixed-sized things -- the current size is two machine
527 words. It is used to hold JS object and string descriptors (but not property
528 lists or string bytes), and double-precision floating point numbers. It
530 bytes of GC things have been allocated and another thing-allocation request
532 between script executions or from the branch callback, as often as necessary.
534 new objects created by your native methods if you store references to them
535 into a non-JS structure in the malloc heap or in static data. Also, if
536 you make a new object in a native method, but do not store it through the
538 result parameter (see math_abs in the "Using the JS API" section above)
539 so that it is in a known root, the object is guaranteed to survive only
540 until another new object is created. Either lock the first new object when
541 making two in a row, or store it in a root you've added, or store it via
542 rval.
544 document for more.
545 <p>The atom manager consists of a hash table associating strings uniquely
546 with scanner/parser information such as keyword type, index in script or
547 function literal pool, etc. Atoms play three roles in JSRef: as literals
548 referred to by unaligned 16-bit immediate bytecode operands, as unique
549 string descriptors for efficient property name hashing, and as members
550 of the root GC set for exact GC.
551 <p>Native objects and methods for arrays, booleans, dates, functions, numbers,
552 and strings are implemented using the JS API and certain internal interfaces
553 used as "fast paths".
554 <p>In general, errors are signaled by false or unoverloaded-null return
556 variants by the lowest level in order to provide the most detail. Client
557 code can substitute its own error reporting function and suppress errors,
558 or reflect them into Java or some other runtime system as exceptions, GUI
559 dialogs, etc..
560 <h2>
561 File walk-through (OUT OF DATE!)</h2>
563 <h4>
564 jsapi.c, jsapi.h</h4>
565 The public API to be used by almost all client code. If your client
568 to include what you need in a fashion that we can support over the long
569 run.
570 <h4>
571 jspubtd.h, jsprvtd.h</h4>
572 These files exist to group struct and scalar typedefs so they can be used
573 everywhere without dragging in struct definitions from N different files.
577 various .h files that need type names, but not type sizes or declarations.
578 <h4>
579 jsdbgapi.c, jsdbgapi.h</h4>
580 The Debugging API, still very much under development. Provided so far:
581 <ul>
582 <li>
583 Traps, with which breakpoints, single-stepping, step over, step out, and
584 so on can be implemented. The debugger will have to consult jsopcode.def
585 on its own to figure out where to plant trap instructions to implement
586 functions like step out, but a future jsdbgapi.h will provide convenience
587 interfaces to do these things. At most one trap per bytecode can be set.
589 are cleared.</li>
591 <li>
592 Watchpoints, for intercepting set operations on properties and running
593 a debugger-supplied function that receives the old value and a pointer
594 to the new one, which it can use to modify the new value being set.</li>
596 <li>
597 Line number to PC and back mapping functions. The line-to-PC direction
598 "rounds" toward the next bytecode generated from a line greater than or
599 equal to the input line, and may return the PC of a for-loop update part,
600 if given the line number of the loop body's closing brace. Any line after
601 the last one in a script or function maps to a PC one byte beyond the last
602 bytecode in the script. An example, from perfect.js:</li>
607 17
608 18 // We build sumOfDivisors[i] to hold a string expression for
612 22 for (var j = divisor + divisor; j <= n; j += divisor) {
613 23 sumOfDivisors[j] += " + " + divisor;
615 25 // At this point everything up to 'divisor' has its sumOfDivisors
616 26 // expression calculated, so we can determine whether it's perfect
618 28 if (eval(sumOfDivisors[divisor]) == divisor) {
619 29 print("" + divisor + " = " + sumOfDivisors[divisor]);
625 The line number to PC and back mappings can be tested using the js program
626 with the following script:
628 print(perfect)
629 dis(perfect)
631 print()
633 var pc = line2pc(perfect,ln)
634 var ln2 = pc2line(perfect,pc)
635 print("\tline " + ln + " => pc " + pc + " => line " + ln2)
679 </ul>
681 <h4>
682 jsconfig.h</h4>
685 all macros are tested around related code yet. In particular, JS 1.0 support
686 is missing from JSRef. JS 1.2 support will appear in a future JSRef release.
688 <h4>
689 js.c</h4>
690 The "JS shell", a simple interpreter program that uses the JS API and more
691 than a few internal interfaces (some of these internal interfaces could
693 source provides a test vehicle for evaluating scripts and calling functions,
694 trying out new debugger primitives, etc.
695 <h4>
696 jsarray.*, jsbool.*, jdsdate.*, jsfun.*, jsmath.*, jsnum.*, jsstr.*</h4>
697 These file pairs implement the standard classes and (where they exist)
698 their underlying primitive types. They have similar structure, generally
699 starting with class definitions and continuing with internal constructors,
700 finalizers, and helper functions.
701 <h4>
702 jsobj.*, jsscope.*</h4>
703 These two pairs declare and implement the JS object system. All of the
704 following happen here:
705 <ul>
706 <li>
707 creating objects by class and prototype, and finalizing objects;</li>
709 <li>
710 defining, looking up, getting, setting, and deleting properties;</li>
712 <li>
713 creating and destroying properties and binding names to them.</li>
714 </ul>
715 The details of a native object's map (scope) are mostly hidden in
717 <h4>
718 jsatom.c, jsatom.h</h4>
719 The atom manager. Contains well-known string constants, their atoms, the
720 global atom hash table and related state, the js_Atomize() function that
722 methods.
723 <h4>
724 jsgc.c, jsgc.h</h4>
725 [TBD]
726 <h4>
727 jsinterp.*, jscntxt.*</h4>
728 The bytecode interpreter, and related functions such as Call and AllocStack,
731 part of JS is split from the interpreter part into a separate program.
732 <h4>
733 jsemit.*, jsopcode.tbl, jsopcode.*, jsparse.*, jsscan.*, jsscript.*</h4>
735 source that defines almost everything there is to know about JS bytecodes.
736 See its major comment for how to use it. For now, a debugger will use it
739 conveniences. The code generator is split across paragraphs of code in
745 <h4>
746 jstypes.h, jslog2.c</h4>
747 Fundamental representation types and utility macros. This file alone among
748 all .h files in JSRef must be included first by .c files. It is not nested
749 in .h files, as other prerequisite .h files generally are, since it is
750 also a direct dependency of most .c files and would be over-included if
751 nested in addition to being directly included. The one "not-quite-a-macro
753 <h4>
754 jsarena.c, jsarena.h</h4>
755 Last-In-First-Out allocation macros that amortize malloc costs and allow
756 for en-masse freeing. See the paper mentioned in prarena.h's major comment.
757 <h4>
758 jsutil.c, jsutil.h</h4>
760 device to make invariants and preconditions clear to the reader, and to
761 hold the line during maintenance and evolution against regressions or violations
762 of assumptions that it would be too expensive to test unconditionally at
763 run-time. Certain assertions are followed by run-time tests that cope with
764 assertion failure, but only where I'm too smart or paranoid to believe
765 the assertion will never fail...
766 <h4>
767 jsclist.h</h4>
768 Doubly-linked circular list struct and macros.
769 <h4>
770 jscpucfg.c</h4>
772 bytes per word and other constants that depend on CPU architecture and
773 C compiler type model. It tries to discover most of these constants by
774 running its own experiments on the build host, so if you are cross-compiling,
775 beware.
776 <h4>
777 prdtoa.c, prdtoa.h</h4>
778 David Gay's portable double-precision floating point to string conversion
779 code, with Permission To Use notice included.
780 <h4>
781 prhash.c, prhash.h</h4>
782 Portable, extensible hash tables. These use multiplicative hash for strength
783 reduction over division hash, yet with very good key distribution over
784 power of two table sizes. Collisions resolve via chaining, so each entry
785 burns a malloc and can fragment the heap.
786 <h4>
787 prlong.c, prlong.h</h4>
788 64-bit integer emulation, and compatible macros that use C's long long
789 type where it exists (my last company mapped long long to a 128-bit type,
790 but no real architecture does 128-bit ints yet).
791 <h4>
792 jsosdep.h</h4>
793 Annoying OS dependencies rationalized into a few "feature-test" macros
795 <h4>
796 jsprf.*</h4>
797 Portable, buffer-overrun-resistant sprintf and friends. For no good reason
798 save lack of time, the %e, %f, and %g formats cause your system's native
801 to convert from double to string, but it's a bug that we'll fix later,
803 function with your own floating type arguments - various vendor sprintf's
804 mishandle NaN, +/-Inf, and some even print normal floating values inaccurately.
805 <h4>
806 prmjtime.c, prmjtime.h</h4>
807 Time functions. These interfaces are named in a way that makes local vs.
808 universal time confusion likely. Caveat emptor, and we're working on it.
809 To make matters worse, Java (and therefore JavaScript) uses "local" time
810 numbers (offsets from the epoch) in its Date class.
813 <h2>
815 <ul>
817 <li><a href ="http://www.mozilla.org/js/spidermonkey/">http://www.mozilla.org/js/spidermonkey/</a>
818 <li><a href ="news://news.mozilla.org/netscape.public.mozilla.jseng">news://news.mozilla.org/netscape.public.mozilla.jseng</a>
819 </ul>
823 </body>
824 </html>