ESP(1)                           User Commands                          ESP(1)

NAME
       esp - ESP Application Generator for Server-Side Web Applications.

SYNOPSIS
       esp
           --cipher cipher
           --combine
           --database DB
           --force
           --home dir
           --keep
           --listen [ip:]port
           --log logFile:level
           --name appName
           --noupdate
           --optimized
           --quiet
           --platform [path/]os-arch-profile
           --rebuild
           --route pattern
           --single
           --show
           --static
           --symbols
           --table name
           --trace traceFile:level
           --verbose
           --why
           commands ...

       Commands:
           esp clean
           esp compile [pathFilters...]
           esp config
           esp edit key[=value]
           esp generate controller name [action [, action] ...]
           esp generate migration description model [field:type ...]
           esp generate scaffold model [field:type ...]
           esp generate table name model [field:type ...]
           esp init [name [version]]
           esp migrate [forward|backward|NNN]
           esp mode [debug|release|otherMode]
           esp role [add|remove] rolename
           esp serve [ip]:[port]
           esp user [add|compute] username password roles...
           esp user [remove|show] username

DESCRIPTION
       The  esp  command  generates, manages and runs ESP web applications. It
       includes a full HTTP/1.1 web server to host your  application  and  can
       generate ESP skeletons, controllers, database tables, and scaffolds.

       The  esp command will create directories and generate configuration and
       source code files that can then be manually edited as required.  ESP is
       intelligent  and  will  not overwrite existing files, so you can safely
       edit and regenerate without losing your changes. You can overwrite your
       changes if you wish to by using the --force switch.

RUNNING ESP
       To run ESP to serve documents from the current directory, type:
             esp
             # or
             esp serve

