Cocoon and Eclipse

This page describes how to debug Cocoon in Eclipse (as at 31 May 2005 with BRANCH_2_1_X and Eclipse 3.0.2).

I use Eclipse configured with the Subclipse plugin to retrieve the Cocoon source code from Subversion.

Eclipse and Subclipse

This part describes how to obtain the latest (or any) revision of the Cocoon source code from the Subversion repository from within Eclipse, using Subclipse. Note that it is not necessary to do this in order to be able to debug Cocoon using Eclipse. You can debug Cocoon without having a Subversion working copy of it. To do that, see the section Eclipse, its workspace and how to import a project (under Older Material) and Running Cocoon Jetty from within Eclipse.


The following should work on Windows. [Please verify]

(Note: Yes, it worked. But you may want to make sure the path name on the Windows box does not get too long. Otherwise you might find that the javadoc task does not work because the gerated command line is getting too long. TorstenSchlabach)

To install the Subclipse plugin:

  1. In Eclipse, click Help -> Software Updates -> Find and Install...

  2. Choose "Search for new features to install".
  3. Click the "New Remote Site..." button.
  4. Enter "Subclipse" into the name field, and "" into the URL field. Click OK.

  5. Eclipse will contact the Subclipse site for available plugins. Select "Subclipse", "Version Control with Subversion" and click Next.
  6. Accept the terms of the agreement, and click "Finish".
  7. The plugins will probably not be signed. You will get warnings. Click "Install".
  8. If prompted, click to restart the Eclipse workbench.

Mac OS X

The above steps didn't work on my Mac OS X 10.3 Powerbook. Instead, I needed to rollback to Subclipse version 0.9.30 (instead of 0.9.31, the latest version at the time of writing). I also needed to install the Pure Java Subversion Client Library. My steps were:

  1. Visit the Subclipse Archive and download

  2. Unzip to my local hard drive.
  3. In Eclipse, click Help -> Software Updates -> Find and Install...

  4. Choose "Search for new features to install".
  5. Click the "New Local Site..." button.
  6. Enter "Subclipse (0.9.30 local)" into the name field, and select the folder you unzipped into. Click OK.
  7. Accept the terms of the agreement, and click "Finish".
  8. The plugins will probably not be signed. You will get warnings. Click "Install".
  9. If prompted, click to restart the Eclipse workbench.
  10. When Eclipse has restarted, click Help -> Software Updates -> Find and Install...

  11. Choose "Search for new features to install".
  12. Click the "New Remote Site..." button.
  13. Enter "Pure Java Subversion Client Library" into the name field, and "" into the URL field. Click OK.

  14. Eclipse will contact the Subclipse site for available plugins. Select "JavaSVN Library", "JavaSVN Subclipse Extension" and click Next.
  15. Accept the terms of the agreement, and click "Finish".
  16. The plugins will probably not be signed. You will get warnings. Click "Install".
  17. If prompted, click to restart the Eclipse workbench.

For more information about using Subclipse on different environments, visit

Checking out Cocoon BRANCH_2_1_X with Subclipse

Create a new repository:

  1. In Eclipse, click Window -> Open Perspective -> Other...

  2. Choose "SVN Repository Exploring" and click OK.
  3. In the SVN Repository view, right-click and select New -> Repository Location...

  4. Enter "" into the URL field.

  5. Click "Browse..." to choose "" as the Root URL.

  6. Leave the user and password fields blank.
  7. Click "Finish".

