Building Railo from Source

July 7, 2009 · 33 Comments

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 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 this file:

Railo-Core > railo.runtime > Info.ini

The 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 3.1.0.120 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= to http://railo.builder:8080/compileAdmin.cfm. Building Railo 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 and dist folders inside that project. Open the dist folder and you should see 3.1.0.120.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 3.1.0.120.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 as 3.1.0.120. Logging into the Administrator, the Overview page should also show the version as 3.1.0.120. 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)

View count: 1387

Tags: coldfusion · oss · railo

33 responses so far ↓

1 Peter Boughton // Jun 25, 2009 at 12:49 AM

Cool, looking forward to checking this out. :)

What does the extra 97MB of Eclipse for JEE give you that Eclipse for Java doesn't? (In that I have the latter, and would prefer to download any significant missing bits rather than a whole 189MB on a slow connection.)

Oh, and you have a typo in third paragraph of "Setting up Eclipse" section - says "rail-java" instead of "railo-java".
2 Sean Corfield // Jun 25, 2009 at 1:06 AM

@Peter, you should be able to build it with Eclipse for Java.

I prefer the JEE bundle because it provides a much more complete feature set for managing servers and building web applications etc. You can see the JEE feature list here (46 items):

http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/galileor

The Java bundle has only about a dozen of those features.

Thanx for spotting the typo - fixed!
3 Jake // Jun 25, 2009 at 5:44 AM

Can you post a quick explanation (and a real-world example)of what benefits this has? I understand what is happening, but not sure how it benefits me to build Railo from scratch.
4 Gert Franz // Jun 25, 2009 at 6:29 AM

One three quick notes:
1. The version number is important since Railo will look for patches online where the version number is higher as the number you are using currently. So if you set it to 3.1.0.116 and there's a patch online available that is for instance 3.1.0.018 then it won't detect it since the version number is smaller than your local one.

2. If you do not build the complete .rc file (including the admin files etc.) and you create a new web context, the necessary files won't be copied into the WEB-INF/railo directory. So you need to copy them from some other locations yet. But we will fix the build process quite soon so that everything is in place and that you have the resource files in there as well.

3. Several people asked me if it is possible to translate the admin into other languages. Well yes it is. Please create a directory called (in this example spanish): /es and in there copy the files from the /en folder. Then translate all the texts to spanish and send us the translated files.

Besides that, thanks a lot Sean for the post...

Gert
Railo Open Source
5 Adam Reid // Jun 25, 2009 at 7:10 AM

Beware JDK 1.6 - java.sql.ResultSet interface has added a new methods which are not implemented in Railo so stick to java 1.5

I should have followed the instructions! :)
6 Paul Kukiel // Jun 25, 2009 at 7:50 AM

These instructions were great! Worked without an issue. I did try with Java 6 aswell and it didn't work so make sure you are using Java 5.

http://twitpic.com/8dg6g

Now to see if I can remember how to do anything useful in java.
7 Robert Burns // Jun 25, 2009 at 8:06 AM

I believe on the "Import Existing Projects into Workspace" task, there is a checkbox "Copy projects into workspace" that needs to be unchecked. If checked the build process will error I believe, due to a relative path to the lib directory in the root of the trunk.
8 Sean Corfield // Jun 25, 2009 at 2:20 PM

@Robert, good point. It's always been unchecked in my Eclipse so I didn't think to mention it!

@Adam, @Paul, yes, perhaps I should have emphasized the need for Java 5 vs Java 6. I'll make sure that's in the official documentation version (which is why we did a blog post first!).

@Gert, good point on the version number. I figured it was safer to avoid a version collision or "accidental" update, especially since your custom .rc file can easily be removed to get back to an official build. Something we can clarify in the official documentation. As soon as we have the Administrator automatically built by ant, I'll do another blog post about that (because there are several things folks can do easily in the admin source code at that point!).

@Jake, I was asked that on Twitter as well. I'll do a blog post about it in the next day or two...
9 Peter Boughton // Jun 25, 2009 at 2:37 PM

Thanks Sean. The only problem with that page is that it doesn't tell me what they actually are (e.g. JST, Persistence, RSE).

For others... well datatools is redundant for me (I'm happy enough with MySQL at console, Use Putty for SSH/Telnet)

So it's hard to determine if there is a practical difference for myself.

Fortunately, I've just noticed that the package comparison page (link below) has hyperlinked each TLA, so it should be possible to figure out what they each are from there.
http://eclipse.org/downloads/packages/compare-packages
10 Adam Haskell // Jun 25, 2009 at 9:05 PM

While it does not do everything for folks, I uploaded a Team Project Set for Eclipse. It will at least expedite setting up the projects and configuring Eclipse for SVN.

More info and the download link are on my blog:

http://cfrant.blogspot.com/2009/06/railo-on-svn-and-team-project-sets.html
11 Peter Boughton // Jun 26, 2009 at 12:34 PM

My JRE System Library in the Libraries tab is listed as jre6.

How do I go about switching it to jdk5?

(which is at C:\Program Files\Java\jdk1.5.0_02)
12 Peter Boughton // Jun 26, 2009 at 12:38 PM

Ah, just found it: Add Library button, fourth down, then select 'JRE System Library' and follow the yellow brick road. :)
13 Peter Boughton // Jun 26, 2009 at 12:55 PM

A quick note:
I used Adam's Team Project Set to get going, but to build successfully I had to rename directory "Railo-libs" to just "libs", remove the ".project" file, and close/delete the Eclipse project (to prevent .project coming back).
14 Sean Corfield // Jun 26, 2009 at 3:39 PM

@Peter, yes, if you don't want to make JDK 5 the default (per my instructions under "Setting up Eclipse") you can do so via the Add Library build configuration, similar to what I described above for reinstating the JDK if you accidentally delete it from your list of libraries.

