SAnt build system

The SAnt (shared Ant) build system is an experimental, easy-to-use build system intended to replace Maven 1. Compared to Maven 1 (and 2) it is much easier to use and extend.

Table of contents

Installation

Supported platforms The command scripts for Windows use advanced capabilities of the command processor. If the scripts fail ensure command extensions are enabled.

Installation of SAnt is very simple. The overhead usually associated with installing new tools is avoided with SAnt.

To be able to use SAnt you have to have the following software already installed:

• Java 1.4+;
• Subversion <= 1.3.

Subversion 1.4 uses a new format for working copies which is not understood by the libraries used by SAnt yet. Please use Subversion 1.3 or earlier.  If you needed to downgrade your Subversion to 1.3, then remember to cleanly check out your sources, including your SAnt tree.

Ivy files

SAnt uses Ivy, a powerful dependency manager. Ivy needs a local repository for artifacts and a cache for remote repositories. By default these files are stored in the home directory of the user. This default location is most likely undesirable for most users.

To change the default location follow these steps:

1. Create directory .ivy in your home directory if it does not exist already.
2. Create file hippo-open-source-sant.properties in directory .ivy.
3. Set property ivy.local.default.root to the path of the directory where you want your local repository.
4. Set property ivy.cache.default.root to the path of the directory where you want the Ivy cache.

Please note that if you use backslashes in the path you have to escape them. For example:

ivy.cache.default.root=C:\\data\\ivy\\cache

It is advised to keep your Ivy local repository and cache for each project domain separate from other local repositories and caches, as the layouts of the repository and the cache depend on the Ivy configuration. Each project domain provides its own Ivy configuration to ensure everybody has the same configuration. Keeping the repository and the cache separate also ensures that you cannot accidentally include an artifact usable by one team in a project of another team.

hippo-open-source-sant.properties is required You do not have to change the default location by setting the properties but you have to create hippo-open-source-sant.properties.

The properties file created above is only for the hippo-open-sourceproject domain. If you want to create/use projects for a different project domain, you will need to create another properties file for that project domain called <project domain name>-sant.properties in the .ivy directory.

Getting SAnt

To get the latest version of SAnt check it out from our Subverions repository at http://svn.hippocms.org/repos/hippo/experimental/sant/trunk. The directory you check it out to will be called <sant home> below. This directory will contain directories sant and project-types.

Setup

The last steps of the setup are:

1. Add the <sant home>/sant/bin directory to your path.
2. Set environment variable SANT_HOME to <sant home>
3. Set environment variable JAVA_HOME to the home directory of a Java SDK.

You can make the changes to your global environment variables, but if you don't want to do this SAnt provides a command, for Windows only, with which you can easily set SANT_HOME and JAVA_HOME in the current console. After adding the bin directory to the path execute the following on Windows. On other systems you have to set SANT_HOME and JAVA_HOME manually:

sant-admin setup-environment <java SDK home> <sant home>

What did you get?

So what did you get when you checked out SAnt? You now have:

• Ant which is used to do the actual building.
• Ivy (as part of the Ant installation) which is used to manage dependencies.
• All JAR files needed for Ant tasks used by our projects.
• The Ivy configuration for Hippo describing which repositories we use for getting and publishing artifacts.
• Project types which provide a templates for new projects and contain the build scripts shared by all instances of a project type.

Creating a project

SAnt provides information about the available project types and it is easy to start with a project.

Listing project types

To get a list of the available project types execute:

sant-admin list-project-types

The list will display the project type name and (if available) a description of the project type. For more extensive information about a project type see the SAnt project type manuals.

Creating a project

To create a project create a directory for it and in that directory execute:

sant-admin create-project <project domain> <project type> <group ID> <module ID>

The project domain determines which repositories will be used for downloading artifacts, and where artifacts will be published. The project domains currently implemented are hippo-open-source and hippo-internal.

The group ID has the same meaning as the group ID used by Maven 1. The module ID has a different meaning than the artifact ID used by Maven 1. SAnt projects can produce multiple artifacts for a single module, so the module ID should be a name covering all artifacts produced.

This will make a copy of the template of the project type to the directory.

SAnt will not create a project in a directory already containing a project to prevent accidental overwriting of changes.

What did you get?

The directory structure for the project has been set up and a number of project files have been created. The files only contain information specific for this project. All the other information is in the project type to which the project refers.

The build script is called sbuild.xml to distinguish the project from an Ant-based project.

Working with projects

One of the goals of SAnt was to make it easy to work with projects, even if you do not know them well. SAnt is capable of providing information about what you can do with a project.

Targets and commands

SAnt has two methods of working with projects:

• Build targets, which perform an operation on the project as a whole, e.g. compile, test and publish.
• Commands, which can be used to automate common operations on specific resources of a project, e.g. create a JDO file for a class and create a test case for a class.

Listing targets and commands

To get the list of available targets execute the following command. Note that sant is a wrapper around Ant so it accepts the same arguments:

sant -p

To get the list of available commands execute:

pcmd list-commands

Executing targets and commands

As stated above sant is just a wrapper around Ant so you can use it just like ant. If you don't like the output generated, you can use santq which appends parameter -q. This results in almost no output.

Execute a command like this:

pcmd <command> <arguments>

Development

SAnt is currently not usable outside of Hippo. This will be changed in the near future. Ideas, requirements, etc. can be written on the SAnt development page.