Building Tomcat 5.5 - Common bugs and how to fix them

If you're still working with Tomcat 5.5.x now that Tomcat 6.x has been released (and Tomcat 7 is on its way) and you don't have the time or resources right now to think about upgrading, finding the support you need is probably starting to get frustrating.  Here's some information on solving a few common Tomcat 5.5-related build issues all in one place, to help cut down the time you spend hunting for a solution.  

Tip: Tcat's live diagnostic feeds gives you fast, centralized insight into Tomcat 5.5 performance across your entire Tomcat infrastructure. Download Tcat now.

Tomcat 5.5 build issues

If you're working with a legacy system, you might run into some bugs while trying to build Tomcat 5.5.  Here are easy fixes for two common errors you might run into.

Ant 1.6.4 bug

If you try to build Tomcat 5.5 using Ant 1.6.4, you'll get an error, due to changes in this build that do not allow a directory to be moved onto another directory.  The error message will include something like this:

Cannot replace directory yourpath/jakarta-tomcat-5.5.9-src/jakarta-tomcat-5/Repository/tomcat-deps/src/java/org/apache/tomcat/dbcp

with directory yourpath/jakarta-tomcat-5/Repository/tomcat-deps/src/java/org/apache/commons

If you run into this bug, upgrade to the latest release of Ant and try the build again.

Tomcat 5.5 Sun JDK dependencies bug

If you try to build Tomcat 5.5 non-Sun JDK such as IBM JDK, you'll may run into some errors caused by missing Sun-specific SSL classes.  Tomcat 5.5 contains these dependencies to support JSSE 1.0 for users of pre-1.4 JVMs.  

Although upgrading to Tomcat 6.x fixes this bug, as the dependencies are no longer included, you don't need to upgrade or switch to a Sun JDK to get your build working.  You just need to download the missing classes.  Here's the fix:

  1. Download JSSE 1.0 from Sun's website and place it in an appropriate location.

  2. Change the jsse.home property in Tomcat's to indicate the directory where JSSE 1.0 is located.  

  3. Build Tomcat.

Building Tomcat 5.5 with eclipse

Although only the "Ant" method of building Tomcat 5.5 is officially supported by the development team, it is possible to build Tomcat in Eclipse and other IDEs, if you find this method a better fit for your needs.  Here's a guide to the extra legwork you'll have to do to compile Tomcat in an IDE.  

Before you pe in, you should take note that it isn't possible to eliminate Ant from the build process; these directions will simply allow you to complete the build with the support of IDE features, and ultimately run Tomcat within Eclipse.  These directions are specific to Eclipse, but you should be able to abstract them to work with your IDE of choice.

  1. Before you can build Tomcat in Eclipse, you still have to download all the Tomcat 5.5 repositories, install a JDK of version 1.4.x or later (you MUST use a JDK of that supports at least Java 5.0), and download, build, and install the latest distribution of Apache Ant, which will be used extensively during the build process.  For more information about where to download these components and moving them into place, visit the Apache Documentation site.
  2. Create a new project in Eclipse for your Tomcat build.  When you set up the project, make sure that you use ${tomcatSource} as the Workspace.
  3. Next, you need to create new Classpath variables to help Eclipse find the resources you'll need for your build.  Create the Classpath "TOMCAT_LIBS_BASE", and point it at the Tomcat binary dependencies base directory, as well as the ANT_HOME Classpath, which should point to the base directory of your Ant build.
  4. Building Tomcat in Eclipse is a matter of creating a separate Java project for each component you'll need to build, and then building them one by one.  You should have a separate project file for container, Tomcat connectors, jasper, and servletapi, and any additional binary repositories.  
  5. From here, proceed with the build as usual.  Make sure your compiler compliance is set to 5.0 or later, or connectors will fail to build.  If you created your projects correctly, Eclipse should be able to automatically read source tree and JAR locations from the .classpath/.project files contained in each project.