Barracuda - Building and Deploying Barracuda
barracuda.gif (11357 bytes)The purpose of this document is to describe how to install the Barracuda project.

Building Barracuda

Barracuda is built using Ant 1.5.1+. The following are the basic steps required to build Barracuda as of version 1.2.0...

  1. install your preferred JDK. Barracuda has been tested to compile under both JDK1.3.x and j2sdk1.4.x
  2. download and install the latest release version of Ant
  3. obtain Barracuda via CVS or via the downloads directory at barracudamvc.org and make sure the distribution is expanded to some directory on your file system
  4. if you plan to run the JUnit tests, you need to do 2 things:
    1. copy the JUnit jar file located in Barracuda/WEB-INF/jars to ANT_HOME/lib
    2. copy the Xalan jar file located in Barracuda/WEB-INF/jars to one of the following locations...
      • JAVA_HOME/jre/lib/endorsed, if you use j2sdk1.4.x. (you should do this whether you plan to run JUnit tests or not to override j2sdk1.4.x's buggy version of Xalan)
      • ANT_HOME/lib, if you use JDK1.3.x

You are all set to start building Barracuda. The Barracuda distribution (and CVS, likewise) contain all required dependencies...other than stuff like JAXP and Xerces2 which already come with packages such as Ant and Tomcat

To actually run the build, open a command console, cd to Barracuda/src, and type "ant" to run the default build target (currently the "install" target). Or, if you are a windows type, you can simply double click WEB-INF/bin/ant_0_install.bat. Running the install task simply copies all the jars from lib-cvs in to lib.

To view available targets and information about those targets, type "ant -projecthelp". Here's a brief list of common tasks:

  • ant install - [DEFAULT] copies the jar files from /lib-cvs to /lib and creates needed files from samples.* if they don't already exist. Cycle the webapp and you're good to go
  • ant clean - cleans all compiled class. Does NOT nuke any files installed from samples.
  • ant superclean - just like clean, but cleaner: it DOES nuke files installed from samples (subsequent install will restore fresh copies)
  • ant taskdefs - build the custom Barracuda taskdefs
  • ant compile compile.test - compiles all source code (including test cases)
  • ant test - runs the unit tests
  • ant jars - rebuilds the jar files [note that the jar files are stored under cvs, so you don't need to do this when you download Barracuda; you can simply install]
  • ant jars.master - same as above, except that it will also create one master barracuda.jar (so you don't have to mess with a handful of individual ones) . 
  • ant javadoc - generate the javadocs

Deploying Barracuda

The Barracuda project is a Webapp - it can be deployed under any Servlet container claiming to support Servlet 2.2+. Extended functionality is available under Servlet 2.3+ and I recommend using a Servlet 2.3 container such as Tomcat 4.1.xx or even a Servlet 2.4 container such as Tomcat 5.x.xx. The following are the basic steps required to deploy Barracuda as of version 1.2.0 (and assumes you've followed the steps above for building Barracuda)...

  1. download and run the latest release version of Tomcat
  2. You can deploy Barracuda to Tomcat in one of a 3 ways:

    OPT 1 - rename WEB-INF/ccf.xml to Barracuda.xml and move this file to either 

    • a) CATALINA_HOME/webapps (Tomcat 4.1) -OR-
    • b) CATALINA_HOME/conf/Catalina/localhost (Tomcat 5.x)

    OPT 2 - alternately, you may generate a .war file using "ant war" and copy the .war file into the directories specified above in the first option

    OPT 3 - use the Catalina Ant manager tasks which use the Ant build to deploy Barracuda. This involves a number of initial steps to set up, but is recommended because it makes things much more flexible and convenient...

    1. configure manager application access
    2. create a file called ".build.properties" in USER_HOME. For example, here is my path to USER_HOME under Win2k: "C:\Documents and Settings\jkjome". Note that under Windows, you will have to use the command line to create this file because Windows Explorer won't allow the creation of files prefixed with non-alphnumeric characters. This file will override Barracuda's local Barracuda/src/build.properties file when running Ant. Add the username/password combo you configured in the last step to the properties "manager.username" and "manager.password", respectively, in the ".build.properties" file.
    3. Make sure Tomcat has been restarted since the time your performed step #1

    You can now cd to Barracuda/src and type "ant catalina-install". This will install the Barracuda webapp into Tomcat's memory. Access it at http://localhost:8080/Barracuda. You can access the GUI for the manager app by visiting http://localhost:8080/manager/html/list

    There are actually a few ways to install/deploy Barracuda to Tomcat as well as manipulate the running context and query it for information. Certain tasks are paired and shouldn't be intermixed (catalina-install/catalina-remove and catalina-deploy/catalina-undeploy). Here are the Catalina Ant Manager targets (named for their tasks) and descriptions of their functionality...

    • catalina-install/catalina-remove - These targets install and remove a context. An install is not persistent across server restarts. The context is installed from wherever it sits on the file system. Nothing is uploaded to Tomcat. These targets are nice to use for testing or demo'ing.
    • catalina-deploy/catalina-undeploy - These targets deploy and undeploy a context. A deploy is persistent across server restarts. The context is uploaded to Tomcat in a .war archive. In fact, the context is served directly out of the .war archive instead of off the filesystem. Additionally, Tomcat's server.xml will be rewritten to record the context's existence and, thus, provide persistence across server restarts. This is a more heavyweight way to deploy webapps, but necessary for production deployment.
    • catalina-reload - This target reloads the context and can be used no matter the method used to install/deploy the webapp. Note that changes to the web.xml will not be picked up using this target, but classes will be reloaded.
    • catalina-start/catalina-stop - Like the catalina-reload target, these targets can be used no matter the method used to install/deploy the webapp. Unlike catlina-reload, however, changes to the web.xml will be picked up in a start/stop cycle.
    • catalina-list - This target lists the current webapps installed/deployed currently on the server
    • catalina-roles - This target lists all available user roles, not just those of the current authenticated user. I don't use this much.
    • catalina-resources - list global JNDI resources of a particular fully qualified class. I don't use this much.

    Also available are a few convenience targets...

    • catalina-reinstall - calls catalina-remove, then catalina-install
    • catalina-redeploy - calls catalina-undeploy, then catalina-deploy
    • catalina-restart - calls catalina-stop, then catalina-start. Note that this is very similar to catalina-reload except that catalina-reload won't re-read the web.xml.
    For more information, see the Manager app howto and the HTML Manager app howto. Additionally, see the Barracuda contrib package howto for information about using the Catalina Ant Manager tasks in conjunction with the contri apps, making them a cinch to install/deploy under Tomcat.

Using Barracuda

To actually use Barracuda in your own projects, all you need to do is copy the appropriate jars into your webapp (and possibly your appserver). While there are a number of possibities (and the details may vary depending on you appserver), here's a typical setup for Tomcat 4.x/5.x:

First, run ant jars.master to generate a single unified barracuda.jar (or download it from the latest binary release). Next, put the following jars in these locations:

  • <tomcat-root-dir>
    • common/lib/log4j-1.2.8.jar
    • common/lib/log4j-sandbox-0.2alpha.jar
    • shared/lib/bcel-5.1.jar
    • shared/lib/gnu-regexp-1.1.4.jar
    • shared/lib/jivan-1.0rc2.jar
    • shared/lib/jtidy-r7-xmlc-2.2.4.jar
    • shared/lib/junit-3.8.1.jar
    • shared/lib/log4j-sandbox-0.2alpha.jar
    • shared/lib/xalan-2.5.2.jar
    • shared/lib/xmlc-all-runtime-2.2.4.jar
  • <my project>
    • WEB-INF/lib/barracuda.jar
      -or-
    • WEB-INF/lib/barracuda-core.jar
    • WEB-INF/lib/plankton.jar

That's all there is to it! Happy hacking! :-)


I hope that these instructions help to reduce confusion in using Barracuda! If you do run into anything that you don't understand, don't hesitate to ping the Barracuda list about your issue. --Jake

For all the latest information on Barracuda, please refer to barracudamvc.org
Questions, comments, feedback? Let us know...