GENERATING APPLICATIONS
       To start a new web application, create a directory named for the appli-
       cation. Then from that directory run pak to install the  required  sup-
       porting packs. For example:

             mkdir blog
             cd blog
             pak install esp-html-skeleton

       This  will  will  create  a  set of directories that have the following
       meaning:

             documents           - Public client web content
             documents/assets    - Images and assets
             documents/css       - Client CSS and Less style sheets
             documents/index.esp - Home web page
             paks                - Extension packs
             db                  - Databases and scripts
             generate            - Template files used when generating

       Other directories will be created as needed:
             cache            - Cache directory for compiled content
             migrations       - Databases migration modules
             controllers      - Server side controllers
             src              - Server side main source code

       Most of these directories are initially empty, but  may  be  used  over
       time.  ESP  follows  conventions  where specific files are stored. This
       greatly simplifies configuring a web application.

       Packs are modules of functionality for ESP applications that are  pack-
       aged  using the Pak utility (see https://embedthis.com/pak).  Packs may
       depend on other packs so that installing a top level pack  may  install
       other  required  packs. For example: generating the "esp-html-skeleton"
       pack will also install: esp-mvc, exp-less, and other paks.

       See https://embedthis.com/catalog/ for a list of packs.

GENERATING MIGRATIONS
       Migrations are generated code modules that manage portions of the data-
       base.  Migrations  are used to create tables, initialize with test data
       and optionally destroy tables. Migrations are typically  generated  and
       then  hand-edited  to  include  relevant  initialization  or test data.
       Migrations are  useful  to  quickly  recreate  the  database  with  the
       required tables and data.

             esp generate migration DESCRIPTION TABLE [field:type ...]

       The  DESCRIPTION  is used to name the migration which is created in the
       migrations directory. A migration is given a  unique  ordered  sequence
       number  and the description is appended to this number. The description
       is mapped where spaces are changed to "_" characters.  When  migrations
       are run, they are run in sequence number order.

       If  field:type values are supplied, the database migration will include
       code to create a column for each specified field of the requested type.
       The  valid  database  types  are:  blob, boolean, date, float, integer,
       string, and text.

GENERATING TABLES
       To generate a database table without creating a migration:

             esp generate table TABLE [field:type ...]

GENERATING CONTROLLERS
       Controllers  are  the  primary  mechanism  for  responding  to   client
       requests.  To generate a controller, run:

             esp generate controller NAME [actions...]

       This  will  create a controller of the requested name. It will create a
       controller source file in the controllers directory.  If  action  names
       are  requested,  the controller source will define an action method for
       each name. You can edit the controller source to meet  your  needs.  It
       will not be overwritten unless you specify the --force switch.

GENERATING SCAFFOLDS
       A  scaffold  is a generated controller, database migration, client-side
       controller and set of views that provides add, edit and list  function-
       ality for the database table.  Scaffolds are useful to quickly generate
       chunks of the application and prototype web pages and actions for  man-
       aging a database table.  To generate a scaffold:

             esp generate scaffold MODEL [field:type ...]

       This  will  create a scaffold for the specified database table and will
       generate a controller of the same name.

       If field:type values are supplied, a database migration will be created
       with  code to create a column for each specified field of the requested
       type. The valid database types are: blob, boolean, date,  float,  inte-
       ger,  string,  and  text. The migration will use the name "create_scaf-
       fold_MODEL" and will be created under the migrations direcvtory.

       The scaffold will include an edit action and view  page  that  provides
       add and edit capability. The list action and view, provides the ability
       to list the table rows and select an entry to edit.

       If the --singleton switch is ues, the controller will be generated  for
       a singleton resource and will not have a list action.

COMPILING
       ESP  compiles  controllers  and ESP pages native code shared libraries.
       These are then loaded and run by ESP in  response  to  incoming  client
       requests.  Code is compiled only once but can be run many times to ser-
       vice incoming requests.

       In development mode, ESP will automatically compile the  relevant  por-
       tions  of the application if the source code is modified. It can intel-
       ligently recompile controllers and ESP pages.  However,  you  can  also
       explicilty  recompile  portions  or the complete appliction via the esp
       command.

       ESP can recompile everything via:

             esp compile.

       This will re-compile all ESP resources.

       ESP also provides options for you to individually  compile  controllers
       and ESP pages. To recompile named pages or controllers:

             esp compile path/*.esp....

            The  arguments  after  "compile"  are  pathname filters. These are
            resolved relative to the current directory.  Only  items  matching
            the filter pathnames are compiled.

       To  compile the entire application and produce a single combined shared
       library file, set the "esp.combine" property in the esp.json  file,  to
       true. Alternatively, invoke "esp --combine compile".

AUTHENTICATION
       ESP  can use the system password database or it can define passwords in
       the esp.json or in an application database.  To define passwords in the
       esp.json, use:

        esp user add username password roles...

       To define authentication roles, use:

         esp role add abilities...

CROSS-COMPILING
       To  compile  for  a target system of a different architecture, you must
       specify the target.  To do this, use the -platform  switch  to  specify
       the  target architecture. Specify the path to the platform directory in
       the Appweb source code built for that platform.

            esp -platform /home/dev/linux-arm-debug compile

MODE
       The esp mode command will retrieve and display the "esp.mode" property.
       The  esp mode debug command will modify the "esp.mode" property and set
       it to the "debug" value.  The esp release command will set the esp.mode
       to "release".

RUNNING
       To run your application, start the esp command to serve pages:

             esp serve

CLEANING
       To clean all generated module files:
             esp clean

MIGRATIONS
       Migration  files  can be run via the esp migrate command. With no other
       parameters, the command will run all migrations that have not yet  been
       applied  to the database. You can also use esp migrate forward to apply
       apply the next unapplied migration. Similarly esp migrate backward will
       reverse the last applied migration. You can also use esp migrate NNN to
       migrate forward or backward to a specific migration, where NNN  is  the
       migration sequence number at the start of the migration file name.

COMMANDS
       esp has the following command usage patterns:

             esp clean
             esp compile
             esp compile controllers name
             esp compile path/*.esp
             esp generate app name
             esp generate controllers name [action [, action] ...]
             esp generate scaffold model [field:type [, field:type] ...]
             esp generate table name model [field:type [, field:type] ...]
             esp serve
             esp serve 4000
             esp mode debug
             esp init appName version

OPTIONS
       --cipher cipher
             Password cipher to use. Set to "md5" or "blowfish".

       --combine
             Combine  compiled ESP assets into a single file. Used when build-
             ing with --static.

       --database Database provider
             Use the specified database provider. Set to "mdb"  or  "sdb"  for
             SQLite.

       --force
             Overwrite  existing files. ESP normally will not overwrite exist-
             ing files. This is to preserve user changes to previously  gener-
             ated files.

       --home dir
             Change the current working directory before beginning processing.

       --keep
             Keep intermediate source files in the cache directory. This over-
             rides the ejs.json "keep" setting.

       --listen [ip:]port
             Define  the  listening  endpoint  address. This will be used when
             generating an application. The value will  be  patched  into  the
             generated esp.json configuration file.

       --log logFile:level
             Specify  a  file  to  log  messages.   The syntax is: "--log log-
             Name[:logLevel]".  Level 3 will trace the  request  and  response
             headers.

       --name AppName
             Set  the ESP application name. Defaults to the name of the direc-
             tory containing the application.

       --noupdate
             Do not update esp.json.

       --optimize
             Compile optimized without debug symbols.

       --quiet
             Suppress diagnostic trace to the console.

       --platform [path/]os-arch-profile
             Target platform configuration to build for and directory contain-
             ing esp objects and libraries for the target platform.  If a path
             is supplied, the specified platform directory  is  used.   Other-
             wise,  esp searches from the current directory upwards for a par-
             ent platform directory.

       --rebuild
             Force a recompile of all items when used with  the  compile  com-
             mand.   When  used  with migrate, this will recreate the database
             and apply all migrations.

       --route pattern
             This selects the route by pattern that will be used for  the  ESP
             configuration.

       --single
             Generate a controller for a singleton resource instead of a group
             of resources. A singleton controller omits a list action.

       --show
             Display the route table to the console.

       --static
             Use static linking when building ESP  applications.  This  causes
             esp to create archive libraries instead of shared libraries.

       --symbols
             Compile for debug with symbols.

       --table name
             Override  the  database table name when generating tables, migra-
             tions or scaffolds. This is useful to request a plural version of
             the model name. Alternatively, specify the model name when gener-
             ating the scaffold, table or migration with  the  desired  plural
             suffix. For example: "-s" or "-ies".

       --trace traceFile:level
             Specify  a file for trace messages.  The syntax is: "--trace tra-
             ceName[:traceLevel]".   Level  3  will  trace  the  request   and
             response headers.

       --verbose or -v
             Run in verbose mode and trace actions to the console.

       --why or -w
             Explain why a resource was or was not compiled.

REPORTING BUGS
       Report bugs to dev@embedthis.com.

COPYRIGHT
       Copyright  (C)  Embedthis  Software.  Embedthis  ESP  is a trademark of
       Embedthis Software.

esp                              November 2014                          ESP(1)