Embedthis Appweb 4.3.4
Home >ESP Guide> Application Generator

# Quick Nav

# See Also

# Application Generator — esp

The ESP web framework provides an application generator and building tool named in the esp program. This tool makes it easy and quick to create and manage your web applications. The esp command generates MVC web applications, database schema, scaffolds and views. The esp command can be used to run your application by invoking the Appweb web server and it can be used to pre-compile controllers, views and web pages.

The esp program is not just for MVC applications. It can be used to pre-compile stand-alone ESP web pages too.

## Generating Applications

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

    esp generate app blog

The esp command will create directories and generate configuration and source code files which can then be manually edited as required. The esp command 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.

### Created Directories

The esp command will create some standard directories when generating an application. Some of these directories are initially empty, but may be used over time. ESP follows conventions where specific files are stored. This greatly simplifies configuring and managing web applications.

Directory | Purpose
--- | ---
cache | Cached modules and views
controllers | Controller source
db | Databases and scripts
layouts | Layout template pages
views | View source files
static | Static web content
static/images | Client side JavaScripts
static/js | Client side JavaScripts
static/themes | Application HTML themes

The esp command will also create some files which have the following meaning:

Files | Purpose
--- | ---
appweb.conf | Appweb startup configuration file
static/themes/default.css | Default theme CSS file
static/layout.css | Default layout CSS file
layouts/default.esp | Default layout template page

## Generating Controllers

Controllers are the primary mechanism for responding to client requests. To generate a controller:

    esp generate controller NAME [actions...]

This will create the named controller in the controllers directory. A controller manages the web application and the controller action methods are invoked by ESP to respond to client requests and generate responses.

If no actions are requested, esp will create a default index action method. If other actions are requested, esp will create an empty action method for each requested action. You can edit the controller source to meet your needs.

If you use the command:

    esp generate controller admin edit login logout command

The following controller code will be generated. There is one function generated for each action and a call to espDefineAction is added to register the controller. The esp_controller_admin initialization function is invoked once when the controller is first loaded.

    /*
        admin controller
     */
    #include "esp.h"
    static void edit() {}
    static void login() {}
    static void logout() {}
    static void command() {}
    ESP_EXPORT int esp_controller_admin(EspRoute *eroute, MprModule *module)
    {
        espDefineAction(eroute, "admin-edit", edit);
        espDefineAction(eroute, "admin-login", login);
        espDefineAction(eroute, "admin-logout", logout);
        espDefineAction(eroute, "admin-command", command);
        return 0;
    }

## Generating Database Tables

Database schema can be created and modified via the esp command. This will create a database table with fields of the required types.

    esp generate table NAME [field:type ...]

If field:type values are supplied, the database will be updated for each specified field of the requested type. The valid database types are: binary, boolean, date, datetime, decimal, float, integer, number, string, text, time, timestamp.

## Generating Scaffolds

Scaffolds enable you to quickly create sections of your application. A scaffold provides CRUD (create, read, update and delete) functionality for a database table. Generating a scaffold will create a database table, controller and a set of views that provide add, edit and list functionality for a database table. Scaffolds are useful to quickly generate prototype web pages and actions for managing a database table. To generate a scaffold:

    esp generate scaffold NAME [field:type ...]

This will create a scaffold for the named database table and will generate a controller of the same name. If field:type values are supplied, the database will be updated with columns for each specified field of the requested type. The valid database types are: binary, bool, date, float, int, string, text. 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 database table rows and select an entry to edit.

## Compiling

ESP compiles views and controllers into native machine code libraries. These are automatically compiled in response to client requests and are then loaded and run by ESP to serve the relevant response. Code is compiled only once but can be run many times to service incoming requests.

ESP will automatically recompile controllers, views and web pages, however you can also source code is modified. It can intelligently recompile views and controllers as required. However, you can also explicitly pre-compile portions or the complete application via the esp command.

### Compile Everything

The esp command can recompile the entire application via:

    esp compile

This will compile and link all controllers and views and place the generated shared libraries (DLLs) in the cache directory.

If you are using static linking, use the --static switch to generate archive libraries instead of shared libraries. If you are doing this, you must manually call the ESP initializers. See the --genlink option for how to generate the code to call the ESP initializers.

### Routes

When esp is invoked it, loads the appweb.conf configuration file from the current directory. If not found, esp will search up the parent directories for an appweb.conf file to use. The --config option may also contain a full path to an appweb.conf file.

An appweb.conf file may contain directives for one more more applications. It will usually contain many routes for various URIs. When esp compile is invoked, esp will compile the resources managed by each of the ESP routes specified in the Appweb configuration file.

### Filtering

If esp compile is invoked with one or more paths on the command line, these paths will act as filters such that only the designated paths will be compiled. For example:

    esp compile web/test.esp
    esp compile myapp
    esp compile views
    esp compile /path/to/my/app
    esp compile /directory/of/apps

