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


  Let me guess: you don't like to read verbose docs, right?
  
  Great, this file is for you.
  
 1) Unpack the distribution

  Obviously you've done this already, but if you got errors when unpacking
  the archive with tar, you might need to use gnutar instead. Our archives
  contain long paths and filenames which cause problems with some versions
  of the tar command.
 
 2) Set your JAVA_HOME environment
  
  You have to set your JAVA_HOME environment to point to the root directory of
  the Java Virtual Machine (JDK 1.4.x or later) 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 depending on your shell, but you know how to setup 
  environments, right?

 3) Build Cocoon by typing "build" or "./build.sh"

 4) Run Cocoon by typing "cocoon" or "./cocoon.sh"
 
 5) Open http://localhost:8888/ with your browser


That's it!  


Now, you have two choices:

  a) close this file and try to hack something out by yourself
  
  b) keep reading

Go ahead and choose option a), but don't complain if you can't figure out how
to use the cocoon build system for your needs.



Still here? good. You won't regret it.


Updating
--------

If you are updating from a previous release of Cocoon, make sure
that you read the installation instructions on updating first.


Choosing the blocks
-------------------

Cocoon is composed by its 'core' and several 'blocks'.

The core (a.k.a. naked cocoon') contains the system with services that
are needed to all cocoon users. Blocks provide services that you might not need,
therefore the build system allows you to remove them from the build.

Now, do the following steps to configure the blocks you want in your cocoon:

 1) cp blocks.properties local.blocks.properties
 2) edit local.blocks.properties
 3) rebuild (do a "build clean" first if you deactivated some blocks)
 
do not modify blocks.properties directly!


Tuning the build
----------------

Ok, now that you told the build system what services you want assembled
into your distribution, you can tune the build for your personal needs:

 1) cp build.properties local.build.properties
 2) edit local.build.properties

do not modify build.properties directly!
 
An example of a local.build.properties is the following:
 
  compiler=jikes
  compiler.debug=off
  build.webapp=/path/to/where/to/build/the/webapp

where you override default compilation parameters and tell the build system
where to place the generated cocoon webapp. Look into build.properties to find
out what you might want to modify for your own personal needs.


Running Cocoon as a servlet
---------------------------

When you do 'cocoon servlet', the servlet container (jetty) is started and Cocoon
loaded into it. By default, this is attached to port 8888, but you can change
this by setting the "JETTY_PORT" environment property before launching cocoon.

Other properties that you can change are:

 JETTY_ADMIN_PORT (defaults to 8889): is the port where the jetty web 
     administration is connected to. This is available when you launch 
     "cocoon servlet-admin", otherwise its disabled.
     
 JETTY_WEBAPP (defaults to build/webapp): is the location of the webapp
     that jetty has to execute. modify this to match your local.build.properties
     if you modified where the build system creates your webapp
     
 JAVA_DEBUG_PORT (defaults to 8000): is the port where the JVM over-the-wire
     debug interface connects to. This is available only if you launch 
     "cocoon servlet-debug", otherwise is disabled. This is used by remote
     debuggers (for example, Eclipse's).


Note that the "standalone-demo" build target prepares a directory that you can
move elsewhere to run "cocoon servlet" outside of the build tree.



All right, that's it for now. 

Happy hacking with Cocoon.