Using the Compiler

Ejscript programs can be run on-demand by using the ejs command or they can be compiled once and the resulting byte code can be run without having to recompile the program. For production use, it is typically many times faster and more compact to pre-compile scripts.

The Ejscript compiler is called ejsc and it compiles Ejscript files to produce binary byte code files called Ejscript module files that can then be run by the ejs shell command.

Inputs and Outputs

The ejsc compiler is both a compiler and link editor in that inputs can be either Ejscript source files or Ejscript module files that have come from previous invocations of ejsc. Outputs will be one or more Ejscript module files that contain byte code.

An output module file will be created for each Ejscript module directive encountered in input scripts during the compilation. A module file will also be created for any global variables or functions declared outside any module directive. These global declarations will go into the "default" module that is specially reserved for global declarations. Each module file will be named the same as the module directive name, but with a ".mod" extension.

For example, if two script files contained the following code:

geometry.es:

module "acme.geometry" {
  class Shape {}
}

widgets.es

module "acme.widgets" { 
  class Widget {}
}

and these scripts were compiled as follows:

ejsc geometry.es widget.es

then two module files would be created: acme.geometry.mod and acme.widgets.mod.

Linking

If ejsc is invoked with the --out switch, all input files, input modules and any dependent modules are merged together into a single output file. The modules retain their logical naming, but are contained in a single module file. When that module file is loaded, all the contained modules will be available to the program. In the example above, if we typed:

ejsc --out acme.mod geometry.es widgets.es

then one module file would be produced called acme.mod.

Link Optimization

Using the --out switch not only creates a convenient way to package an entire application as a single file, it also permits many optimizations by merging the entire application and its dependent modules into a single bundle. The ejsc compiler will attempt to early-bind all possible property and function references. Binding means resolving the reference to the underlying storage for a property or function and doing this at compile time usually results in much faster execution. When using --out, the compiler can early bind all global variables, functions and type references resulting in a much smaller and faster application. However, you must not subsequently load other modules that have global declarations, otherwise the Ejscript loader will throw an exception. Thus, the --out switch must only be used to create a complete application including all the application's required modules.

Standards Compliance

The ejsc compiler supports two modes of compliance:

1. ECMAScript compliant compilation
2. Enhanced compliance mode

By default the ejsc command runs in enhanced compliance mode. This mode corrects several issues with JavaScript that remain in the language due to browser compatibility requirements. Ejscript, by targeting non-browser environments can rectify these issues without impact to legacy applications. These changes are:

• Assignments to non-existent properties create local variables rather than globals.
• The == and != operators will perform like their more rigorous counterparts === and !===.
• All var declarations are always block local in scope and are equivalent to the newer let declarations.
• The eval command is not supported.

Using the --ecma switch changes the default compliance mode to be ECMAScript.

Command Options

The ejsc command may be invoked with the following command options:

ejsc [--debug] [--dir directory] [--doc] [--merge] [--modver version] 
    [--noout] [--optimize level] [--out filename] [--parse] 
    [--require modules] [--searchPath ejsPath] [--standard] 
    [--strict] [--version] [--warn level] 
    files or modules ...

The ejs command will parse and execute the given file with the supplied arguments passed into the App.args property.

Switch	Description
--debug	Run in debug mode with symbolic stack backtraces in exceptions.
--doc	Include documentation strings from input scripts in the output modules. The ejsmod command can then generate HTML documentation using these doc strings. The format of the doc strings resembles that of Javadoc.
--merge	Merge dependent input modules into the output.
--modver version	Set the default module version.
--noout	Don't generate any output modules.
--parse	Just parse the source scripts. Don't verify, execute or generate output. Useful to check the script syntax only.
--optimize level	Set the code optimization level. Level values must be between 0 (least) and 9 (most). Default is 9.
--require modules	Required modules to pre-load before compiling.
--searchPath ejsPath	Override the module search path. The module search path is a set of directories that the ejs command will use when locating and loading Ejscript modules. Given a module named "a.b.c" in a script, ejs will use the following search strategy to locate the module: 1. Search for a module file named "a.b.c.mod" 2. Search for a module file named "a/b/c.mod" 3. Search for a module file named "a.b.c.mod" in EJSPATH 4. Search for a module file named c.mod in EJSPATH The search path is initially specified via the environment variable EJSPATH and may be overridden via the --searchPath ejsPath switch. EJSPATH and the ejsPath command line value are similar to the system PATH formats. On windows, path segments are separated by ";" and on Linux, Unix, FreeBSD and MAC, the path segments are separated by ":" delimiters.
--standard	Run scripts in standard mode. Ejscript supports two parsing modes: strict and standard. Standard mode does not require variables be declared and typed before use.
--strict	Run scripts in standard mode. Ejscript supports two parsing modes: strict and standard. Strict mode requires that all variables be declared and typed.
--version	Print the ejs command version and exit.
--warn level	Set the compiler warning verbosity level. Level values must be between 0 (least verbose) and 9 (most). Default is 0.