Page History

[{TableOfContents title=' '}]

h2
h1. 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.

h3. Contents
* [1] Get the Roller source code
* [2] Run the build
* [3] Deploy

h3. Other build options
* [4] Unit tests
* [5] Ant based deployment
* [6] Create and maintain a customized build

\\
!! Get the Roller source code [#1]

Read the instructions on [Roller Source Code Access|RollerSourceCodeAccess] 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
{{{noformat}
   % svn checkout https://svn.apache.org/repos/asf/incubator/roller roller/trunk roller_trunk
}}{noformat}

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


!!h3. Run the build [#2]

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:
{{{noformat}
   % chmod +x build.sh
   % build.sh all
}}{noformat}

   On Windows:
{{{noformat}
   C> build all
}}{noformat}

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. 


!!h3. Deploy [#3]

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|RollerMailingLists]. 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 [5].


!!h3. Running Unit Tests [#4]

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

{{{noformat}
   % build.sh tests
}}{noformat}

or

{{{noformat}
   C> build tests
}{noformat}}

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.

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

!h5. 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.

!h5. 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

!!h3. Ant-based Deployment [#5]

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.

!h5. 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:

# 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.
# 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}}. 



!!h3. Create and maintain a customized build [#6]

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