Taglets Collection

This document describes how to set up a local development copy of the project directory.

Starting Out

Development setup is a three step process:

1. Repository check out.
2. Build environment configuration.
3. Initial build.

Repository Check Out

First, check out the sources from the CVS repository.

E.g. on Unix/Mac OS X:

cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/taglets checkout taglets

Alternatively you may of course also use a graphical CVS client or use the CVS repository browser of your favourite IDE. Make sure that you use the following connection parameters:

Repository Host: cvs.sourceforge.net
Repository Path: /cvsroot/taglets
Connection Type: pserver
Connection Port: 2401 (default)
Checkout Module: taglets

cvs -d :extssh:${LOGNAME}@cvs.sourceforge.net:/cvsroot/taglets checkout taglets

Build Environment Configuration

In the following all files mentioned are listed relative to the toplevel directory of the project directory. Also, all build commands should be executed from the toplevel directory of the master module.

Site and User Specific Configuration Files

To keep site and user specific information out of the build process the build tools use the following configuration files:

The build script first imports the site specific configuration file and then launches ANT which in turn imports the following files:

Thus, the user configuration overrides the site configuration which in turn overrides the default values.

To create and/or configure the site and user specific configuration files refer to the sections Semi-automated Setup or Manual Setup below.

Semi-automated Setup

There is a small setup script which will help you conduct the steps outlined in the manual setup section below. In the toplevel directory execute:

On Unix/Mac OS X

$ ./build.sh setup ${USER} ${SITE}

or on Windows

> build setup ${USER} ${SITE}

Where ${USER} is your username and ${SITE} is your sitename.

Once the configuration files are in place and the site specific path to the J2SE is set proceed to perform the Initial Build.

Manual Setup

If you want to prepare the setup manually perform the following steps:

1. The Ant startup script build.sh (Unix/Mac OS X) or build.cmd (Windows) includes another script (env/site.sh on Unix/Mac OS X or env/site.cmd on Windows) that has to set the site specific path to a J2SE 1.5.0 installation and to set an appropriate path that includes libraries and binaries used. Make a link (on Unix/Mac OS X) or a copy (on Windows) to one of the existing confiuration/site_*.sh or confiuration\site_*.cmd files.

   E.g. on Unix/Mac OS X

   $ cd env
   $ ln -s configuration/site_foo.sh site.sh

   or on Windows

   > cd env
   > copy configuration\site_foo.cmd site.cmd

2. The build file for Ant includes the configuration file env/user.xml. Since this file is sourced first, it is possible to overwriteall properties here for a certain user. Additional tasks can also be defined in this file. Make a link (on Unix/Mac OS X systems) or a copy (on Windows systems) to one of the existing configuration/user_*.xml files.

   E.g. on Unix/Mac OS X

   $ cd env
   $ ln -s configuration/user_john_doe.xml user.xml

   or on Windows

   > cd env
   > copy configuration\user_john_doe.xml user.xml

3. The build file for Ant includes also the configuration file env/site.xml. Since this file is sourced right after the user specific file env/user.xml (see above), it is possible to overwrite all properties here that have not been specified in the user specific file. Additional tasks can also be defined in this file. Make a link (on Unix/Mac OS X systems) or a copy (on Windows systems) to one of the existing configuration/site_*.xml files.

   E.g. on Unix/Mac OS X

   $ cd env
   $ ln -s configuration/site_foo.xml site.xml

   or on Windows

   > cd env
   > copy configuration\site_foo.xml site_local.xml

If your target is a new site, you may have to create your own site specific include file. In the env/templates directory are templates that should give you an idea of the parameters.

Initial Build

Some portions of the documentation (API documentation and some other HTML pages) are generated automatically. So your initial setup process should build this documentation in the next step. But also after a later update it is good practice to proceed with the next step to ensure that everything is correctly (re-)built.

To create all generated sources and documentations and to compile all parts of the project the build tool build.sh (Unix/Mac OS X) or build.cmd (Windows) has to be started with the target world.

E.g. on Unix/Mac OS X

$ ./build.sh world

> build world

After all these steps all parts of the whole project is built and the documentation should be complete.

The targets of the master build file are listed on the Build Environment page (this page is only avaible once build world has been run).