Building And Developing Railo For Testing

By Sean Corfield
Expert Author
Article Date: 2009-06-25

As of today, you can easily build your very own version of Railo from the latest source code in Subversion! This blog post will take you through all the steps necessary to download, build and deploy a new copy of Railo for your own testing, experimentation and general edification.

What you need

In order to build and test Railo from source, you're going to need the following:

Eclipse for JEE - this is the easiest Eclipse bundle to work with when building Java projects
Java 5 JDK - not just the JRE (because you're going to be compiling Java code)
A Subversion client - any client will do but we're only going to do a single checkout so even command line will be sufficient, although if you're using Eclipse, you're probably using Subclipse or some other SVN plugin
A running Railo installation in which to test your new patch file

I'm going to assume you can figure the above out (if not, you probably wouldn't want to try building a large Java application from source anyway!).

Getting started

Getting the latest Railo source code is as simple as:

svn checkout http://anonsvn.jboss.org/repos/railo

This will take a little while - it has to check out about 9,000 files. If you don't like the command line, use another client (but the command line will be way faster).

You should now have a railo folder containing branches, tags and trunk. For now, we're only interested in the trunk which is where the latest code approved by the core engineering team will live. In future, you might be interested in one of the branches which will be where experimental code will live for each new version of Railo.

Setting up Eclipse

Make sure the Java 5 JDK is one of the installed JREs for Eclipse: under Eclipse > Preferences..., go to Java > Installed JREs and, if necessary, Add... the Java 5 JDK. To make life easier, check the "JVM JDK5" option in the list of JREs so that it is automatically added to the build path of new Java projects.

We're now going to import four projects into Eclipse from the newly checked out source code tree. In Eclipse, switch to the Java or JEE perspective (because it'll make life easier) and then select File > Import... and then General > Existing Projects into Workspace and click Next >. For the root directory, Browse... to railo/trunk/railo-java/railo and Choose that folder. It should show a project called Railo. Click Finish. You'll have a new project in the Package Explorer and it'll have a little red 'x' indicating errors in it. Don't worry about that yet.

Repeat the import process for railo/trunk/railo-java/railo-core, railo/trunk/railo-java/railo-loader and railo/trunk/railo-java/railo-master.

You should now have four projects: Railo, Railo Source (from railo-master), Railo-Core and Railo-Loader.

Now we are going to correct the build paths for Railo-Core and Railo-Loader.

Right-click on Railo-Core and select Build Path > Configure Build Path.... Click the Libraries tab and you'll see a long list of JAR files with a red 'x' next to them (and a warning saying 80 build path entries are missing). Select all of the JAR files (be careful not to select the JRE System Library at the bottom!) and click Remove. Now we'll re-add those from the correct place. Click Add External JARs... and navigate to railo/trunk/railo-java/libs then select all of the JAR files and click Open. You should now see the Libraries tab with about 80 JAR files listed and no warnings or red 'x' markers. Click OK. Eclipse will probably then busy itself building your workspace.

Repeat this same process for the Railo-Loader project. Again, Eclipse will probably get busy building your workspace.

At this point, if Eclipse did build your workspace, your Railo-Core and Railo-Loader projects should no longer have a red 'x' - but they will have a yellow '!' marker next to them. Do not panic.

Note: If you did accidentally remove the JRE System Library, you can add it back by clicking Add Library... then selecting JRE System Library and Next > and choosing the JVM JDK5 option.

Setting your build version

In order to set the Railo build / patch level, you need to edit two files:

Railo-Core > build.properties
Railo-Core > railo.runtime > Info.java

The build.properties file determines the name of the .rc patch file we will build. Change core.version to a higher unique patch number. It was 3.1.0.016 when I checked it out of SVN so I set it to 3.1.0.116 so I won't get it confused with a regular patch from Railo.

In Info.java, look for the patches variable. It's around line 538 at the moment and probably looks like:

private static int patches=12;

(with major=3, minor=1 and releases=0). Modify it to match your chosen core.version patch number (e.g., 116).

As you modify Railo and make new builds, you may want to increase this number to keep track of which patch level you are working with (and make it easier to rollback patches).

Building Railo

Open up the Railo Source project and run the ant script there: right-click build.xml and select Run As > Ant Build. Depending on the speed of your machine, after about 20-30 seconds, it'll be done and you should see BUILD SUCCESSFUL in the Console panel that opened up when you ran the build script.

Now right-click the Railo project and select Refresh. The red 'x' should go away and you should see build and core folders inside that project. Open the core folder and you should see 3.1.0.116.rc. That's your new patch file. Yay!

Deploying your own build

Copy the newly created 3.1.0.116.rc file from the Railo project's core folder to the lib/railo-server/patches folder in your current Railo installation. You have to have started Railo at least once for this folder to exist (hence I said you need a running Railo installation to test your build!). Restart your Railo server and browse to the default index.cfm or the Administrator. The index.cfm page should show server.railo.version as 3.1.0.116. Logging into the Administrator, the Overview page should also show the version as 3.1.0.116.

Congratulations! You've built, deployed and tested your very own custom build of Railo!

If you fix a bug or add an enhancement, you can submit a patch (diff) of the changed files along with the issue you log in JIRA which will enable the core team to evaluate and, if appropriate, incorporate your changes in a future build of Railo.

As a final note, the source of the Administrator is in railo/trunk/railo-cfml and this is not yet part of the standard build process. We will be addressing this in the next few days, which will allow you to start modifying the Administrator itself (and deploying it as part of the build/patch process) - something I know several people are just itching to do!

Comments

About the Author:
Sean is currently Chief Technology Officer for Railo Technologies US. He has worked in IT for over twenty five years, starting out writing database systems and compilers then moving into mobile telecoms and finally into web development in 1997. Along the way, he worked on the ISO and ANSI C++ Standards committees for eight years and is a staunch advocate of software standards and best practice. Sean has championed and contributed to a number of CFML frameworks and was lead developer on Fusebox for two years.