-*- text -*-

This is an interim snapshot of LShift's Icing web-development toolkit,
packaged as part of a demo conference-booking application.


LIMITATIONS
---------------------------------------------------------------------------

  * It's not well packaged, yet.

  * There's no documentation.

  * The database code is, unfortunately, MS SQL-Server specific.
    (Fixing this ought to be relatively straightforward.)

  * The LShift-internal project that drove the creation of Icing is
    still evolving. Improvements (some major!) from that project have
    yet to be folded in.


BUILDING
---------------------------------------------------------------------------

You will need:

  * Ant 1.6 or newer (we use 1.6.5)
  * Tomcat v4.1.30. (Newer versions /probably/ work.)
  * LShift's xml.pipeline v1_4_5
  * MS SQL Server (only if you're intending to run the demo app)

Instructions:

  * Copy sample.config.properties.xml to config.properties.xml.

  * Edit the config-name property to the name of a subdirectory of the
    config/ directory. The named subdirectory should contain
    build.properties.xml, which in turn should contain a <project/>
    element with machine- and user-specific build configuration
    properties.

    There's a template configuration in config/TEMPLATE/build.properties.xml.

    Notable build.properties.xml properties are documented later in this file.

  * If this is the first time you've used this tomcat instance with
    Icing, you will need to

    $ ant bless-tomcat-nocm

    (the "-nocm" magic is required to avoid trying to use an
    LShift-internal configuration management tool, "use.jar".)
    Bless-tomcat-nocm performs a one-off "bless" procedure on
    whichever tomcat instance you have selected by your
    build.properties.xml. The XML libraries bundled with Tomcat and/or
    the JDK are replaced with newer, less buggy libraries, that are
    required for Icing to work properly. The MS SQL Server jtds driver
    is also copied over into the tomcat installation.

  * Running the command

    $ ant deploy-nocm

    will build and deploy the Icing demo application into the tomcat
    instance you've configured. In order to actually run the
    application, you'll need to create and populate the database:

    $ ant create-db
    $ ant populate-db

    Other interesting ant targets are

    $ ant clean
    $ ant clean-deploy-nocm
    $ ant dist-nocm

    Clean removes build products from your working copy.
    Clean-deploy-nocm deletes the deployed application from Tomcat's
    webapps directory. Dist-nocm prepares a .war file ready for
    deployment.


BUILD CONFIGURATION PROPERTIES IN build.properties.xml
---------------------------------------------------------------------------

jdbc.username, jdbc.password: Credentials for connecting to the
application database.

jdbc.url: Location of the application database.

jdbc.driver: Class name of the JDBC driver to use for connecting to
the application database.

db.db-name: The name of the database to create.

db.object-owner: The SQL user name to use for the owner of the DB
objects created - we use "dbo" here.

xml.pipeline.home: Must point to a directory such that
${xml.pipeline.home}/lib/pipeline.jar exists.

tomcat.home: Must point to a directory such that
${tomcat.home}/common/endorsed/ and ${tomcat.home}/webapps/ exist.

deploy.dir: Path to your Tomcat installation's webapps directory.


GUIDE TO THE SOURCE TREE
---------------------------------------------------------------------------

config - Contains per-user/per-machine/per-working-copy
build.properties.xml files in subdirectories.

etc - Contains sample Tomcat server.xml and web.xml files.

lib - Contains required libraries for Icing.

src/3rdparty - Support modules for Icing, not directly related to the
project itself.

src/ant - Fragments of build.xml for controlling the building and
deployment of the application.

src/java - Java support code for Icing.

src/scm - Source code both for the Icing libraries and for the demo
application. Also contains third-party code such as SSAX and SXPATH.

src/sql - Demo application MS SQL Server database creation, deletion
and population scripts.

src/templates - Contains HTML templates for the demo-application user
interface. These templates are processed by project-tags.xsl and
template-compiler.xsl by the build process.

web/styles - Contains stylesheets for the demo application.

web/xslt - Contains the template-compiler for the Icing HTML template
mechanism, as well as custom project tags that can be expanded into
project-specific boilerplate HTML.
