See Also
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 scipts.
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 ejsvm virtual machine 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:
- ECMAScript compliant compilation
- 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 envirnonments 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 conterparts === 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] [--doc] [--ecma] [--empty] [--noout] [--optimize level] [--out filename] [--parse] [--searchPath ejsPath] [--standard] [--strict] [--version] [--warn level] files...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. |
--ecma | Run in ECMAScript Edition 3 (ES3) compilance mode. The ejs command normally runs in non-compliant, enhanced mode. This enhanced mode eliminates browser specific portions of the ES3 standard to give a safer, faster language. For example: in ES3 compliant mode, function variables used without an accompanying var declaration are global variables, whereas in enhanced mode, they are local variables. |
--empty | Start with an empty interpreter without the core language types such as Object, Array, Number etc. This option is used to build the foundation Ejscript module ejs.mod which contains the system core types. |
--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. |
--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 initiallly 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. |