| |
| |
| +-----------------------------+ |
| | 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.3.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 servlet" or "./cocoon.sh servlet" |
| |
| 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. |
| |
| |
| Reading the documentation |
| -------------------------- |
| |
| This directory contains the full Cocoon documentation (as xml documents). |
| You can either browse the documentation when you start Cocoon as described |
| above and go to the documentation section: http://localhost:8888/docs/index.html. |
| Or you can build the docs your self by running "build.bat docs" or |
| "./build.sh docs". If you want to build the docs yourself, you need |
| an installed version of Forrest (http://xml.apache.org/forrest). |
| |
| Of course you can also read the documentation at the website |
| http://cocoon.apache.org/ |
| |
| 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. |