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
       supporting 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 packaged
       using the Pak utility (see https://www.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
       database. 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.
             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
       functionality for the database table.  Scaffolds are useful to quickly
       generate chunks of the application and prototype web pages and actions
       for managing 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, integer,
       string, and text. The migration will use the name "create_scaffold_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 service
       incoming requests.

       In development mode, ESP will automatically compile the relevant portions
       of the application if the source code is modified. It can intelligently
       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.

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
             Password cipher to use. Set to "md5" or "blowfish".

       --combine
             Combine compiled ESP assets into a single file. Used when building
             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 existing
             files. This is to preserve user changes to previously generated
             files.

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

       --keep
             Keep intermediate source files in the cache directory. This
             overrides 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
             logName[:logLevel]".  Level 3 will trace the request and response
             headers.

       --name AppName
             Set the ESP application name. Defaults to the name of the directory
             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 containing
             esp objects and libraries for the target platform.  If a path is
             supplied, the specified platform directory is used.  Otherwise, esp
             searches from the current directory upwards for a parent platform
             directory.

             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, migrations
             or scaffolds. This is useful to request a plural version of the
             model name. Alternatively, specify the model name when generating
             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
             traceName[: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 © Embedthis Software. Embedthis ESP is a trademark of Embedthis
       Software.




esp                               November 2014                           ESP(1)