vgritsenko 02/03/04 20:37:23
Modified: src/documentation/xdocs/installing index.xml
Log:
Restructure doc a little: added new "Configuring Env" chapter.
Added JRun installation instructions.
Revision Changes Path
1.12 +217 -152 xml-cocoon2/src/documentation/xdocs/installing/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/installing/index.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- index.xml 4 Mar 2002 15:29:20 -0000 1.11
+++ index.xml 5 Mar 2002 04:37:23 -0000 1.12
@@ -111,36 +111,87 @@
</s2>
</s1>
- <s1 title="Building Cocoon">
- <s2 title="Set JAVA_HOME environment variable">
- <p>Set the JAVA_HOME environment variable to point to the root directory of
- the Java Development Kit installed on your machine. To do this simply
type:</p>
+ <s1 title="Configuring Environment">
+ <s2 title="Set JAVA_HOME environment variable">
+ <p>Set the JAVA_HOME environment variable to point to the root directory of
+ the Java Development Kit installed on your machine. To do this simply
type:</p>
- <source>
+<source>
[unix] JAVA_HOME=/path/to/java/
-[win32] SET JAVA_HOME=c:\path\to\java
- </source>
+[win32] SET JAVA_HOME=c:\path\to\java</source>
- <p>Your mileage may vary, but you know how to setup environments, right?</p>
- </s2>
+ <p>Your mileage may vary, but you know how to setup environments, right?</p>
+ </s2>
+
+ <s2 title="Java 1.4 configuration">
+ <p>Cocoon requires more recent versions of the Xerces and Xalan libraries
+ than those shipped with j2se 1.4. To override bundled libraries, follow
+ these steps:
+ </p>
+ <ol>
+ <li>
+ Create <code>%JAVA_HOME%\jre\lib\endorsed</code> directory.
+ </li>
+ <li>
+ Copy <code>xerces-XXX.jar</code>, <code>xalan-XXX.jar</code>,
+ and the <code>xml-apis.jar</code> from the
+ <code>.\lib\core\</code> to the
+ <code>%JAVA_HOME%\jre\lib\endorsed\</code> directory.
+ </li>
+ </ol>
+ </s2>
+
+ <s2 title="UNIX with X server">
+ <p>Cocoon is bundled with the <link
href="http://xml.apache.org/batik/";>Batik</link>
+ (SVG rasterization toolkit) to deliver SVG imaging capabilities. Batik
uses Java
+ <code>java.awt</code> library, which (at least in Sun JDK before 1.4)
requires
+ graphics display. This means that X server must be running and Cocoon
should
+ have permission to connect to it.
+ </p>
+ <p>Easiest way to avoid X server connection problem (and to have mentioned
permission)
+ is to install and run Cocoon and entire servlet engine of your choice
under regular
+ user account.
+ </p>
+ <p>For security, and many other reasons, X server can be replaced by Xfvb
+ or PJA (alternative awt implementation).</p>
+ <note>Sun JDK 1.4 does not require graphics display anymore.</note>
+ </s2>
+
+ <s2 title="Headless UNIX and PJA">
+ <p>If you are using unix with the Sun JDK, it's awt implementation requires
you to use X
+ even if you aren't actually displaying anything. One simple solution is
to use a different
+ implementation of the awt.</p>
+
+ <ol>
+ <li>From www.eteks.com you can get an awt replacement that doesn't need X:
+ <link
href="http://www.eteks.com/pja/en/";>http://www.eteks.com/pja/en/</link>.</li>
+ <li>Then add the following options to the Java command starting your
container:
+ </li>
+ </ol>
+
+<source>
+-Xbootclasspath/a:/path/to/pja.jar
+-Dawt.toolkit=com.eteks.awt.PJAToolkit
+-Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment
+-Djava.awt.fonts=/usr/local/jdk/jre/lib/fonts/</source>
+
+
+ <note>If you use Tomcat, this can be done by setting environment variable
+ CATALINA_OPTS (Tomcat 4.x), or TOMCAT_OPTS (Tomcat 3.x):</note>
+
+<source>
+export CATALINA_OPTS='-Xbootclasspath/a:/path/to/pja.jar \
+ -Dawt.toolkit=com.eteks.awt.PJAToolkit \
+ -Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment \
+ -Djava.awt.fonts=/usr/local/jdk/jre/lib/fonts/'</source>
+
+ </s2>
+ </s1>
- <s2 title="Java 1.4 configuration">
- <p>Cocoon requires more recent versions of the Xerces and Xalan libraries
- than those shipped with j2se 1.4. To override bundled libraries, follow
- these steps:
+ <s1 title="Building Cocoon">
+ <p>If you downloaded binary distriution of the Cocoon, you can
+ skip this chapter and proceed to the "Installing Cocoon".
</p>
- <ol>
- <li>
- Create <code>%JAVA_HOME%\jre\lib\endorsed</code> directory.
- </li>
- <li>
- Copy <code>xerces-XXX.jar</code>, <code>xalan-XXX.jar</code>,
- and the <code>xml-apis.jar</code> from the
- <code>xml-cocoon2\lib\core\</code> to the
- <code>%JAVA_HOME%\jre\lib\endorsed\</code> directory.
- </li>
- </ol>
- </s2>
<!-- TODO: Replacing HSQLDB with other SQL DB
<s2 title="Making the sql examples work out of the box">
@@ -177,7 +228,9 @@
Most of these libraries are already included in the distribution, but some
have to be downloaded manually. The build task checks whether you have
the required libraries or not and includes the optional components only
- if you have the libraries available when you build Cocoon.
+ if you have the libraries available when you build Cocoon. Refer to the
+ <link href="jars.html">Cocoon JARs</link> page for a list of libraries
+ and locations where you could get them.
</p>
<p>
A library/package is available to the build process when it is located
@@ -226,71 +279,71 @@
</s2>
<s2 title="Running the build">
-
<p>Cocoon uses <link href="http://jakarta.apache.org/ant/";>Jakarta Ant</link>
- for the build and installation, and comes with a build script
- ([unix]./build.sh, [win32] .\build.bat) that automates the process.</p>
-
+ for the build and installation, and comes with a build script
+ ([unix]./build.sh, [win32] .\build.bat) that automates the process.</p>
+
<note>If you want to use build.xml directly with your copy of Ant, please
- run the build sctipt at least once after every CVS checkout, to ensure that
- extra initializations like jar copying are done correctly.</note>
+ run the build script at least once after every CVS checkout, to ensure that
+ extra initializations like jar copying are done correctly.</note>
+
+ <note>The UNIX build script (build.sh) overrides the existing ANT_HOME
variable.</note>
- <note>The build script overrides the existing ANT_HOME variable.</note>
-
<p>There are basically two options that can be set as parameters to
- the script: <strong>targets</strong> and <strong>properties</strong>.</p>
-
- <s3 title="build targets">
- <p>Targets are the execution units available in
- <link href="http://jakarta.apache.org/ant/";>Ant</link> build files.</p>
-
- <p>Only one target can be specified per run, by appending it to
- the script invocation:</p>
-
- <source>
+ the script: <strong>targets</strong> and <strong>properties</strong>.</p>
+
+ <s3 title="About build targets">
+ <p>Targets are the execution units available in
+ <link href="http://jakarta.apache.org/ant/";>Ant</link> build files.</p>
+
+ <p>Only one target can be specified per run, by appending it to
+ the script invocation:</p>
+
+<source>
[unix] ./build.sh target
-[win32] .\build.bat target
- </source>
+[win32] .\build.bat target</source>
+
</s3>
- <s3 title="build properties">
+
+ <s3 title="About build properties">
<p>A target can use properties, that can, or must in some cases, be
specified.
- Multiple properties can be set, by appending them like this to
- the script invocation:</p>
-
- <source>
+ Multiple properties can be set, by appending them like this to
+ the script invocation:</p>
+
+<source>
[unix] ./build.sh [target] -Dpropertyname=propertyvalue
-[win32] .\build.bat [target] -Dpropertyname=propertyvalue
- </source>
+[win32] .\build.bat [target] -Dpropertyname=propertyvalue</source>
+
</s3>
-
- <p>The <strong>build.xml</strong> file comes with some basic important
targets. If no target is specified,
- the default one is used (defined in build.xml).</p>
- <note>Some targets are preliminary and their call method will change
- in the future. Preliminary targets are marked as [BETA].</note>
+ <s3 title="Cocoon build targets">
+ <p>The <strong>build.xml</strong> file comes with some basic
+ important targets. If no target is specified, the default one
+ is used (defined in build.xml).</p>
+
+ <note>Some targets are preliminary and their call method will change
+ in the future. Preliminary targets are marked as [BETA].</note>
- <p>Cocoon targets place work files and results in a build directory under
- the cocoon root. The only exception are the distribution targets that build
- in a directory called dist.</p>
+ <p>Cocoon targets place work files and results in a build directory
+ under the cocoon root. The only exception are the distribution targets
+ that build in a directory called dist.</p>
- <s3 title="build all">
+ <s4 title="build all">
<p>Builds all main Cocoon targets to create the
<strong>cocoon.jar</strong>
package.
</p>
-
<ul>
<li><strong>target:</strong> all</li>
<li><strong>required properties:</strong> none</li>
<li><strong>buildfile:</strong> build.xml</li>
</ul>
-
+
<note>This is currently the default target.</note>
-
+
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="[BETA] build interactive">
+ <s4 title="[BETA] build interactive">
<p>Shows common build targets and asks the user for eventual
properties that may be needed.
</p>
@@ -309,11 +362,9 @@
</source>
<note>This is the recommended target for first-time users.</note>
-
- </s3>
+ </s4>
-
- <s3 title="[BETA] build installwar">
+ <s4 title="[BETA] build installwar">
<p>Builds and installs Cocoon war package in a specified directory.
</p>
@@ -327,10 +378,9 @@
<note>This is the recommended target for an easy install in Tomcat.</note>
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="build docs">
+ <s4 title="build docs">
<p>Builds the Cocoon documentation in html format.
</p>
@@ -341,10 +391,9 @@
</ul>
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="build javadocs">
+ <s4 title="build javadocs">
<p>Builds the Cocoon javadocs in html format.
</p>
@@ -355,10 +404,9 @@
</ul>
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="build printerdocs">
+ <s4 title="build printerdocs">
<p>Builds the Cocoon documentation in html printer-friendly format.
</p>
@@ -369,10 +417,9 @@
</ul>
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="build test">
+ <s4 title="build test">
<p>Runs Cocoon unit tests.
</p>
@@ -383,10 +430,9 @@
</ul>
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="build compile">
+ <s4 title="build compile">
<p>Compiles Cocoon source files.
</p>
@@ -397,11 +443,13 @@
</ul>
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="build clean">
- <p>Cleans the build directory.
+ <s4 title="build clean">
+ <p>Cleans the build directory. It is recommended to clean Cocoon
+ build directory every time you upgrade Cocoon, or add/remove
+ libraries from the <code>./lib/optional/</code>
+ directory, or change JDK version.
</p>
<ul>
@@ -411,10 +459,9 @@
</ul>
<note>Available in interactive build.</note>
-
- </s3>
+ </s4>
- <s3 title="build dist">
+ <s4 title="build dist">
<p>Creates source and binary distributions of Cocoon.
</p>
@@ -425,10 +472,9 @@
</ul>
<note>The results are in the dist directory.</note>
-
- </s3>
+ </s4>
- <s3 title="build webapp">
+ <s4 title="build webapp">
<p>Creates the Cocoon WAR package. It's a non-interactive version
of installwar.</p>
@@ -441,17 +487,16 @@
<p>To do this you simply have to type:</p>
- <source>
+<source>
[unix] ./build.sh -Dinclude.webapp.libs=yes webapp
-[win32] .\build.bat -Dinclude.webapp.libs=yes webapp
- </source>
-
- <p>this will create the "cocoon.war" file in the
- './build/cocoon' directory.</p>
+[win32] .\build.bat -Dinclude.webapp.libs=yes webapp</source>
- </s3>
+ <p>this will create the <code>cocoon.war</code> file in the
+ <code>./build/cocoon</code> directory. Follow instructions in the next
+ chapter to deploy this webapp in your container.</p>
+ </s4>
- <s3 title="[BETA] build scratchpad">
+ <s4 title="[BETA] build scratchpad">
<p>An interactive build to help alpha-testers in installing
cutting-edge code.
</p>
@@ -464,18 +509,16 @@
<p>To do this you simply have to type:</p>
- <source>
+<source>
[unix] ./build.sh -buildfile tools/build-s.xml
-[win32] .\build.bat -buildfile tools/build-s.xml
- </source>
+[win32] .\build.bat -buildfile tools/build-s.xml</source>
- <note><strong>WARNING:</strong>Scratchpad builds are <strong>not
guaranteed to work</strong>.
+ <note><strong>WARNING:</strong> Scratchpad builds are <strong>not
guaranteed to work</strong>.
You have been warned.
</note>
-
- </s3>
+ </s4>
- <s3 title="[BETA] build try">
+ <s4 title="[BETA] build try">
<p>Makes it possible to try new build targets that have not yet made
it into the core build. These targets are in tools/builds/try.xml.
</p>
@@ -488,20 +531,17 @@
<p>To test target test-target for example, you simply have to type:</p>
- <source>
+<source>
[unix] ./build.sh try -Dtry.target=test-target
-[win32] .\build.bat try -Dtry.target=test-target
- </source>
+[win32] .\build.bat try -Dtry.target=test-target</source>
<note>Targets are in tools/build-i.xml.</note>
- </s3>
-
+ </s4>
+ </s3>
</s2>
-
- </s1>
+ </s1>
- <s1 title="Installing Cocoon">
-
+ <s1 title="Installing Cocoon">
<p>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.</p>
@@ -540,7 +580,8 @@
</li>
<li>
- <strong>Copy the cocoon/lib/xerces-XXX.jar and cocoon/lib/xml-apis.jar
files to tomcat/lib</strong>
+ <strong>Copy the cocoon/lib/core/xerces-XXX.jar and
cocoon/lib/core/xml-apis.jar
+ JAR files to tomcat/lib</strong>
Cocoon will now be able to see and use the correct XML libraries.
</li>
@@ -565,7 +606,7 @@
</ol>
</s2>
- <s2 title="Installing on Tomcat 4.X">
+ <s2 title="Installing on Tomcat 4.0 - 4.0.1">
<p>Tomcat 4 is a really straight-forward installation.</p>
<ol>
<li>
@@ -590,30 +631,7 @@
Note that the first time you access Cocoon, it will take a few
seconds to start, since Cocoon needs to compile parts of itself.
</li>
-
</ol>
- <s3 title="Linux/Headless/Batik">
- <p>If you are using unix with the Sun JDK, it's awt implementation requires
you to use X
- even if you aren't actually displaying anything. One simple solution is to
use a different
- implementation of the awt.</p>
-
- <ol>
- <li>From www.eteks.com you can get an awt replacement that doesn't need X:
- <link
href="http://www.eteks.com/pja/en/";>http://www.eteks.com/pja/en/</link>.</li>
-
- <li>Then add the following to your Tomcat startup script
- (using CATALINA_OPTS if it is 4.x, TOMCAT_OPTS if it is 3.x):
- </li>
- </ol>
-
- <source>
-export CATALINA_OPTS='-Xbootclasspath/a:/path/to/pja.jar \
- -Dawt.toolkit=com.eteks.awt.PJAToolkit \
- -Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment \
- -Djava.awt.fonts=/usr/local/jdk/jre/lib/fonts/'
- </source>
- <p><strong>(Re)start Tomcat and enjoy!</strong></p>
- </s3>
</s2>
<s2 title="Installing on BEA Weblogic 6.0">
@@ -822,7 +840,7 @@
<li>jaxp.jar</li>
</ul>
</li>
- <li>Copy <code>xml-apis.jar</code> from <code>cocoon/lib</code> to
<code>jboss/lib</code></li>
+ <li>Copy <code>xml-apis.jar</code> from <code>cocoon/lib/core/</code> to
<code>jboss/lib</code></li>
<li>Change <code>jboss/bin/run.sh</code></li>
</ul>
<source>
@@ -887,7 +905,7 @@
<li>parser.jar</li>
</ul>
</li>
- <li>Copy <code>xerces-XXX.jar</code> from <code>cocoon/lib</code> to
<code>jboss/lib</code></li>
+ <li>Copy <code>xerces-XXX.jar</code> from <code>cocoon/lib/core/</code> to
<code>jboss/lib</code></li>
<li>Change <code>jboss/bin/run.sh</code></li>
</ul>
<source>
@@ -917,6 +935,7 @@
<note>As both JBoss and Cocoon ship with a Hypersonic database installed,
these two conflict and you won't be able to use Cocoon database (SQL) samples. Then
again, you probably use JBoss for EJB persistence anyway, so this shouldn't bother you
too much ;-)
</note>
</s2>
+
<s2 title="Installing on Resin 2.0.x">
<p>
This section describes the deployment of the Cocoon sample WAR with Resin
2.0.x.
@@ -942,8 +961,9 @@
<li>sax.jar</li>
</ul>
</li>
- <li>Copy the <code>xerces-XXX.jar</code> JAR file from
<code>xml-cocoon2/lib</code> to
- <code>resin-2.0.x/lib</code> directory</li>
+ <li>Copy <code>xerces-XXX.jar</code> and <code>xml-apis.jar</code>
+ JAR file from <code>xml-cocoon2/lib/core/</code> to
+ the <code>resin-2.0.x/lib/</code> directory</li>.
</ul>
</li>
<li>Copy the <code>xml-cocoon2/build/cocoon/cocoon.war</code> WAR file to
<code>resin-2.0.x/webapps</code> directory
@@ -959,6 +979,7 @@
<code><![CDATA[<web-app id='/cocoon'
app-dir='/path/to/webapp/cocoon.war'/>]]></code>
</note>
</s2>
+
<s2 title="Installing on HP-AS 8.X">
<p>HP-AS is J2EE application server available from the Hewlett-Packard
website.
<link href="http://www.hpmiddleware.com/download";>Download and install
HP-AS 8.X</link>
@@ -1013,7 +1034,51 @@
</li>
</ol>
</s2>
- </s1>
-</body>
+ <s2 title="Installing on JRun 3.1">
+ <p>
+ This section describes the deployment of the Cocoon sample WAR with JRun
3.1,
+ on its default server. It assumes that you built Cocoon as described
above. All
+ steps have been tested under Win2000.
+ </p>
+ <p>To get Cocoon running do the following:</p>
+ <ul>
+ <li>Stop the default and admin servers if they are running.</li>
+ <li>Remove <code>jaxp.jar</code> and <code>parser.jar</code>
+ files (Crimson XML parser) from the <code>jrun/lib/ext/</code>
directory.
+ </li>
+ <li>Install Xerces as default XML parser for JRun by copying
+ <code>xerces-XXX.jar</code> and <code>xml-apis.jar</code> JAR
+ files from the <code>xml-cocoon2/lib/core/</code> to
<code>jrun/lib/ext/</code>
+ directory.
+ </li>
+ <li>Update Rhino shipped with JRun with newer version from the Cocoon by
+ overwriting <code>jrun/lib/rhino.jar</code> JAR file
+ with the <code>xml-cocoon2/lib/optional/rhino-1.5r3.jar</code> file.
+ </li>
+ <li>Start JRun admin server.</li>
+ <li>Start JRun default server.</li>
+ <li>Open JRun admin page:
+ <link href="http://localhost:8000/";>http://localhost:8000/</link>
+ </li>
+ <li>Deploy cocoon.war webapp using console. Use same values for
+ application name and URI prefix (e.g., application name "cocoon",
+ URI "/cocoon").</li>
+ <li>Open the Cocoon welcome page:
+ <link
href="http://localhost:8100/cocoon/";>http://localhost:8100/cocoon/</link>
+ </li>
+ <li>Congratulations! (hopefully) you should see the Cocoon welcome
page.</li>
+ </ul>
+ <note>Instead of deploying WAR file using console, same could be done by
copying
+ <code>xml-cocoon2/build/cocoon/webapp</code> under
<code>jrun/servers/default/</code>
+ directory and adding following lines to the
<code>jrun/servers/default/local.properties</code>:
+ </note>
+
+<source>
+cocoon.rootdir=/absolute/path/to/jrun/servers/default/cocoon
+cocoon.class={webapp.service-class}
+webapp.mapping./cocoon=cocoon</source>
+ </s2>
+ </s1>
+ </body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
