Table of Contents

Introduction
Installing the Heml Webapp
Checking Out Heml
Checking out the Heml CVS Repository
Building Heml
Updating Your CVS

This document is a guide to the process of downloading and building the code locally. In general, this project uses the tools and procedures of the Cocoon group at Apache.

Heml is being constructed on an open-source development model: all interested parties are encouraged to look over the java and xslt source code and to make contributions to it. Up-to-date versions of the code can be checked out of our CVS server, altered and built locally. Qualified persons will be granted write access to the CVS server as well. See the section below on CVS access for detail instructions. Alternatively, you may download a 'webapp' version of Heml. A webapp is a compressed archive of resources that is installed in a Java Servlet engine. This is the equivalent of downloading a binary file, but it will make locally available to you this entire web site.

Our development model is 'breadth-first': the markup language and transformations are made more complex in step with each other; ideally the markup language will never include concepts that are left unexpressed in the transformations. Heml also strives to use common computational tools. As much as possible of it is written in xslt, though much of this code makes use of our Java extensions to the Xalan xslt engine. This version of Heml uses version 2.1.7 of the Cocoon publishing framework to organize and integrate its transformations into a website.

Heml is most easily run within the servlet engine built into Cocoon 2.1.x. By default, This runs on port 8888 of your localhost: http://localhost:8888 should bring up the Cocoon homepage once you have built it with its instructions. Browse around it to make sure it works properly.

  1. Have a JDK 1.4-1.5 (current) java environment.
  2. Download the latest version of Heml from our server. as of this writing ($Date: 2006-02-08 15:23:44 -0400 (Wed, 08 Feb 2006) $), v. 0_7.1
  3. Restart tomcat, and point your browser to the heml server: http://localhost:8080/cocoon-with-heml/samples/heml/, assuming the usual values are set .
  4. Install your heml documents in the $TOMCAT_HOME/webapps/cocoon-with-heml/samples/heml/docs/source directory.

The following section briefly outlines how code is checked out and built. It is no substitute for general introductions to CVS and ant , the applications that underlie this process.

The entire Heml website's documents and source code are available in a Subversion server. Subversion is a popular and free system that stores and retrieves groups of documents in such a way that they might reliably be written and edited by many people concurrently. Users who wish to aid in the development of Heml or to adapt it to suit their local needs or who wish to have the most up-to-date version of the project should follow these instructions to download Heml from Subversion and build it locally.

Building Heml locally requires the following software in addition to the requirements listed above:

  1. A CVS client for downloading the documents and source code. Unix-clone users will likely find that they have a 'cvs' command-line application installed from their distribution. Windows and Macintosh clients are available from http://www.cvshome.com . Many windows users find the Tortoise CVS tool to be an amazing help.

  2. A Cocoon 2.0.x source release. cocoon-2.0.4 is the most recent.

Windows 95/98 users: before Heml can be successfully downloaded, the following environment variables must be set:

  1. CVS_HOME (set this to the directory which houses CVS)
  2. HOMEDRIVE (set this in autoexec.bat -- for example: set HOMEDRIVE=c:)
  3. HOMEPATH (set this in autoexec.bat -- for example: set HOMEPATH=\user)
It may also be necessary to set the USERNAME on the system to anonymous.

These are the steps taken to download and build Heml locally:

  1. Login to the CVS server at :pserver:anonymous@heml.mta.ca:/home/heml/cvsroot using the password anoncvs and issue the checkout heml_cvs command. With the unix-clone cvs command-line utility, the following commands would be used: 
    cvs -d :pserver:anonymous@heml.mta.ca:/home/heml/cvsroot login
cvs -d :pserver:anonymous@heml.mta.ca:/home/heml/cvsroot checkout heml_cvs
    CVS will then create a directory entitled heml and fill it with the source code and documents of the Heml project.

The resulting directory cannot be installed directly into a tomcat webapps directory. Its source code must be complied and its files must be put in the proper hierarchy within the webapp directory. 'Building' the Heml webapp in this way is done with Jakarta ant.

Building Heml locally requires the following software in addition to the requirements listed above:

  1. A Cocoon 2.1.x source release. cocoon-2.1.4 is the most recent.

  2. (To build local copies of documentation) xsltproc

With these in hand, follow these steps:

  1. Set local variables. The $COCOON_HOME and $HEML_HOME variables must be set to assist the build process. $COCOON_HOME points to your cocoon-2.1.x directory. $HEML_HOME should be set to the path to the heml directory just created by CVS. Be sure that your $JAVA_HOME environment variable is also set.
  2. Execute the build by running the build.sh all or build.bat all command under your heml directory. This will set up a Heml 'sample block' in your cocoon environment, then ask cocoon to build itself. In effect, Heml has been integrated into a cocoon build.
  3. From here on, you follow the directions for running and using Cocoon. Cocoon now has its own servlet engine build-in, so you no longer need install tomcat in order to run Cocoon. Rather, enter the $COCOON_HOME directory and run ./cocoon.sh servlet or cocoon.bat servlet.
  4. Point your browser to http://localhost:8888/ for the cocoon welcome page and follow it to samples and blocks, or point your browser to http://localhost:8888/samples/heml.
  5. Run other ant 'tasks' defined in build.xml file. For instance, the 'javadoc' task builds a local javadoc for the Heml java code. These tasks are run by appending the task name to build.sh, for instance, build.sh javadoc

When you alter the xslt or java source in your $HEML_HOME, run build.sh to have the altered files installed in the webapp.

Once you have checked out Heml from the repository, you can update your local version by running the following command in $HEML_HOME: 

cvs update

Valid XHTML 1.0 Strict Heml Project (c) 2001-2006 Bruce Robertson