Project Type Development Manual

This page describes how to create a new project type for SAnt.

Basic structure

A project type consist of a number of mandatory and optional parts. Let's start with the mandatory parts:

an Ant build file;
a text file containing the description;

The optional parts are:

a directory containing the template for the project type.
a directory containing resources used in the build file;
a directory containing JAR files containing the code for project commands;
a properties file describing the project commands of the project type;
a text file containing the project type that is extended;
a text file containing the modules that are included;
an XML file describing the Ivy configurations for the artifacts produced.

For understanding the basic structure see project type public-resoources. It is the simplest project type so should help getting you started with your own project type quickly.

Ant build file

The build file is a regular Ant build file. It must be named according to this pattern: <project type name>-build.xml, e.g. standard-library-build.xml.

Please make sure that you document each target that a user is allowed to invoke by adding attribute description to the element of the target.

Description

The description is the text that gets displayed below the project type name when a user lists the project types using the sant-admin command.

For proper layout you have to indent the text with two spaces, and you have to do your own line wrapping (underscores were added to show the indent):

__This is my first project type. It simply encodes all files
  in the source directory using ROT13.

Template

Upcoming change

Currently a project type can have only one template. This will change in a future version of SAnt.

The template is used when creating new projects of the project type. It contents will be copied to the directory of the new project. During the copying a number of Ant tokens will be replaced with information entered on the command line used to create the project.

If the template directory is not present, the project type is considered to be abstract, i.e. not instantiable.

A template must contain:

a properties file containing the project properties;
a properties file containing information about where SAnt can be found on the current system;
an Ant file called sbuild.xml;
any directories (even empty ones) and files that form the basic structure for an empty project.

Project properties

The project properties are called project.properties and must contain at least the following two properties with the values shown. The values, which are tokens, will be replaced when the template is copied to the directory of the new project:

project.organisation=@sant.project.groupId@
project.name=@sant.project.moduleId@

Because the build file of the project type is shared by all projects of that type, the information cannot be stored in the build file. That is why it is in project.properties.

SAnt properties

The SAnt properties tell SAnt to which project domain a project belongs and what its project type is. This makes it easy to move a project to another project domain, and to change the project type respectively. The SAnt properties are called sant.properties and must contain at least the following two properties with the values shown. The values, which are tokens, will be replaced when the template is copied to the directory of the new project:

sant.project.domain=@sant.project.domain@
sant.project.type=@sant.project.type@

Build file

To prevent mistaking an Ant project for a SAnt project and vice versa, SAnt uses another name for the build file than Ant: sbuild.xml. This file is the same for all project types, except for the default target:

<?xml version="1.0" encoding="UTF-8"?>
<project name="@sant.project.moduleId@" default="nop">
  <!-- NEVER MODIFY THIS FILE! MAKE CHANGES TO THE PROJECT TYPE. -->

  <property file="local-sant.properties" />
  
  <property name="sant.home" value="### NOT SET ###"/>
  <fail>
    <condition>
      <equals arg1="${sant.home}" arg2="### NOT SET ###"/>
    </condition>
    &gt;&gt;&gt;
    
    Set the property 'sant.home' in 'local-sant.properties'. You can use the
    following command:
        sant-admin create-local-sant-properties
  </fail>
  
  <property file="sant.properties" />

  <import file="${sant.home}/project-types/${sant.project.type}/${sant.project.type}-build.xml" />
</project>

The build file uses the information in local-sant.properties and sant.properties to determine the location of SAnt and the project type. Using this information the build file of the project type is found and included.

Directories and files

Depending on the project type the template can contain a number of (empty) directories and files so users don't have to create that structure each time they start a new project. For example, directory src/java for Java projects.

More to come

The above gets you started with project types. The explanation of the other parts of a project type will be added soon.

Page Operations

Browse Space