(Applies to Roller 4.0)

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.

Before you get started

Make sure you have the Sun Java SE 5 JDK and Apache Ant installed on your system. Set the environment variable JAVA_HOME to point to your JDK directory.

Get the Roller source code

You can do this by downloading a source release from http://roller.apache.org/downloads/downloads.html or by getting source code from Subversion.

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

   % svn checkout https://svn.apache.org/repos/asf/roller/tags/roller_4.0.1 roller

Under the roller_trunk directory, here's how the code is layed out:

   apps/weblogger   - Roller Weblogger source code
   apps/planet      - Roller Planet source code
   components/core  - Roller "Core" or shared code
   tools            - Dependencies

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 into the Roller Weblogger directory. Run the Ant build script there.

If you don't have Ant then you can use the UNIX build.sh or Windows build.bat build script. It uses the version of Ant that is bundled with the Roller source. For example, to build Roller Weblogger:

On UNIX:

   % cd roller_trunk/apps/weblogger
   % ant dist

On Windows:

   C> cd roller_trunk\\apps\\weblogger
   C> ant dist

This will build Roller and will stage the Roller web application into the apps/weblogger/build/webapp 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

   % ant tests

or

   C> ant 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

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. ant clean dist

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.)

  • No labels