How to build the project from scratch

1. Downloading the source code

The Restlet project stores all its source code in a Subversion repository hosted by the Tigris.org web site. You can get detailled instructions on how to setup a SVN client like Tortoise SVN on this page.

Note that you can download several versions of the source code. The most common one lives under the "/trunk" directory in the Restlet SVN repository. It contains the latest code developped and may be broken from time to time and even contain critical bugs, it's the bleeding edge

Also, each released version is tagged in the repository for archival purpose. They are available under the "/tags" directory, for example "/tags/1.0b19/" contains a full snapshot of the project when the version 1.0 beta 19 was released!

Finally, there is a "/branch" directory that will contain branches of the code in the future. A branch is used to maintain a publicly released version (for example Restlet 1.0) while working in parallel on a newer version (for example Restlet 1.1) 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.

2. 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 version 1.7.0RC1 compiled on November 5 2006

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.

3. 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:

 all         Full build
 archive     Archive the content of the project
 clean       Clean up the classes and Javadoc
 compile     Compile the Java source files
 generate    Generate template-based files
 javadoc     Generate the Javadoc
 package     Generate the distribution
 retroweave  Backport classes using Retroweaver
 test        Execute the test suites
Default target: all

Knowing the available targets is useful when you want to regenerate only the Javadocs or only pass the unit tests for example. To remove all the generated files you can simply enter "ant clean".

At this point, you should have a look at the "%RESTLET_HOME%/build.properties" file. It contains many parameters, like compiler flags, that you might want to modify in order to customize the build process. This is also the place to look for if you want to backport a build to JDK 1.4 using the Retroweaver tool.

Now, let's do a full build by simply entering "ant" in your shell. You should see some indication of the progress of the build displayed, and at the end a message like this one:

"BUILD SUCCESSFUL
Total time: 1 minute 0 seconds

Congratulations! You can now have a look at the two directories that were created. "%RESTLET_HOME%/build/" contains all the compiled classes and the traces of the unit tests. "%RESTLET_HOME%/dist/" contains the packaged distribution in a directory named after the current version. An archive of the distribution is also available. This is the file that you usually download from the Restlet web site.

-- Main.jlouvel - 10 Dec 2006