Building the source

Introduction

Ant is used to build the Restlet Framework, combined with a code pre-processor capable of customizing the master code branch for each edition and each distribution channel.

Downloading the source code

The Restlet Framework stores all its source code in this GitHub repository. You can get detailled instructions on how to setup a Git client like TortoiseGit on this page.

Note that you can download several versions of the source code. The most common one lives under the “master” branch. It contains the latest code developed and may be broken from time to time and even contain critical bugs: it’s the bleeding edge

Also, each released version lives in a dedicated branch such as “2.0” or “2.1”. A branch is used to maintain a publicly released version while working in parallel on a newer version (for example Restlet 1.2) in the trunk.

From now on, we will use “RESTLET_HOME” as a shortcut for the location of the downloaded the source code on your computer.

Installing Ant

In order to build the Java source code, generate the Javadocs and package the project for distribution, we rely on the popular Apache Ant tool. You need to install a recent version on your computer, ideally version 1.7 for the best experience. If you need assistance for this step, please follow the installation instructions provided by Ant.

After the installation, open a shell and enter “ant -version”. If this commands fails, you need to ensure that ant’s executable is declared in your path environment variable. If it succeeds, you should get something like:

ant -version
Apache Ant(TM) version 1.8.2 compiled on December 20 2010

Note that if you use a lower version of Ant, you need to follow some extra steps to install the optional JUnit task for Ant. See this page for details.

Building the source code

In the shell, change the current dir to “RESTLET_HOME”. Enter “ant -p” to display the list of main Ant targets available for the Restlet project. At the time of this writing, here was the result:

>ant -p
Buildfile: build.xml

Main targets:
 build                         Regenerate the source code and build the editions.
 build-current                 Build the editions with the current source code.
 clean                         Clean the staging area.
 clean-dist                    Clean distributions files.
 clean-temp                    Clean temporary build files.
 copy-eclipse                  Copy the generated artifacts to the project
 generate                      Regenerate the source code.
 generate-artifacts            Generates artifacts for the unique source code
 generate-libraries-manifests  Generates the manifest.mf files for the unique source code
 generate-manifests            Generates the manifest.mf files for the unique source code
 generate-misc                 Generates miscellaneous files.
 generate-modules-manifests    Generates the manifest.mf files for the unique source code
 generate-poms                 Generates the pom files for the unique source code
 prepare-stage-maven           Prepare the generation of the maven distributions.
 rebuild                       Clean the temp files, regenerate the source code and build the editions.
 regenerate                    Clean and regenerate the source code.
Default target: build

The build uses configuration variables located in ‘build.properties’. This file contains the default value and shouldn’t be locally modified as it is save in the Git repository. If you need to customize it, you should create a ‘custom.properties’ file following the same format that will be detected by the build and will override the default values.