cvs commit: xml-cocoon2 INSTALL.txt

[st...@apache.org]

stefano     2003/02/23 08:39:10

  Added:       .        INSTALL.txt
  Log:
  new INSTALL doc that matches the new system (please, read it!!)
  
  Revision  Changes    Path
  1.1                  xml-cocoon2/INSTALL.txt
  
  Index: INSTALL.txt
  ===================================================================
  
  
                        +-----------------------------+
                        |     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) Set your JAVA_HOME environment
    
    You have to set your JAVA_HOME environment to point to the root directory of
    the Java Virtual Machine 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?
    
   2) Build Cocoon by typing "build"
  
   3) Run Cocoon by typing "cocoon servlet"
   
   4) 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.
  
  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
  
  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).
  
  
  
  All right, that's it for now. 
  
  Happy hacking with Cocoon.