How to debug tomcat source code?

The procedure is a bit involved, but what we do is the following:

-download tomcat sources and extract

-the actual source is spread throughout many different directories, collect them all into a single directory (you’ll end up with a javax.servlet.* and a org.apache.* if you do this often you may wish to create a script for doing this)

-create a new webproject and copy the merged tomcat sources to it
You’ll notice a lot of unmet dependencies. This doesn’t matter as JDT is still able to do its work. If you wish you can satisfy these depencies by copying libs like commons-collections, commons-logigng etc to this project’s path.

-jar both the sources and compiled classes. In my project I have an ant file in a directory tomcat5.5.17/build_libs, where tomcat5.5.17 is the name of my project. E.g.

<project name="tomcat" default="doTomcat" basedir="../." >
    
  
  <property name="buildDir"                 value="build_libs"                     />
  <property name="binSourceDir"             value="WebRoot/WEB-INF/classes/"    />  
  <property name="srcSourceDir"             value="src/"                        /> 
    
  <target name="doTomcat" >
      <jar destfile="${buildDir}/tomcat_5_5_17.jar"  basedir="${binSourceDir}"
          includes="javax/servlet/** org/apache/**"
      >      
        
    </jar>
    
    <jar destfile="${buildDir}/tomcat_5_5_17_src.jar"  basedir="${srcSourceDir}"
          includes="javax/servlet/** org/apache/**"
      >      
    </jar>  
          
      <eclipse.refreshLocal resource="tomcat5.5.17/${buildDir}" depth="infinite"/>
                
  </target>
  
</project>

– in the project where you wish to step into tomcat’s source code, create a directory -outside- of your web root, e.g. [project root]/ext_src (it must be created outside the web root so it doesn’t get deployed).

– copy the tomcat_5_5_17.jar and tomcat_5_5_17_src.jar to this new directory.

– in your project settings, add ext_src/tomcat_5_5_17.jar to your Java build path.

– while the Java build path dialog is still open, unfold the jar you just added and do a source attachment to the tomcat_5_5_17_src.jar.

– you may wish to close the other project where you generated the jars.

You can now step into the majority of the tomcat source code from your own code. For a few classes the MyEclipse J2EE 1.4 library container still takes precedence when debugging, notably javax.servlet.jar. Sometimes it helps to attach the tomcat_5_5_17_src.jar to this, but MyEclipse is quite picky on this.

The final missing link is stepping through the actual Java source code that Tomcat generates for JSP pages. With MyEclipse you can step through the JSP (jsr 45), but not through its servlet ‘peer’ code. Especially when you’re doing in-depth tag lib development this is often a requirement.

Nevertheless, with the method I outlined above you can step through 99% of Tomcat’s source code. This has been of great help to us in tracking down some particular nasty behavioural bugs.