Note: Michael Straessle suggests here that SVN access from behind a firewall might be a problem. If this is the case, you should use instead (i.e. https://).

Check out the Cocoon BRANCH_2_1_X source code:

  1. From the SVN Repository view, expand "".

  2. Open the branches subfolder.
  3. Right-click on BRANCH_2_1_X, and choose "Check Out As...".
  4. Choose "Java Project from the Wizards box and click "Next".
  5. Enter BRANCH_2_1_X into the project name field.
  6. Click "Finish", and wait. Subclipse will take a long time to complete the checkout!

Note: Eclipse automatically detects source folders and adds them to your project (there is no need to run an Ant task to create an Eclipse project).

Eclipse and Ant

Building Cocoon with Eclipse's built-in Ant

To begin, we need to configure Ant to use the latest Xerces and Ant contrib JARs. We only need to do this once:

  1. In Eclipse, click Window -> Preferences, and choose Ant -> Runtime from the tree on the left of the dialog box.

  2. From within the Classpath tab, click on "Global Entries" and then click "Add JARs..."
  3. From your Cocoon project select tools/lib/ant-contrib-0.6.jar, lib/endorsed/xml-apis and lib/endorsed/xercesImpl-2.6.2.
  4. Click OK

Eclipse comes with Ant built-in. The Ant integration in Eclipse provides some nice features, such as an Eclipse view for build.xml files. Now we'll load Cocoon's Ant build file into the Eclipse Ant view:

  1. Make sure the Ant view is visible in your current Eclipse perspective. If not, choose Window -> Show View, and select Ant.

  2. Drag the build.xml from the Cocoon project root folder into the Ant view, and expand the tree. You should see many Ant targets, each marked with a green concentric circle.

To build Cocoon from within Eclipse:

  1. In the Ant view, double click the target you wish to build (e.g. "war", "webapp" etc.)
  2. Output from the build process should appear in Eclipse's Console window.

Note: All these targets (e.g. "war", "webapp" etc.) automatically invoke the init-tasks target mentioned below. There is no need to run the init-tasks target first, as described below.

Running Cocoon Jetty from within Eclipse

You can start cocoon from within Eclipse so you don't need the cli anymore. You simply configure Jetty as an application in Eclipse, build cocoon once (and the Eclipse project) and then invoke build eclipse-webapp-prepare that corrects the roles file and deletes all jars from within the WEB-INF/lib directory. That's it and you simply only use Eclipse from that point on.


Outside of Eclipse:

Eclipse Setup:

This will launch Jetty from within Eclipse and you'll see Jetty's output in the console of your debug perspective. Your application should run at http://localhost:8888/.

You can also debug Cocoon this way:

Note: this seems to be a quite inefficient way to debug Cocoon, it is much slower than remote debugging. May be did I overlook a setting? I'd suggest running Cocoon outside of Eclipse and using remote JVM debugging. See DebuggingCocoon. Note also that to run Cocoon outside of Eclipse, you'll need to rebuild the JARs you wiped away with 'build eclipse-webapp-prepare' from the WEB-INF\lib folder, so that Cocoon debugging and running Cocoon Jetty within Eclipse seem to conflict.

I tried this. I omitted the step

and it did not hurt. What is this good for?

Also I was unable to find this option:

so I ignored this. Did not hurt; it works anyway.

It might be worth having a look at the Tomcat plugins available for Eclipse. Maybe anything similar exists for Jetty as well.


Older Material (can it be deleted now?)

--- The stuff below may be deprecated as of 2.1.8-dev. It was definitely the way to go in 2.1.6. Maybe someone can take the time and test with 2.1.7. We should keep it around for people who need to stick to older releases for production support for a while.

Torsten Schlabach


The reson for that is that the Cocoon build process relies on external tasks in Ant (see: which are compiled on-the-fly during the Cocoon build process. So if you build Cocoon from the command line using either build.bat (Windows) or (*ix) here is what is happening internally:

One of the very first targets in the build process is the init-tasks target in the file tools/targets/init-build.xml. This target will compile the external Ant tasks

from the sources in tools/src/anttasks to tools/anttasks and make these external tasks known to Ant using <taskdef ...>.

Other targets further down the build process rely on these tasks obviously.

Eclipse, its workspace and how to import a project

As silly as it sounds, but picking up an already existing project in Eclipse is not alway straigt forward, mostly because Eclipse offers a lot of options. Most of them are misleading for what we want to achieve here. But they are sitting on the menus ready to lead you in the wrong direction. As this is not really a in-depth Eclipse internals tutorial, let's keep a long story short.

Eclipse keeps a .metadata directory in each workspace. In there it records the projects it knows about in the workspace. Therefore just extracting the Cocoon tarball into the Eclipse workspace will not make the project show up at all.

The next logical thought then would be to use the File -> Import option and select Existing Project into Workspace. This might work somehow, but it leaves the project where it is on the file system. In other words, this is not a means to copy the extracted Cocoon source tree from a temporary location where you unpacked it into your workspace. It rather is a means of referencing a project outside the workspace. If you rely on keeping things together in your workspace(s) this is not what you want, either.

The Cocoon build.xml file provides a target to create an Eclipse project (which means it will create the .project and .classpath files that Eclipse expects) but Eclipse does not know how about this target and will not call it no matter what import mechanism you use.

So the best way to make the Cocoon source tree available in Eclise is:


eclipse-cocoon-import-02.jpg eclipse-cocoon-import-03.jpg


Once you do that, note the information that shows up in the bottom of the dialogue. (It will only show up if you name the project identical to the folder!) Hit finish and you are done. Cocoon is now a project in your Eclipse Workbench using the correct settings from the .classpath and .project files.

Note: Eclipse considers it a feature that the project's name in the workspace can be different from the name on the file system. You can then refer to the project name instead of the filesystem name, for example when building project dependencies. But in Cocoon land this is causing more trouble than doing any good, therefore it is recommended to keep the project's name in the workspace and the directory name on the filesystem in sync.

At this point, depending on your hardware, you might notice a lot of activity going on. This is because of Eclipse's habit to compile a .java file as soon as it sees one. This is the default setting for a new project and we did not yet have a chance to change this. So either wait for it to finish (and ignore and warnings or errors) or interrupt the build process:

eclipse-cocoon-import-05.jpg eclipse-cocoon-import-06.jpg


Note: Wouldn't it be possible to set these settings in the .project file so the build does not even start at all?

Now you are finally ready to turn to the section about actually building Cocoon in Eclise!

Building Cocoon using Eclipse internal Ant

 broken at least for Cocoon versions => 2.1.5, see section above 

Here are the required steps:

For using CVS functionality provided by Eclipse you must do additional steps:

To run the Ant build from within Eclipse you have to add something like this to the build.xml:

  <!-- =========================================================== -->
  <!-- Use the Eclipse compiler if we are running in eclipse       -->
  <!-- =========================================================== -->

  <target name="properties" if="eclipse.running">
    <property name="build.compiler" value="org.eclipse.jdt.core.JDTCompilerAdapter"/>

Note: Cocoon build system uses Ant 1.6, so calling the Ant build from an older Eclipse without Ant 1.6 does not work. You need a recent 3.0 milestone build of Eclipse - or you know how to replace your Ant version in your older Eclipse.

I don't know where I should put that.


I discovered one problem with IBM's WSAD under Linux. In the .project file the <name>project-name</name> should be the same as the path. For instance:


Does this maybe relate to the section "Eclipse, its workspace ..."? Then it would on only be applicable to WSAD but any flavour of Eclipse.


Building Cocoon in Eclipse using Cocoon's packaged Ant

Note: This is kind of a workaround and it has not yet been fully researched what implications this approach has on the Eclipse way of doing things (especially on-the-fly compiling, automatic reloading of web applications what using a Tomcat plugin and the like). In fact what is described here is little more than a more convenient way of just browsing and editing the Cocoon source tree in Eclipse but keeping a command line window open to trigger the build from there. One important feature of this "external tools" approach is that Eclipse will do a refresh of the project after a build - if you don't forget to configure it!

We assume $ECLIPSE_WORKSPACE is your Eclipse workspace here.

Here are the required steps:




Note: This again is something very eclipsy: Probably for performance reasons Eclipse has a very strong caching of file system contents and is heavily relying on the assumption that during development all changes to the file system will happen through the Eclipse workbench itself, either by the user editing or the compiler building any output files. As the external Ant build breaks this assumption the refresh is needed to make sure Eclipse is in synch again after the build.

LoadInEclipse (last edited 2009-09-20 23:41:29 by localhost)