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)