EC(1)                            User Commands                           EC(1)



NAME
       ec - Ejscript compiler.

SYNOPSIS
       ec  [--debug]  [--doc]  [--ecma] [--empty] [--noout] [--optimize level]
       [--out  filename]   [--parse]   [--searchPath   ejsPath]   [--standard]
       [--strict] [--version] [--warn level] files...

DESCRIPTION
       The  ec  command compiles Ejscript programs to produce binary byte code
       files called Ejscript module files.  These module files may then be run
       via the ejsvm virtual machine command or via the ejs shell command.

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

       An output module file will be created for each Ejscript  module  direc-
       tive 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  declara-
       tions.  Each module file will be named the same as the module directive
       name, but with a ".mod" extension.

LINKING
       If ec 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. This not only creates a  con-
       venient  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  ec  compiler  will attempt to early-bind all possible property and
       function references. Binding  means  resolving  the  reference  to  the
       underlying  storage for the property or function and doing this at com-
       pile 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 declara-
       tions, otherwise the Ejscript loader will throw an exception. Thus, the
       --out switch must only be used to create a complete application includ-
       ing all the application's required modules.

COMPLIANCE
       The ec compiler supports two modes of compliance: ECMAScript Edition  4
       compliant  compilation and an enhanced compliance mode.  By default the
       ec command runs in enhanced compliance mode. This mode corrects several
       issues  with Javascript that remain in the language due to browser com-
       patibility requirements. Ejscript, by targeting  non-browser  envirnon-
       ments  can  rectify these issues without impact to legacy applications.
       These changes are:

           * Assignments to non-existant  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 Edition 4.

BACKGROUND
       Ejscript is an interpreted, object oriented scripting language  and  is
       an  enhanced  implementation  of  the  emerging  ECMAScript  Edition  4
       (Javascript)  language.  Ejscript  supports  statements,   expressions,
       objects,  classes,  exceptions,  namespaces, iterators, type annotation
       and a powerful suite of data types.

       While Javascript is the language of  the  browser,  Ejscript  has  been
       designed  to  run Javascript outside a browser. The goal of Ejscript is
       to create a language ideally suited  for  embedded  applications  where
       efficiency of execution is a paramount concern.

OPTIONS
       --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.

       --ecma Run in ECMAScript Edition 4 (ES4) compilance mode. The  ec  com-
              mand  normally  runs  in  non-compliant,  enhanced  mode.   This
              enhanced mode eliminates browser specific portions  of  the  ES4
              standard  to give a safer, faster language.  For example: in ES4
              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 ec command will use  when  locating  and
              loading  Ejscript  modules.  Given  a  module named "a.b.c" in a
              script, ec 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 ejs-
              Path switch. EJSPATH and the ejsPath command line value are sim-
              ilar 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 vari-
              ables be declared and typed before use.

       --stats
              Print various statistics on exit.

       --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.

       --warn level
              Set the compiler warning verbosity level. Level values  must  be
              between 0 (least verbose) and 9 (most). Default is 0.

       --version
              Print the ec command version and exit.


REPORTING BUGS
       Report bugs to <dev@embedthis.com>.

COPYRIGHT
       Copyright (C) 2004-2009 Embedthis Software.  Ejscript is a trademark of
       Embedthis Software.

SEE ALSO
       ejs, ejsmod, ejsvm



ec                                 May 2009                              EC(1)
