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).
Getting the Roller source code
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
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 Subversion repository or from a source release. Here's how to get the code from Subversion:
<code>
svn co
https://svn.apache.org/repos/asf/roller/trunk
...
...
Under the roller_trunk directory, here's how the code is layed out:
No Format |
---|
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:
No Format |
---|
% cd roller_trunk/apps/weblogger
% ant dist
|
On Windows:
No Format |
---|
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
No Format |
---|
% ant tests
|
or
No Format |
---|
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:
- svn co $ROLLERSVN roller-2.1
- cvs -d $YOURCVS co $YOURROLLERCUSTOM
- cd roller-2.1
- mv custom custom.orig
- ln -s ../$YOURROLLERCUSTOM custom
- ant clean dist
<code>
TBD: how to get and extract a source release
Building Roller Weblogger
Here's how to build Roller Weblogger (also runs the unit tests).
<code>
cd roller_trunk
mvn install
<code>
Running Roller Weblogger for development testing
Here's how to run the Jetty servlet engine, Derby and Roller for development testing of Roller:
<code>
cd roller_trunk/weblogger-web
mvn jetty:run-war
<code>
Then use your web browser to browse to http://localhost:8080/roller to test Roller. You will find the log files in roller_trunk/weblogger-web/target/work. You can adjust logging levels via the Roller properties override file at roller_trunk/weblogger-web/src/test/resources/roller-custom.properties.
Building a Roller Weblogger release package
Here's how to build a full Roller Weblogger release including both binary and source releases.
<code>
cd roller_trunk/web-assembly
mvn install
<code>
You'll find the release files in roller_trunk/web-assembly/target.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.)