You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

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

   % svn checkout https://svn.apache.org/repos/asf/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

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