Updated for build 3.1.0.020 and later!
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) - and not Java 6! Railo requires Java 5 to build correctly!
- 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 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
. 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...
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
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 this file:
- Railo-Core > railo.runtime > Info.ini
file determines the name of the .rc
patch file we will build. Change number=
to a unique patch number so it won't get confused with a regular patch from Railo. It was 3.1.0.020 when I checked it out of SVN so I set it to 188.8.131.52 so I won't get it confused with a regular patch from Railo.
(previously you edited two files: Info.java and the build.properties file to set the patch number)
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).
In order to build the Railo Administrator, you need to do the following:
- Create a Railo web context based on the railo/trunk/railo-cfml directory (which contains compileAdmin.cfm).
- Start Railo and log into the Web Administrator for that context (to set a password).
- Edit Railo-Core > build.properties to set railo.url= to the URL of compileAdmin.cfm in that new web context
I added a local /etc/hosts
definition for railo.builder
pointing to 127.0.0.1 and, since I'm using Tomcat, added a Host / Context for that domain pointed to /Developer/workspace-new/Railo-Project/railo-cfml/
. Then I set railo.url=
Open up the Railo Source project and run the ant script there: right-click build.xml
and select Run As > Ant Build
. In the middle of the build, it will prompt you for the Web Administrator password for the web context that you created (containing compileAdmin.cfm
). 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-Core project and select Refresh
. The red 'x' should go away and you should see build
folders inside that project. Open the dist
folder and you should see 184.108.40.206.rc
. That's your new patch file. Yay!
(previously the .rc file was built into the Railo project under a core folder)
Deploying your own build
Copy the newly created 220.127.116.11.rc
file from the Railo-Core project's dist
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
. Logging into the Administrator, the Overview page should also show the version as 18.104.22.168.
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.
The Railo Administrator is now an automatic part of the build! (this was not the case for 3.1.0.016)