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
       cation. Then from that directory run pak to install the  required  sup-
       porting packs. For example:

             mkdir blog
             cd blog
             pak install embedthis/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.



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.

       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.

       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.


             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.

             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)

Man(1) output converted with man2html