From 05f23656d016f99c56b1a9c193c5715d6d614529 Mon Sep 17 00:00:00 2001
From: Dean Troyer <dtroyer@gmail.com>
Date: Wed, 29 Aug 2012 15:20:21 -0500
Subject: [PATCH] Add lib/template

Add a template for the lib/* sub-scripts and a description
to HACKING.

Change-Id: Ia490de8e565982c517525e09d8941a847ba530aa
---
 HACKING.rst  | 20 ++++++++++++--
 lib/template | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 94 insertions(+), 3 deletions(-)
 create mode 100644 lib/template

diff --git a/HACKING.rst b/HACKING.rst
index 7262cff63d..e8f90c78d7 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -53,9 +53,23 @@ configuration of the user environment::
     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 0000000000..d70f2189a1
--- /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?
+    :
+}