Posting the latest version of the doc itself so people can read it. On Thu, Jan 22, 2009 at 9:04 AM, <[email protected]> wrote: > http://codereview.appspot.com/11948
-- Ihab A.B. Awad, Palo Alto, CATitle: Compiled module format
Summary
We describe an updated format for Caja modules, which allows for, among other things, debugging information. We outline some debugging information that will be included.
Background
Currently, the output of the Caja translator is a Cajita module. This module is a _javascript_ statement of the following form:
___.loadModule(function(___, IMPORTS___) {
... cajoled code here ...
});
The call to ___.loadModule() is
merely to handle the case where a containing page loads a module by
including a
<script src=""> tag pointing
to the module's text. In that case, the module function must be made
available to the surrounding page via some side effects; we chose
those to be the loadModule() method
of the global ___ object representing
the Caja µkernel. Otherwise, the Cajita module itself
is just the anonymous function:
function(___, IMPORTS___) {
... cajoled code here ...
};
Cajita modules as described above do not have a mechanism for providing to their container some important metadata for debugging, checksumming, signing, authorship, details of cajoling process and time, description of API requirements, and slots for framework programmers to use in describing modules.
Module format
Our new module format is an object literal, so the Caja translator output looks like:
___.loadModule({
execute: function(___, IMPORTS___) { ... },
cajolerVersion: ...,
cajoledDate: ...,
originalSource: { ... },
debugInfo: { ... },
imports: { ... },
manifest: { ...}
});
The following are the standard keys:
execute |
required | The anonymous function representing the module, as before. |
cajolerVersion |
required | Slot reserved for a string literal uniquely identifying the
version of the Caja translator which emitted this module. This will
be used in the future by cajita.js to check whether a
cajoled module is compatible with the runtime. At the moment, we
will populate this with the string representation of the SVN revision
number of the code that cajoled this module. |
cajoledDate |
required | The date at which the module was cajoled, expressed as an integer number of milliseconds since Epoch. |
imports |
required | Information about the variables imported by this module. This is a record
where each key is the name of an imported variable, and each corresponding value
is some JSON data providing meta-information about the module's expectations regarding
that variable.
TODO: Define the imported variable metadata
format (essentially equivalent to
@param Javadocs)
and how Caja programmers can set it. |
originalSource |
optional | The original source from which this module was compiled. This is a record where each key is a file name (expressed at the discretion of the cajoler) and the corresponding value is a string literal containing the text of the file. The text is escaped such that it will be bit-identical to the original source when parsed as a JS string literal; thus it is understood that the actual text embedded in the module file itself will not be bit-identical to the original. |
debugInfo |
optional | A record containing debug information, described below. If a module was compiled without debugging support, this property is absent. |
manifest |
optional | A JSON record containing the module manifest. A program
provides this to the cajoler by calling
the cajita.manifest() function. |
___.readImport and thus clutters up the Cajoled code a bit.Debugging information
The purpose of the debugging information is to provide hooks for
transparent source-level debugging of cajoled code. This requires
providing the original source code; line number mappings from the
original source to the cajoled output; information about which
variables are actually in-scope end-user code (as opposed to
temporaries generated by the cajoler); and enough information for the
debugger to skip over Caja boilerplate (e.g. to enter a function
directly rather than step through the
Cajita ___.callPub() or Valija
$v.callFunc() guff).
