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 logFile: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 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 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 application 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, integer, string, and text. The migration will use the name "create_scaffold_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 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 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 appwebStaticInitialize() function that will invoke all ESP initializers. By default, appweb expects this to be in the src/server/slink.c file.

--keep
    Keep intermediate source files in the cache directory. This overrides 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 logName[,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 command. 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 commands are determined by the ESP configuration drawn from the specified route. The default is the first route with the ESP handler 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 commands are determined by the ESP configuration drawn from the specified route. The default is the first route with the ESP handler 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 © 2004-2013 Embedthis Software. ESP is a trademark of Embedthis Software.

SEE ALSO
appweb