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)