After some discussion internally we'll be adopting Railo-libs and using relative paths for Library build paths which will make this easier in future - and we'll be providing a Team Project Set based on Adam's contribution.
15 denny // Jun 27, 2009 at 3:12 PM

Thanks for the directions!

Since we're using an ant script, what about automagically setting the build suffix/patch level to the current date or some such? Just a thought.

Again, thanks,
and WOOHOO!
16 Sean Corfield // Jun 27, 2009 at 3:23 PM

@denny, yup, that's on my list of things to address. There should be just one place to set the version and the rest should be automatic.
17 Sean Corfield // Jul 9, 2009 at 11:49 AM

@denny, check out these updated instructions for 3.1.0.020 - the version number is set in just one place now.
18 denny // Jul 9, 2009 at 12:18 PM

@Sean you guys are rock'n!
19 Don // Jul 11, 2009 at 2:55 PM

Sean,

I have a few questions. a) On the 4th prerequisite of "A running Railo installation in which to test your new patch file", could we substitute that with railo source code for a new installation? Hence, there might be additional value for a customized railo installer. b) I'm not a java programmer would the process 'kill' me?

Thanks.

Don
20 Sean Corfield // Jul 12, 2009 at 12:52 AM

@Don, I don't understand what you mean by either a) or b). My instructions were very clear: you must have a live, running Railo install in order to run the compile/archive process.
21 Don // Jul 12, 2009 at 7:49 AM

Sean,

I'd like to be able to create a railo installer for Windows, so, if the 4th prerequisite can be substitute with source code then your method would be great for me. But you've just answered it, no.

Don
22 Sean Corfield // Jul 12, 2009 at 12:53 PM

@Don, an installer has nothing to do with the build process. You can create an installer without needing to build everything from source. Again, I don't understand what you mean. Can you explain why you think you need any part of this build process for a Windows installer?
23 Don // Jul 12, 2009 at 2:34 PM

Sean,

Thanks for the enlightening to compensate my lack of knowledge in the java space. I've just looked into the cacho resin installation doc a bit and tried a silly approach for the heck of it, copying an installation of railo from one machine to another (just all the direcotories and files), and then ran the install-service.bat batch file and railo becomes available at the target. So, it appears that railo is very flexible. However, the silly approach has a price to it, the extracted railo has about 250MB vs. the {railo_for_win}.exe has only 66MB footprint, so to bundle railto with the exe is definitely desirable for me. Why did I want to do it this way? I'm going to distribute my app and making it available to download as well. An issue with the current {railo_for_win}.exe for my case is that, it requires 3 munual steps for the installation, undertood normal for individual users, but I'd like railo to be silently installed like the install.properties file for cf8 installation. What are available options out there?

Once again many thanks.

Don
24 Sean Corfield // Jul 12, 2009 at 4:21 PM

@Don, sounds like you need to learn how to build a Windows installer. There are a lot of resources out there to help. Since I don't do Windows, you won't find any here :)
25 Don // Jul 12, 2009 at 6:27 PM

Thanks, Sean, I'll try. Just curious, do you happen to know who compiled the Railo for Windows download (railo-3.1.0.022-resin-with-jre-windows.exe)?

Don
26 Sean Corfield // Jul 12, 2009 at 7:13 PM

@Don, all of the packaged installers available on getrailo.org were built by core engineering in Railo Switzerland.
27 Don // Jul 13, 2009 at 8:37 AM

Sean,

Thank you for your kind note. I sent a similar request to Gert two days ago, heard he's on a trip...

Best,

Don
28 Mark // Aug 27, 2009 at 2:03 AM

Hi Sean trying to follow the build process you have defined above, have a small problwm in my lack of understanding when you state:

Create a Railo web context based on the railo/trunk/railo-cfml directory (which contains compileAdmin.cfm).

How is this done? do i just take that directory and copy the files and place them somewhere else?
29 Sean Corfield // Aug 27, 2009 at 8:04 AM

How you "Create a Railo web context" is going to depend on how you have your existing Railo installation setup. Essentially you need to tell Railo that the railo/trunk/railo-cfml directory is a webroot (of a new web application).

For example, if your running Railo instance is on Tomcat (and you have the custom multi-web configuration I blogged about), add a Host entry to server.xml designating railo/trunk/railo-cfml as the document root.

If you need help with setting up web contexts, ask on the Railo mailing list.
30 Mark // Oct 22, 2009 at 1:31 AM

Hi Sean I am building Railo from your blog but get a buld failure due to a missing class
railo.runtime.security.SerialNumber.java

It is being called from FDControllerImpl.java on line 19 but is not
present in the subversion checkout, it appears on further
investigation that this was last updated on September 08th 2009 for
the new release 3.1.1.005 but the file is missing from the update?

any suggestions?
31 Sean Corfield // Dec 11, 2009 at 9:10 AM

Also check out Mark Niland's recent blog post:

http://www.pixsdesign.co.uk/2009/12/build-railo-from-source/
32 Bilal // Oct 18, 2010 at 11:39 AM

Sean do you know which revision in the SVN is considered build-complete.
I have checked out several:
67, 68,70,101,105, and head
No luck, all head one or more missing classes or references (jars) . I was partially able to work around them, by removing classes, creating mock ones etc. but I am guessing that the goal is to have something we can download from svn and build from.
For example, I ran into the (X-CFXCPP) missing with the head revision.
Would be easier if we could identify in SVN which ones are intended for public use, i.e. commented with something like "complete build"?
33 Sean Corfield // Oct 18, 2010 at 7:52 PM

@Bilal, Railo has been on github for quite a while and SVN is not updated as regularly. You'll do better with the git version.

An Architect's View

CFML, Clojure, Software Design, Frameworks and more...