Improve RUNNING.txt by adding the following:

- Mention that CATALINA_HOME should have a correct value or be absent (BZ 51806)
- Mention environment variables that are used by the scripts.
- Document what is left in $CATALINA_HOME when $CATALINA_BASE is used.
- Document setenv.* scripts.

Feedback and better wording are welcome.

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1175798 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/RUNNING.txt b/RUNNING.txt
index f25b786..ae86e01 100644 (file)
--- a/RUNNING.txt
+++ b/RUNNING.txt
@@ -56,7 +56,7 @@ subdirectory of your source distribution.
 
 (2.1) Download a binary distribution of Tomcat from:
 
-      http://tomcat.apache.org
+      http://tomcat.apache.org/
 
 (2.2) Unpack the binary distribution into a convenient location so that the
       distribution resides in its own directory (conventionally named
@@ -64,6 +64,11 @@ subdirectory of your source distribution.
       the symbolic name "$CATALINA_HOME" is used to refer to the full
       pathname of the release directory.
 
+NOTE: The scripts expect that the $CATALINA_HOME environment variable is
+either set to the correct value, as defined above, or is absent. In the
+latter case the scripts will try to calculate the value for $CATALINA_HOME
+by themselves.
+
 
 (3) Start Up Tomcat
 
@@ -81,7 +86,7 @@ subdirectory of your source distribution.
 (3.3) Further information about configuring and running Tomcat can be found in
       the documentation included here, as well as on the Tomcat web site:
 
-      http://tomcat.apache.org
+      http://tomcat.apache.org/
 
 
 (4) Shut Down Tomcat
@@ -102,30 +107,71 @@ binary distribution shared among multiple users on the same server.  To make
 this possible, you can set the $CATALINA_BASE environment variable to the
 directory that contains the files for your 'personal' Tomcat instance.
 
-When you use $CATALINA_BASE, Tomcat will calculate all relative references for
-files in the following directories based on the value of $CATALINA_BASE instead
-of $CATALINA_HOME:
+When running with separate $CATALINA_HOME and $CATALINA_BASE, the files
+and directories are split as following:
+
+In $CATALINA_BASE:
+
+ * bin  - Only the following files:
+          setenv.sh (*nix), setenv.bat (windows) and tomcat-juli.jar
+
+ * conf - Server configuration files (including server.xml)
+
+ * lib  - Libraries
+
+ * logs - Log and output files
+
+ * webapps - Automatically loaded web applications
+
+ * work - Temporary working directories for web applications
+
+ * temp - Directory used by the JVM for temporary files (java.io.tmpdir)
+
+
+In $CATALINA_HOME:
+
+ * bin  - Startup and shutdown scripts
+
+          The following files will be used only if they are absent in
+          $CATALINA_BASE/bin:
+
+          setenv.sh (*nix), setenv.bat (windows) and tomcat-juli.jar
+
+ * lib  - Libraries
+
+ * endorsed - Libraries that override standard "Endorsed Standards"
+          libraries provided by JRE. See Classloading documentation
+          in the User Guide for details. This directory is not created by
+          default.
+
+If $CATALINA_BASE environment variable is not set, it will default to the
+same value as $CATALINA_HOME, which means that the same directory is used
+for all relative path resolutions.
 
-* bin  - Only setenv.sh (*nix), setenv.bat (windows) and tomcat-juli.jar
 
-* conf - Server configuration files (including server.xml)
+By default Tomcat will first try to load classes and JARs from
+$CATALINA_BASE/lib and then from $CATALINA_HOME/lib. You may place instance
+specific JARs and classes (e.g. JDBC drivers) in $CATALINA_BASE/lib whilst
+keeping the standard Tomcat JARs in $CATALINA_HOME/lib.
 
-* logs - Log and output files
 
-* webapps - Automatically loaded web applications
+The values of $CATALINA_BASE and $CATALINA_HOME are available in XML
+configuration files processed by Tomcat as ${catalina.base} and
+${catalina.home} respectively.
 
-* work - Temporary working directories for web applications
 
-* temp - Directory used by the JVM for temporary files (java.io.tmpdir)
+======================================
+Using setenv.* to Tune Tomcat Scripts
+======================================
 
-Note that by default Tomcat will first try to load classes and JARs from
-$CATALINA_BASE/lib and then $CATALINA_HOME/lib. You can place instance specific
-JARs and classes (eg JDBC drivers) in $CATALINA_BASE/lib whilst keeping the
-standard Tomcat JARs in $CATALINA_HOME/lib.
+The scripts used to run Tomcat can be further configured by setting several
+environment variables. For the list of these environent variables see the
+comment at the top of catalina.sh or .bat script.
 
-If you do not set $CATALINA_BASE, $CATALINA_BASE will default to the same value
-as $CATALINA_HOME, which means that the same directory is used for all relative
-path resolutions.
+The setenv.sh (*nix) or setenv.bat (windows) script can be used to
+configure all those variables except $CATALINA_BASE and $CATALINA_HOME. The
+standard scripts will execute the setenv.* script when it is present either
+in $CATALINA_BASE/bin or in $CATALINA_HOME/bin.
 
 
 ================