These paths are interpreted as filenames relative to the current directory. If a controller, view or web page filename is provided, only that resource will be compiled. If a directory that is part of an MVC application is provided, then all resources under that directory will be compiled. If a directory that is a parent directory of ESP applications or web pages, then all those resources contained by that directory will be compiled.

You may also use the --routeName or --routePrefix switches to select a specific route in the appweb.conf configuration file. Then only the resources managed by that route will be compiled.

### Keep Source

When compiling views or web pages, the EspKeepSource configuration file directive will control if the intermediate C source code generated from the ESP will be preserved. This can sometimes be helpful for debugging.

### Compile Application as One Module

For deployment in a production environment, it can be useful to compile the entire application including all controllers, views and web pages into a single module file. Use the --flat esp option to achieve this:

    esp --flat compile

If you compile flat, you will need to add an EspLoad directive to the appweb.conf. This tells ESP to pre-load the application and where to locate the module file.

    EspLoad NAME PATH

When using dynamic linking, appweb automatically invokes the necessary ESP initializers when running ESP pages or invoking ESP controllers. However, if you are using static linking, you need to manually call these ESP initializers. You can generate the necessary initialization calls via the esp --genlink slink.c switch. The generated code should be linked with your appweb main program replacing the default slink.c file.

    esp --flat --static --genlink slink.c

### Cross Compiling

When esp compile is invoked, it selects its compile and link rules from the esp.conf configuration file. This file, which may be customized, contains the rules for various operating systems and CPU architectures. The esp.conf file is included automatically when the ESP handler is added.

By default, the current system configuration is selected if not cross compiling. If cross-compiling, the configuration for the target host specified via the Appweb configure program is utilized.

The esp command can select alternate compile and link configurations via the --platform switch. For example:

    esp --platform vxworks-arm-debug

This will compile the application for VxWorks on arm. Of course, the resulting module cannot be run on the development system if cross-compiling.

The --platform option will search current directory and parent directories for an Appweb platform directory of the same name. You can provide a full path name as an argument to the --platform switch if your application is outside the Appweb source tree.

Note: You may need to modify the esp.conf configuration file to add rules for your operating system and CPU architecture or to customize for your application.

## Running

To run your application:

    esp run

## Cleaning

To clean all generated files under the cache directory:

    esp clean

## Command Options

To see the esp command options, run esp with no options. This produces:

    ESP Usage:
      esp [options] [commands]
      Options:
        --chdir dir                # Change to the named directory first
        --config configFile        # Use named config file instead appweb.conf
        --database name            # Database provider 'mdb|sqlite'
        --flat                     # Compile into a single module
        --genlink                  # Generate a static link module for flat compilations
        --host OS                  # Target O/S
        --keep                     # Keep intermediate source
        --listen [ip:]port         # Listen on specified address
        --log logFile:level        # Log to file file at verbosity level
        --overwrite                # Overwrite existing files
        --quiet                    # Don't emit trace
        --platform os-arch-profile # Target platform. May be a full path.
        --rebuild                  # Force a rebuild
        --reverse                  # Reverse migrations
        --routeName name           # Route name in appweb.conf to use
        --routePrefix prefix       # Route prefix in appweb.conf to use
        --show                     # Show compile commands
        --static                   # Use static linking
        --verbose                  # Emit verbose trace
        --why                      # Why compile or skip
      Commands:
        esp clean
        esp compile
        esp compile [pathFilters ...]
        esp migrate [forward|backward|NNN]
        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 [field:type [, field:type] ...]
        esp run

Switch | Description
--- | ---
--chdir dir | Change to the specified directory.
--config configFile | Use the named config file instead of appweb.conf.
--database connector | Select a database connector to use. Currently, this switch is not implemented and sqlite is the only connector supported.
--flat | Compile entire application into a single module. Same as "esp compile flat".
--genlink slink.c | Generate a file of ESP initializers when using --static and --flat".
--keep | Preserve intermediate files. Useful for debugging.
--listen [ip:]port | Listen on the specified address. Overrides the Listen directive in appweb.conf.
--log logFile:level | Log errors and trace to the log file at the given verbosity level. Levels are 0-9 with nine being the most verbose.
--name | Name for the application when compiling flat.
--overwrite | Overwrite existing files. The esp command normally will not overwrite existing files. This is to preserve user changes to previously generated files.
--quiet or -q | Run quietly and don't trace actions to the console.
--platform os-arch-profile | Target platform. This may be a full path to an Appweb platform directory in an Appweb source tree.
--rebuild | Force a rebuild of all components.
--reverse | Reverse migrations.
--routeName name | Route name in appweb.conf to use for ESP configuration.
--routePrefix prefix | Route prefix in appweb.conf to use for ESP configuration.
--show | Show all commands invoked by esp.
--static | Use static linking when compiling ESP components.
--verbose or -v | Run in verbose mode and trace actions to the console (default).
--why | Show why a compile was performed or omitted.

© Embedthis Software LLC, 2003-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.