Add lib/template
Add a template for the lib/* sub-scripts and a description
to HACKING.
Change-Id: Ia490de8e565982c517525e09d8941a847ba530aa
diff --git a/HACKING.rst b/HACKING.rst
index 7262cff..e8f90c7 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -53,9 +53,23 @@
source $TOP_DIR/openrc
``stack.sh`` is a rather large monolithic script that flows through from beginning
-to end. There is a proposal to segment it to put the OpenStack projects
-into their own sub-scripts to better document the projects as a unit rather than
-have it scattered throughout ``stack.sh``. Someday.
+to end. The process of breaking it down into project-level sub-scripts has begun
+with the introduction of ``lib/cinder`` and ``lib/ceilometer``.
+
+These library sub-scripts have a number of fixed entry points, some of which may
+just be stubs. These entry points will be called by ``stack.sh`` in the
+following order::
+
+ install_XXXX
+ configure_XXXX
+ init_XXXX
+ start_XXXX
+ stop_XXXX
+ cleanup_XXXX
+
+There is a sub-script template in ``lib/templates`` to be used in creating new
+service sub-scripts. The comments in ``<>`` are meta comments describing
+how to use the template and should be removed.
Documentation
diff --git a/lib/template b/lib/template
new file mode 100644
index 0000000..d70f218
--- /dev/null
+++ b/lib/template
@@ -0,0 +1,77 @@
+# lib/template
+# Functions to control the configuration and operation of the XXXX service
+# <do not include this template file in ``stack.sh``!>
+
+# Dependencies:
+# ``functions`` file
+# ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
+# <list other global vars that are assumed to be defined>
+
+# ``stack.sh`` calls the entry points in this order:
+#
+# install_XXXX
+# configure_XXXX
+# init_XXXX
+# start_XXXX
+# stop_XXXX
+# cleanup_XXXX
+
+# Print the commands being run so that we can see the command that triggers
+# an error. It is also useful for following along as the install occurs.
+set -o xtrace
+
+
+# Defaults
+# --------
+
+# <define global variables here that belong to this project>
+
+# Set up default directories
+XXXX_DIR=$DEST/XXXX
+XXX_CONF_DIR=/etc/XXXX
+
+
+# Entry Points
+# ------------
+
+# cleanup_XXXX() - Remove residual data files, anything left over from previous
+# runs that a clean run would need to clean up
+function cleanup_XXXX() {
+ # kill instances (nova)
+ # delete image files (glance)
+ # This function intentionally left blank
+ :
+}
+
+# configure_XXXX() - Set config files, create data dirs, etc
+function configure_XXXX() {
+ # sudo python setup.py deploy
+ # iniset $XXXX_CONF ...
+ # This function intentionally left blank
+ :
+}
+
+# init_XXXX() - Initialize databases, etc.
+function init_XXXX() {
+ # clean up from previous (possibly aborted) runs
+ # create required data files
+ :
+}
+
+# install_XXXX() - Collect source and prepare
+function install_XXXX() {
+ # git clone xxx
+ :
+}
+
+# start_XXXX() - Start running processes, including screen
+function start_XXXX()
+ # screen_it XXXX "cd $XXXX_DIR && $XXXX_DIR/bin/XXXX-bin"
+ :
+}
+
+# stop_XXXX() - Stop running processes (non-screen)
+function stop_XXXX() {
+ # FIXME(dtroyer): stop only our screen screen window?
+ :
+}