- Summary
- Documentation
- Downloads
- Resources
- Development

Documentation

These are the release notes for version 0.5 of the Diesel File Generator source code.

1. For the Impatient Reader

Three ways to build the distribution from source code:

build.bat dist (on Windows)
./build.sh dist (on UNIX, including Linux)
ant dist (if you have Ant already installed, configured with JUnit task)

Three ways to build the JavaDoc and unit test report from source code:

build.bat doc (on Windows)
./build.sh doc (on UNIX, including Linux)
ant doc (if you have Ant already installed, configured with JUnit task)

Command line usage:

diesel [-d name] -o dir -m file [-h] -c dir
  -c,--input dir    cartridge directory
  -d,--domain name  domain model format
  -h,--help         shows this message
  -m,--model file   input model file
  -o,--output dir   output directory

2. What is the Diesel File Generator?

The Diesel File Generator creates a directory with output files, using a domain model or generic model and a reusable cartridge with templates and other files. Model files are defined in XML, and cartridges use the Velocity templating language. Domain models are converted to generic models though XSL transformations.

In the terminology of the Code Generation Network, the Diesel File Generator is a passive tier generator that creates text files of any kind, with facilities for using XML domain languages.

2.1. Domain Model Format

The domain model is an XML document that provides information that the file generator plugs into templates to create output files. In order to use a particular type of domain model file with a cartridge, the cartridge must contain an XSL file that defines the transformation from that type of domain model file into a generic model file.

2.2. Generic Model Format

The generic model is an XML document with a map of key/value pairs. Each value can be a string, a list of values, or a map of key/value pairs. Lists and maps can be nested to arbitrary depth. The generic model file can be passed directly to the Diesel File Generator, or Diesel can create it by applying a specified XSL transformation to a domain model file.

2.3. Template Format

Templates use the Velocity templating language. The Diesel File Generator can generate one or more output files from each template. The cartridge configuration file can specify the mapping of one file name to multiple file names by using data from the generic model. When generating files, each template receives a context with the generic model data. For templates that are used to create multiple files, the template context also includes a reference to the part of the generic model data specific to that instance of the file.

2.4. Cartridge Format

The cartridge directory has two main components: the META-INF directory with configuration and metadata, and the Content directory with templates and other files. The META-INF directory contains the Cartridge.xml file, which describes the files in the Content directory and how they are to be used. The META-INF directory also contains a Domains directory, which has an XSL translation file for each domain type which can be used with the cartridge. The Content directory can contain template files, opaque files, and ignored files. Opaque files are copied without applying any template expansion. This is useful for compiled libraries and other binary files. The Cartridge.xml file can identify files and directories to ignore, so they do not appear in the generated directory. This is useful for CVS directories and other artifacts of the build environment.

2.4.1. Cartridge Directory

+-- META-INF/
|   |
|   +-- Cartridge.xml
|   |   (namespace, default type,
|   |    template file paths, opaque file paths, ignored file paths,
|   |    file expand mappings)
|   |
|   +-- Domains/
|       |
|       +-- *.xsl
|
+-- Content/
    |
    +-- **/[template files]
    |
    +-- **/[opaque files]
    |
    +-- **/[ignored files]

2.5. Dependencies

Diesel requires a Java runtime environment. It has been tested with J2SE 1.4, but may also work with earlier versions. Diesel uses Velocity 1.3.1, Xalan 2.5.2, Xerces 2.4.0, Jakarta Commons Logging 1.0.2, and Jakarta Commons CLI 1.0.

3. License

Diesel is licensed under the Apache License, Version 2.0.