EC(1) User Commands EC(1)
NAME
ejsc - Ejscript compiler.
SYNOPSIS
ejsc [--bind] [--debug] [--doc] [--lang [ecma|plus|fixed]] [--empty]
[--noout] [--optimize level] [--out filename] [--parse] [--search ejs-
Path] [--standard] [--strict] [--use 'module, ...'] [--version]
[--warn level] files...
DESCRIPTION
The ejsc command compiles Ejscript programs to produce Ejscript module
files containing byte code. The module files may then be run via the
ejsvm virtual machine command or via the ejs shell command.
The ejsc command is both a compiler and link editor. Inputs can be
either Ejscript source files or Ejscript modules that have come from
previous invocations of the ejsc command. Outputs will be one or more
Ejscript module files that contain declarations and byte code.
An output module file will be created for each Ejscript module direc-
tive encountered during compilation. A module file will also be created
for any global variables or functions declared outside a module direc-
tive. These global declarations will go into the default module that is
specially reserved for global declarations. Each module file will be
named according to the module directive name, but with a .mod extension
appended.
LINKING
If ejsc is invoked with the --out switch, all input scripts, modules
and any other dependent modules are merged together into a single out-
put module. The modules retain their logical naming, but are emitted in
a single output module file. When that module file is loaded, all the
contained modules will be available to the program. This creates not
only a convenient way to package an entire application as a single
file, it also permits many optimizations by merging the entire applica-
tion and its dependent modules into a single module.
BINDING
The ejsc compiler will attempt to early-bind all possible variable and
function references. Binding means resolving references to the underly-
ing storage for properties and functions. Doing this at compile time
usually results in much faster execution at run-time.
When using the --out switch, 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 also have global declarations. Otherwise the Ejscript
loader will throw an exception. Consequently, the --out switch must
only be used to create a complete application including all the appli-
cation's required modules.
COMPLIANCE
Ejscript is fully compliant with the JavaScript (ECMA-262 3.X) stan-
dards, but it also offers a set of enhancements and fixes designed to
improve the language and correct some longstanding JavaScript design
issues. Use of these enhancements and fixes is optional and controlled
via opt-in configuration switches and script pragmas.
The ejsc compiler supports three language compliance modes:
* ecma for strict ECMAScript compliance.
* plus for close compliance plus compatible Ejscript enhancements.
* fixed for close compliance, plus compatible Ejscript enhance-
ments and breaking fixes.
When Ejscript is built, the default compliance mode is defined. By
default, this is plus mode. The fixed mode corrects several issues
with Javascript that remain in the language due to browser compatibil-
ity requirements. Ejscript, by targeting non-browser envirnonments, can
rectify these issues without impact to legacy applications. These
changes are:
* Assignments to non-existent properties inside functions, will
create local variables rather than global variables.
* Multiple declarations of the same variable in the same scope are
not permitted.
* The == and != operators will perform like their more rigorous
conterparts === and !===.
OPTIONS
--bind Bind global variable declarations into slot references. This
results in faster more compact code. However, only one module
can have its global variables bound.
--debug
Generate symbolic debug instructions. This permits symbolic
debugging of Ejscript programs and enables exception stack back-
traces to include line number information.
--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.
--empty
Start with an empty interpreter without the core language types
such as Object, Array and Number. This option is used to build
the foundation ejs.mod module which contains the core system
types.
--lang [ecma|plus|fixed]
Set the language compliance mode. Use ecma for strict ECMAScript
Edition 3 compliance. Use plus for close ECMAScript compliance
plus Ejscript enhancements. Select fixed mode for ECMAScript
features plus enhancements and some compatibility breaking
fixes.
--merge
Merge all input files and modules together into a single output
module. This option acts like a link-editor combining all inputs
together. Useful if you want to distribute your application as a
single module file.
--optimize level
Set the code optimization level. Level values must be between 0
(least) and 9 (most). Default is 9.
--parse
Just parse the source scripts. Don't verify, execute or generate
output. Useful to check the script syntax only.
--search ejsPath
Set the module search path. The module search path is a set of
directories that the ejsc command will use when locating and
loading Ejscript modules. The search path will always have some
system directories appended to the end. These include paths
specified via the EJSPATH environment variable and key system
directories such as the Ejscript system module directory and the
directory containing the ejsc command.
The search path value is similar in format to the system PATH
variable format. On windows, path segments are separated by ";"
and on Linux, Unix, FreeBSD and MAC, the path segments are sepa-
rated by ":" delimiters.
Given a module named "a.b.c" in a script, ejsc will use the fol-
lowing 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 the search path
4. Search for a module file named c.mod in the search path
--standard
Run scripts in standard mode. Ejscript supports two parsing
modes: strict and standard. Standard mode does not require vari-
ables 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 vari-
ables be declared and typed.
--use 'module, ...'
List of modules to preload before compiling input files.
--version
Print the ejsc 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.
BACKGROUND
Ejscript is an enhanced implementation of the JavaScript language for
use in embedded applications such as web servers, embedded and mobile
devices. It is especially suited for Server-Side JavaScript web appli-
cations.
Ejscript is a dynamic, interpreted, object-oriented scripting language
that supports classes, objects, exceptions, statements, expressions and
a powerful suite of data types.
REPORTING BUGS
Report bugs to dev@embedthis.com.
COPYRIGHT
Copyright (C) 2004-2012 Embedthis Software. Ejscript is a trademark of
Embedthis Software.
SEE ALSO
ejsgen, ejs, ejsmod, ejsvm
ejsc March 2012 EC(1)