HomeDownloadsUser GuideDevelopment

Development: Introduction

Introduction

This document gives a short introduction to the build system and the most important commands you will want to use.

Build System

The OpenPermis build environment is Ant based. However, instead of relying on your installation of Ant (which may or may not be the correct version) the OpenPermis project comes with a bundled version of Ant that includes all the extensions necessary for the build.

The only difference between an ordinary Ant project and the self-contained OpenPermis build system is that you need to use a custom build script to execute build commands. The rest of the build is composed of ordinary Ant build scripts and should be familiar to anyone who has ever worked with Ant.

For more information about how to setup the OpenPermis build script please refer to the Build Setup page.

Structure

The main build driver file the usual build.xml stored in the toplevel of the project. Since the build is highly modularized the driver file mainly imports module build files and provides a few global targets to execute common tasks.

The following outlines the most important build files used:

build.xml
The toplevel and build file used by the build.sh command.
build.sh
Unix / Mac OSX script file to invoke the built-in Ant with the correct classpath.
build.cmd
Windows command file to invoke the built-in Ant with the correct classpath.
shared
Folder that contains shared build files, libraries and documentation.
build
Task specific build files.
audit.xml
Auditing tasks.
compile.xml
Everything compilation related.
dist.xml
All about distribution building.
doc.xml
Generators for the HTML documentation.
hudson.xml
Special build file for use on the integration server.
javadoc.xml
Driver build file to create module specific javadoc.
resources.xml
Resource preprocessing and bundling.
Eclipse IDE specific project files.
Container folder for shared libraries.
Project documentation sources.
tool
Build system and auditing tools.
audit
Auditing 3rd party libraries and Ant build files.
mockito
Mockito library as an example for the layout.
Folder that contains the mockito jars.
tool.xml
Tool description file (mandatory).
ant.xml
Ant build file for import in another build file (optional).
More auditing libraries.
build
Build system libraries.
All the build system libraries, same structure as the audit tools.

Common Build Commands

For a list of all available build commands check out the generated target list in the Build Environment page.

The most important commands you will want to use in day to day use are:

build check Performs a full build and runs the most important auditing tasks.
Use this command prior to checking in your changes and make sure there are no errors!
build check.report Opens your webbrowser with the auditing reports generated after a build.check.
Use this command to check the detail messages of errors.
build world Performs a full build including all auditing reports, the distribution and just about everything that can be built.

Always use the bundled build script to invoke build commands instead of your local version of ant in order to avoid conflicts!

On Windows use build.cmd <target> and on Unix / Mac OSX use ./build.sh <target>. Both scripts are stored in the toplevel folder of the project.