view release on metacpan or  search on metacpan

JS/js/README  view on Meta::CPAN

design walk-through, and a brief file-by-file description of the source.

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.

The current version of JSRef lacks a conformance testsuite.  We aim to provide
one as soon as possible.

Quick start tip: skip to "Using the JS API" below, build js, and play with the
object named "it" (start by setting 'it.noisy = true').

Brendan Eich, 9/17/96

------------------------------------------------------------------------------

Build conventions:

- On Windows, use MSDEV4.2 (js*.mdp) or 5.0 (js*.mak).

- On Mac, use CodeWarrior 1.x (JSRef.prj.hqx) or 2 (JSRef.prj2.hqx).

- On Unix, use vendor cc or gcc (ftp://prep.ai.mit.edu/pub/gnu) for compiling,
  and use gmake for building.

  To compile optimized code, pass BUILD_OPT=1 on the nmake/gmake command line
  or preset it in the environment or makefile.  The C preprocessor macro DEBUG
  will be undefined, and NDEBUG (archaic Unix-ism for "No Debugging") will be
  defined.  Without BUILD_OPT, DEBUG is predefined and NDEBUG is undefined.

  On Unix, your own debug flag, DEBUG_$USER, will be defined or undefined as
  BUILD_OPT is unset or set.

  (Linux autoconf support way overdue; coming some day soon, I promise.)

- To add C compiler options from the make command line, set XCFLAGS=-Dfoo.
  To predefine -D or -U options in the makefile, set DEFINES.
  To predefine -I options in the makefile, set INCLUDES.

- To turn on GC instrumentation, define JS_GCMETER.
- To enable multi-threaded execution, define JS_THREADSAFE and flesh out the
  stubs and required headers in jslock.c/.h.  See the JS API docs for more.
- To turn on the arena package's instrumentation, define PR_ARENAMETER.
- To turn on the hash table package's metering, define PR_HASHMETER.

Naming and coding conventions:

- Public function names begin with JS_ followed by capitalized "intercaps",
  e.g. JS_NewObject.
- Extern but library-private function names use a js_ prefix and mixed case,
  e.g. js_LookupSymbol.
- Most static function names have unprefixed, mixed-case names: GetChar.
- But static native methods of JS objects have lowercase, underscore-separated
  or intercaps names, e.g., str_indexOf.
- And library-private and static data use underscores, not intercaps (but
  library-private data do use a js_ prefix).
- Scalar type names are lowercase and js-prefixed: jsdouble.
- Aggregate type names are JS-prefixed and mixed-case: JSObject.
- Macros are generally ALL_CAPS and underscored, to call out potential
  side effects, multiple uses of a formal argument, etc.

- Four spaces of indentation per statement nesting level.
- 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, or convert these files to be space-filled.
- DLL entry points have their return type expanded within a PR_PUBLIC_API()
  macro call, to get the right Windows secret type qualifiers in the right
  places for both 16- and 32-bit builds.
- Callback functions that might be called from a DLL are similarly macroized
  with PR_STATIC_CALLBACK (if the function otherwise would be static to hide
  its name) or PR_CALLBACK (this macro takes no type argument; it should be
  used after the return type and before the function name).

Using the JS API:

- Starting up:

    /*
     * Tune this to avoid wasting space for shallow stacks, while saving on
     * malloc overhead/fragmentation for deep or highly-variable stacks.
     */
    #define STACK_CHUNK_SIZE	8192

    JSRuntime *rt;
    JSContext *cx;

    /* You need a runtime and one or more contexts to do anything with JS. */
    rt = JS_Init(1000000L);
    if (!rt)
	fail("can't create JavaScript runtime");
    cx = JS_NewContext(rt, STACK_CHUNK_SIZE);
    if (!cx)
	fail("can't create JavaScript context");

    /*
     * The context definitely wants a global object, in order to have standard
     * classes and functions like Date and parseInt.  See below for details on
     * JS_NewObject.
     */
    JSObject *globalObj;

    globalObj = JS_NewObject(cx, &my_global_class, 0, 0);
    JS_InitStandardClasses(cx, globalObj);

- Defining objects and properties:

    /* Statically initialize a class to make "one-off" objects. */
    JSClass my_class = {
	"MyClass",

	/* All of these can be replaced with the corresponding JS_*Stub
	   function pointers. */
	my_addProperty, my_delProperty, my_getProperty, my_setProperty,
	my_enumerate,   my_resolve,     my_convert,     my_finalize
    };

    JSObject *obj;

    /*