    ESP(1)                           User Commands                          ESP(1)

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

    SYNOPSIS
           esp  [--apply]]  [--chdir dir]] [--config configFile]] [--database DB]]
           [--flat] [--genlink slink.c] [--keep] [--listen [ip:]port] [--log  log-
           File:level]   [--overwrite]   [--quiet]   [--platform  os-arch-profile]
           [--rebuild]  [--static]  [--routeName  name]   [--routePrefix   prefix]
           [--verbose] [--why] commands ...

           Commands:
            esp clean
            esp compile
            esp compile [pathFilters...]
            esp generate app name
            esp generate controller name [action [, action] ...]
            esp  generate  migration  description model [field:type [, field:type]
           ...]
            esp generate scaffold model [field:type [, field:type] ...]
            esp generate table name model [field:type [, field:type] ...]
            esp migrate [forward|backward|NNN]
            esp run

    DESCRIPTION
           The esp command generates, manages and runs ESP web  applications.   It
           can  generate  ESP  web applications, 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 --overwrite switch.

           Esp can run your application by invoking a configured web server.

    GENERATING APPLICATIONS
           To start a new web application,  run  esp  to  create  the  application
           directory  and  generate  the  application  configuration and essential
           script files. For example:

                 esp generate app blog

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

                 cache          - Cache directory for compiled content
                 controllers    - Controller source
                 db             - Databases and scripts
                 db/migrations  - Databases migration modules
                 layouts        - Web page layout files
                 static         - Static web directory
                 static/images  - Public images
                 static/js      - Client side JavaScripts
                 static/themes  - Application HTML themes
                 views          - View source files

           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.

           Esp will also create some files which have the following meaning:

                 appweb.config             - Appweb configuration file
                 app.config                - Appweb configuration file
                 esp-app.h                 - Application header file
                 layouts/default.esp       - Default layout web page
                 static/layout.css         - Default layout CSS file
                 static/themes/default.css - Default theme CSS file
                 static/js/jquery.js       - jQuery client side script

    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
           db/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. If not action names are requested, esp will define a default
           action named index.  You can edit the controller source  to  meet  your
           needs.

    GENERATING SCAFFOLDS
           A  scaffold  is  a generated controller, database migration, and set of
           views that provides add, edit and list functionality for  the  database
           table.  Scaffolds are useful to quickly generate chunks of the applica-
           tion and prototype web pages and actions for managing a database table.
           To generate a scaffold:

                 esp generate scaffold TABLE [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_TABLE" and will be created under the db/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.

    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  pages and MVC applications for routes
           defined in the appweb.conf file.

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

                 esp compile path/*.esp....

                 esp compile controller NAMES....

                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 shared library
           file:

                 esp --flat compile .

    RUNNING
           To run your application:

                 esp run

    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 controller name
                 esp compile path/*.esp
                 esp generate app name
                 esp generate controller name [action [, action] ...]
                 esp generate scaffold model [field:type [, field:type] ...]
                 esp generate table name model [field:type [, field:type] ...]
                 esp run

    OPTIONS
           --chdir dir
                 Change the current working directory before beginning processing.

           --config configFile
                 Use the specified config file instead of appweb.conf

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

           --flat
                 Compile the application flat into a single shared library file.

           --genlink slink.c
                 Generate a static link initialization  file  for  ESP  pages  and
                 applications.   This  is used with --static to generate a appweb-
                 StaticInitialize() function that will invoke all  ESP  initializ-
                 ers.    By   default,   appweb   expects   this   to  be  in  the
                 src/server/slink.c file.

           --keep
                 Keep intermediate source files in the cache directory. This over-
                 rides the EspKeepSource setting in the appweb.conf file.

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

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

           --overwrite
                 Overwrite  existing  files.  Ejsweb  normally  will not overwrite
                 existing files. This is to preserve user  changes  to  previously
                 generated files.

           --quiet
                 Suppress diagnostic trace to the console.

           --platform os-arch-profile
                 Target platform configuration to build for.

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

           --reverse
                 Reverse the application of migrations.

           --routeName name
                 This  selects  the Appweb route by name that will be used for the
                 ESP configuration. The ESP directory names, and compilation  com-
                 mands  are  determined  by  the  ESP configuration drawn from the
                 specified route. The default is the first route with the ESP han-
                 dler defined in appweb.conf.

           --routePrefix prefix
                 This selects the Appweb route by prefix that will be used for the
                 ESP configuration. The ESP directory names, and compilation  com-
                 mands  are  determined  by  the  ESP configuration drawn from the
                 specified route. The default is the first route with the ESP han-
                 dler defined in appweb.conf.

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

           --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) 2004-2013 Embedthis Software.   ESP  is  a  trademark  of
           Embedthis Software.

    SEE ALSO
           appweb

    esp                              November 2013                          ESP(1)