

                      *-----------------------------*
                      |     I  N  S  T  A  L  L     |
                      *-----------------------------*


  You have downloaded the source distribution of Cocoon and you don't like 
  to read verbose docs, right?
  
  Great, this file is for you.
  
 
 1) Have your Servlet 2.2 compatible servlet engine installed.
  
  If you don't know how to do this, well, stop right here and move to the 
  Apache Tomcat project (http://jakarta.apache.org/tomcat/) then come back
  when you are done.

  Done? Ok, let's go on.

  
 2) Set your JAVA_HOME enviornment
  
  You have to set your JAVA_HOME enviornment to point to the root directory of
  the Java Development Kit installed on your machine. To do this simply type:
  
    [unix] JAVA_HOME=/path/to/java/
    [win32] SET JAVA_HOME=c:\path\to\java

  your mileage may vary, but you know how to setup enviornments, right?


 3) Create the Cocoon WAR package.

 3a) Automatic install.

  To create the package and automatically install it in your servlet
  container, do
  
    [unix]  ./build.sh  -Dinclude.webapp.libs=yes -Dinstall.war=$TOMCAT_HOME/webapps install
    [win32] .\build.bat -Dinclude.webapp.libs=yes -Dinstall.war=%TOMCAT_HOME%\webapps install

  This creates the "cocoon.war" file in '$TOMCAT_HOME/webapps' which
  is the absolute path to the location where the "cocoon.war" file
  should be deployed. It also changes all references to that directory
  in the included samples so that i.e. the database samples will work
  properly.
  
  Continue with 5)

 3b) Manual install.

  To do this you simply have to type, depending on your operating system
  
    [unix]  ./build.sh  -Dinclude.webapp.libs=yes -Dinstall.war=$TOMCAT_HOME/webapps webapp
    [win32] .\build.bat -Dinclude.webapp.libs=yes -Dinstall.war=%TOMCAT_HOME%\webapps webapp
  
  This will create the "cocoon.war" file in the './build/cocoon'
  directory. It also changes all references to that directory in the
  included samples so that i.e. the database samples will work
  properly.

  TOMCAT_HOME points to the directory where tomcat is installed (note:
  you don't need to set it in the enviornment, it's there only to show
  you). For more information on Tomcat 3.2.1 see the FAQ below.

 4) Install the WAR package in your servlet container.
  
  There is no standard way to do this, but in most servlet engines, this is 
  just a matter of copying the war file in a specific directory and the
  engine will take care of installing it when restarted. 
  
  For Apache Tomcat, you have to copy the WAR archive into the '/webapps'
  directory, so do
  
    [unix] cp ./build/cocoon/cocoon.war $TOMCAT_HOME/webapps/cocoon.war
    [win32] copy .\build\cocoon\cocoon.war %TOMCAT_HOME%\webapps\cocoon.war
  

 5) Restart the servlet engine.


 6) Access the URI 'http://localhost/cocoon/' with your favorite browser

 
 7) Wait a few seconds (Cocoon needs to compile parts of itself when launched)
 

 8) Say hello to Cocoon :)
  


  FAQ
  ---
  
  1) Why does nothing happen when I access 'http://localhost/cocoon/'?

  You might want to check a few things:
  
   - is your server listening to port 80? if not, you have to call the right
     port like in 'http://localhost:8080/cocoon/'. Note that Apache Tomcat
     binds by default to port 8080, NOT 80.
     
   - did your servlet engine install the WAR file? you can check by making
     sure the WAR file was unpacked or connecting to the administration tools
     of your servlet engine.
     
   - did you restart the servlet engine? if not, do it.
   
   
  2) Why does Cocoon take so long to start?
  
  Cocoon compiles sitemaps into java classes to increase runtime performance,
  this is done only at startup and only if the sitemap file is modified, for 
  all the other requests the compiled sitemap is executed. See question #7 
  for information on how to pre-compile the sitemap and the XSP's.

  
  3) Can I improve startup-time by precompiling the sitemap and XSP's?

  Sure, follow the instructions:
  
    a) Set the "work-directory" parameter in web.xml as follows:
     
        <init-param>
         <param-name>work-directory</param-name>
         <param-value>WEB-INF/classes</param-value>
        </init-param>
         
    b) Set the auto-reload to false in your cocoon.xconf file as follows:
      
        <parameter name="auto-reload" value="false"/>
        
    c) Use "-Dcompile.xsp=yes" in your build command line when you are
       building your WAR file. For example:
        
       ./build.sh -Dcompile.xsp=yes -Dinclude.webapp.libs=yes -Dinstall.war=$TOMCAT_HOME/webapps install
        
        
  4) Why is cocoon.war so big?
  
  Cocoon.war includes all the libraries that it requires to run. They are 
  several megabytes of Java classes and it also includes the JDK javac compiler
  which must be present in the war file to allow page compilation without 
  classloading problems.



  5) I get a java.lang.VerifyError when accessing 'http://localhost/cocoon/'.
     What's wrong?

  Make sure you do not have a Cocoon 1.x jar in your servlet container lib/
  directory.


  6) I get an Exception when accessing Cocoon the first time. What's wrong?

  Cocoon requires a JAXP 1.1 compliant parser. Recent servlet engines
  (like Tomcat 3.2.1) use older xml parsers. You have to replace the xml
  parser with a newer one (e.g. the Xerces 1.3.0).
  For Tomcat 3.2.1 simply remove the jaxp.jar and the parser.jar from the
  tomcat/lib directory and copy the xerces.jar to this directory and rename
  it to parser.jar. Before you restart Tomcat make sure to remove the
  tomcat/work directory beforehand.

  7) I don't want to build Cocoon myself.

  Download the binary distribution from http://xml.apache.org/dist/cocoon.
  The binary distribution contains a pre-build war file of Cocoon.

  
  8) I'm still stuck, what do I do?
  
  Read the Cocoon documentation included in the distribution. 
  
  This file is just a quick and dirty way to get you started but the docs 
  contain much more detailed information as well as FAQs and indications
  on how to contact us.
  
  
  
  Happy hacking with Apache Cocoon.

                                           The Apache XML Project
                                           http://xml.apache.org/

  
