[Cocoon Wiki] New: HowToBuildAndDeployCocoonWithMaven

[do...@cocoon.apache.org]

   Date: 2004-11-30T10:14:41
   Editor: EricJacob <er...@bell.ca>
   Wiki: Cocoon Wiki
   Page: HowToBuildAndDeployCocoonWithMaven
   URL: http://wiki.apache.org/cocoon/HowToBuildAndDeployCocoonWithMaven

   no comment

New Page:

= Purpose =

This how-to explains how to integrate [http://maven.apache.org/ Maven] with the [http://cocoon.apache.org/ Cocoon] project. An example for building a minimal webapp is provided for each option and the end of this document.


= Prerequisites =

 * You must be familiar with the Cocoon's Self:BuildSystem;
 * '''Maven must be installed on your system.''' For instructions on how to download and install Maven, follow this link: http://maven.apache.org/start/install.html


= Integrate Maven with Cocoon =

There is really only one step to integrate Maven with a project: the creation of a project descriptor. You may also create an ancillar ''maven.xml'' file which contains project specific goals, preGoals, and postGoals.

If you are using Maven for the first time or starting a new project you can use the [http://maven.apache.org/reference/user-guide.html#Starting_a_New_Project GenApp plug-in] to automate the creation of a Maven project tree.

''maven -Dpackage=com.mycompany.app genapp''

I'll present two approaches that were discussed on the user mailing list [http://marc.theaimsgroup.com/?t=110114687600005&r=1&w=2].


== Option 1 (the hard way...) ==

This option is the one I used to use before discovering Ralph's method (option 2). It consists mainly in manually tracking all the Cocoon's JARs and putting them into your Maven repository. Here the steps:

 1. Build Cocoon with only the desired properties and blocks (as explained in INSTALL.txt) by typing ''build war'' or ''./build.sh war'';
 1. Move all the generated JARs (build/webapp/WEB-INF/lib) into your Maven repository;
 1. Copy the generated Cocoon webapp folder (build/webapp) to your project source directory (e.g. projectA/src/webapp), except the JARs;
 1. Add the JARs dependencies to your Maven project;
 1. Build Cocoon by typing ''build war'' or ''./build.sh war''. It will download the dependencies into your local repository and create a WAR file.

The drawback of this solution is the need to upgrade all the Cocoon blocks and dependencies with each release (It could be a real pain, believe me!). Ralph's approach solves this problem.


== Option 2 (recommended) ==

 1. Build Cocoon with only the desired properties and blocks (as explained in INSTALL.txt) by typing ''build war'' or ''./build.sh war'';
 1. Copy the generated WAR (build/cocoon-2.1.6/cocoon.war) into your Maven repository (you may want to rename it, for example cocoon-2.1.6.war);
 1. Add the WAR dependency to your Maven project descriptor;
 1. In maven.xml, add a preGoal element containing an unwar instruction for expending the specified WAR;
 1. Build Cocoon by typing ''build war'' or ''./build.sh war''. It will extract the Cocoon WAR into your build directory, add your stuff and create another WAR file.

Note that this means that the vast majority of the JARs you will be using will be brought in via the Cocoon WAR file, dramatically reducing the number of dependencies that have to be changed with each Cocoon update.


= Use the examples =

'''Option 1:'''
 * Extract the zipped file in the location of your choice;
 * Do steps 1 and 2 (I’ve included a local.blocks.properties and local.build.properties). Steps 3 and 4 are done for you ?;
 * Finally, do step 5.

'''Option 2:'''
 * Extract the zipped file in the location of your choice;
 * Do step 2 using the provided cocoon-2.1.6-minimal.war (or build your own, using the included local.blocks.properties and local.build.properties);
 * Finally, do step 5.

<!> '''Note:''' If you use the Tomcat plug-in, start Tomcat then type ''maven tomcat:deploy''.


= Useful links =

 * The Cocoon 2.1 Build System: Self:BuildSystem
 * Maven: [http://maven.apache.org/]
 * maven-proxy: [http://maven-proxy.codehaus.org/]
 * maven-tomcat-plugin: [http://www.codeczar.com/products/maven-tomcat-plugin/]


Eric Jacob