This guide explains how to get the Roller source code, build it with Maven, test it with Maven and run it via Maven, Jetty and Derby (recommended for development test purposes only). This build build applies to the current Roller trunk. Roller 5.1 requires JDK 1.7 or newer; Roller 5.0.x requires just JDK 1.6.

Eclipse users, you might wish to refer to this instead: Build and Run Roller 5 in Eclipse

Building and deploying Roller from source

Build and deploying Roller from source involves three simple steps: get the source, run the build script, follow the installation instructions above to deploy the results.

Get the Roller source code

Read the instructions on Roller Source Code Access to find out how to get the source packages for a release or to get the latest source code directly from the source repository.

Example: get very latest Roller source into a directory called roller_trunk

There are two ways to get the source code, from the project's Git repository or from a source release. Here's how to get the Roller code directly from the Git repo:

   git clone http://git-wip-us

   % svn checkout https://svn.apache.org/repos/asf/incubator/roller roller/trunk roller_trunk

After you are done getting the source code, you can return here and move on to Step 2.

Run the build

Once you have extracted the Roller source code into a directory on your system, then open up a command prompt and cd to that directory. Set the environment variable JAVA_HOME to point to your JDK and then build Roller by using either the UNIX or Windows version of the build script. This script sets up the right classpath and calls Roller's Ant build script build.xml. The build shell script invokes the Ant that is in the tools subdirectory that comes with the Roller Subversion tree (or from extracting the tools file you downloaded). If you like to drive Ant from your IDE, you should set up to use the same Ant jar and classpath that is used by the shell script.

On UNIX:

   % chmod +x build.sh
   % build.sh all

On Windows:

   C> build all

This will build Roller and will stage the Roller web application into the build/roller subdirectory.

The build subdirectory can be removed for a clean build by specifying the Ant target clean. Examine the build.xml file for additional targets.

Deploy

You can simply copy the build/roller to your tomcat/webapps directory and follow the InstallationGuide to complete your deployment.

If you have problems making a build then please consult with the experts on the roller-dev mailing list. Somebody has probably encountered the very same problems that you are encountering.

After you have deployed Roller at least once manually, if you plan to do continued development, you will probably want to set up ant-based deployment to your test environment.

Running Unit Tests

Currently, unit tests run using mock contexts and use HSQLDB for the test database. They do not require actual container deployment, and can be run as soon as you have completed a full build. To run the tests, use the Ant target "tests". Using the build script this is invoked by running

   % build.sh tests

or

   C> build tests

This will leave HTML test reports in files in directories under build/reports.

The ant target clean-tests will remove test build artifacts, test results, and the reports.

Running unit tests in the Netbeans debugger

You can also run individual JUnit tests within your IDE. There are also two test suite's you can run: org.roller.business.TestAll for the Roller backend and org.roller.presentation.TestAll for the Roller backend.

You should have no problem running the 'tests' Ant target within Netbeans, but if you want to run individual tests some additional setup is required (TBD: document changes, if any, to project.xml)

Running unit tests in the Eclipse debugger

The same goes for Eclipse. You can easily run individual unit tests in the Eclipse debugger, just make sure you include the build/tests directory in the debug classpath. See the notes below for setting up the Roller build's built-in HSQLDB database to test against.

The Roller build's built-in HSQLDB database

If you run the 'tests' target, the Roller build script starts an HSQLDB database, creates the Roller database tables, runs the tests and then stops the database. If you want to run individual tests from within an IDE (for example), you'll need to: start and init the database before you run the tests and stop it when you're done. Use these Ant targets to do that:

• start-hsqldb: start the HSQLDB database (you should background it or run it in a separate window).
• init-hsqldb: drop and create all of the Roller tables (assumes HSQLDB is running)
• stop-hsqldb: stop the HSQLDB database

Ant-based Deployment

There are some Ant targets to support the repeated deployment that occurs for developer testing. These are not intended to be used for production deployment. This section describes how to set up the deploy-tomcat target.

Using the deploy-tomcat target

The deploy-tomcat target will copy the webapp files from your build staging directory to the webapps subdirectory of your Tomcat catalina.home. It does not set up the Tomcat context (e.g. roller.xml) or server.xml files for you. You must do this once manually.
To setup to use the deploy-tomcat target, perform the following steps:

1. Copy personal/sample.build.xml to personal/build.xml. You may wish to edit the deploy-tomcat target that is within that. For my needs, I was able to just use the sample version verbatim. This target gets invoked by the deploy-tomcat target that is in the top-level build.xml.
2. Edit the ant.properties file at the top-level of the Roller tree. Make sure that the following properties are defined:
   ;staging:The directory from which you wish to deploy. Generally the value of this should be "../build/roller"
   ;webapp.name:The deployed webapp name. Typically this value is "roller". If you change it, make sure the names in your context descriptor, and the filename of the context descriptor agree.
   ;catalina.home:Your catalina home directory. The Ant script assumes your web apps are deployed to webapps under this directory.

You should now be able to execute the deploy-tomcat Ant target that is in the top-level build.xml.

Create and maintain a customized build

The main Ant build file (build.xml) pulls in XML fragment files (.xmlf extension) from the custom subdirectory that can be modified to customize the build process. One technique of maintaining a custom build is to keep your own version of the custom subdirectory in your own revision control system.

To build Roller with your customizations, checkout the desired version of Roller, rename the custom directory to custom.orig, and create a symbolic link to your custom directory, as follows:

1. svn co $ROLLERSVN roller-2.1
2. cvs -d $YOURCVS co $YOURROLLERCUSTOM
3. cd roller-2.1
4. mv custom custom.orig
5. ln -s ../$YOURROLLERCUSTOM custom
6. ./build.sh rebuild

.git

Replace "http://" with "https://" in the above URLs if you are presently a Roller committer (i.e., have write access to Roller).:

If you are a GitHub user, you might find it easier to fork the Roller GitHub Repo: https://github.com/apache/roller.

Build Roller Weblogger

Here's how to build Roller Weblogger (also runs the unit tests).

   cd roller
   mvn clean install 

Run Roller Weblogger for development testing

Here's how to run the Jetty servlet engine, Derby and Roller for development testing of Roller:

   cd roller/app
   mvn jetty:run

Then use your web browser to browse to http://localhost:8080/roller to test Roller. You will find the log files in roller_trunk/app/target/work. You can adjust logging levels via the Roller properties override file at roller_trunk/app/src/test/resources/roller-jettyrun.properties. Note the blog information stored during each mvn jetty:run session will be lost once you stop Jetty (i.e., each mvn jetty:run starts with empty Roller database tables), however deploying Roller this way allows for hot (real-time) deployment of your JSP and CSS/JavaScript to the running application.

Build a Roller Weblogger release package

After running mvn clean install from from roller_trunk, navigate to its assembly-release subfolder and run mvn clean install again.

Other resources

Check the Roller Install guide for instructions on deploying Roller to Tomcat and other web servers. Unlike mvn jetty:run above, these deployments will persist data to non-temporary databases so you don't have to start from scratch with each run.

The Roller team is also starting to use Selenium to automate in-browser testings (using just Firefox presently), mvn clean install from the Roller it-selenium folder will activate the Roller Selenium tests.

Check this page's child pages for development within IntelliJ IDEA and Eclipse, as well as how to do code tracing in IDEA while running Roller via mvn jetty:run.This technique has been used to make changes to JSPs, velocity macros, themes, images, and "small bits" of code. The .xmlf files in the default custom directory provide examples of customizations you can use. (Note: You'll need a solid understanding of Apache Ant to make these kind of changes.)