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]
