bin/cassandra improvements

- allow user-local configuration (~/.cassandra.in.sh)
- add comments documenting startup configuration

Patch by eevans; reviewed by jbellis and Lance Weber for CASSANDRA-416

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

bin/cassandra

@@ -20,22 +20,67 @@
 #   -f: start in foreground
 #   -p <filename>: log the pid to a file (useful to kill it later)
 
+# CONTROLLING STARTUP:
+# 
+# This script relies on few environment variables to determine startup
+# behavior, those variables are:
+#
+#   CLASSPATH -- A Java classpath containing everything necessary to run.
+#   JVM_OPTS -- Additional arguments to the JVM for heap size, etc
+#   CASSANDRA_CONF -- Directory containing Cassandra configuration files.
+#
+# As a convenience, a fragment of shell is sourced in order to set one or
+# more of these variables. This so-called `include' can be placed in a 
+# number of locations and will be searched for in order. The lowest 
+# priority search path is the same directory as the startup script, and
+# since this is the location of the sample in the project tree, it should
+# almost work Out Of The Box.
+#
+# Any serious use-case though will likely require customization of the
+# include. For production installations, it is recommended that you copy
+# the sample to one of /usr/share/cassandra/cassandra.in.sh,
+# /usr/local/share/cassandra/cassandra.in.sh, or 
+# /opt/cassandra/cassandra.in.sh and make your modifications there.
+#
+# Another option is to specify the full path to the include file in the
+# environment. For example:
+#
+#   $ CASSANDRA_INCLUDE=/path/to/in.sh cassandra -p /var/run/cass.pid
+#
+# Note: This is particularly handy for running multiple instances on a 
+# single installation, or for quick tests.
+#
+# Finally, developers and enthusiasts who frequently run from an SVN 
+# checkout, and do not want to locally modify bin/cassandra.in.sh, can put
+# a customized include file at ~/.cassandra.in.sh.
+#
+# If you would rather configure startup entirely from the environment, you
+# can disable the include by exporting an empty CASSANDRA_INCLUDE, or by 
+# ensuring that no include files exist in the aforementioned search list.
+# Be aware that you will be entirely responsible for populating the needed
+# environment variables.
+
+
 if [ -x $JAVA_HOME/bin/java ]; then
     JAVA=$JAVA_HOME/bin/java
 else
     JAVA=`which java`
 fi
 
+# If an include wasn't specified in the environment, then search for one...
 if [ "x$CASSANDRA_INCLUDE" = "x" ]; then
+    # Locations (in order) to use when searching for an include file.
     for include in /usr/share/cassandra/cassandra.in.sh \
                    /usr/local/share/cassandra/cassandra.in.sh \
                    /opt/cassandra/cassandra.in.sh \
+                   ~/.cassandra.in.sh \
                    `dirname $0`/cassandra.in.sh; do
         if [ -r $include ]; then
             . $include
             break
         fi
     done
+# ...otherwise, source the specified include.
 elif [ -r $CASSANDRA_INCLUDE ]; then
     . $CASSANDRA_INCLUDE
 fi