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)