onos-* script help functions, plus:

o support onos-watch on OS X by emulating 'watch'.

Change-Id: I072f347b21b038168e08405bd228434bcc421aeb
diff --git a/tools/test/bin/onos b/tools/test/bin/onos
old mode 100755
new mode 100644
index 89197db..780a90d
--- a/tools/test/bin/onos
+++ b/tools/test/bin/onos
@@ -3,6 +3,27 @@
 # ONOS remote command-line client.
 # -----------------------------------------------------------------------------
 
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0) [-w] [node]
+
+flags:
+- -w : Waits for ONOS instance to reach run-level 100, i.e. to be fully started.
+
+options:
+- [node] : the node to attach to
+
+summary:
+ ONOS remote command-line client.
+
+ The -w flag depends on 'onos-wait-for-start'. If [node] is unspecified, \$OCI
+ is used.
+
+_EOF_
+}
+[ "$1" = "-h" ] && _usage && exit 0
+
 [ ! -d "$ONOS_ROOT" ] && echo "ONOS_ROOT is not defined" >&2 && exit 1
 . $ONOS_ROOT/tools/build/envDefaults
 . $ONOS_ROOT/tools/test/bin/find-node.sh
diff --git a/tools/test/bin/onos-archetypes-test b/tools/test/bin/onos-archetypes-test
old mode 100755
new mode 100644
index 7ae0033..331c433
--- a/tools/test/bin/onos-archetypes-test
+++ b/tools/test/bin/onos-archetypes-test
@@ -3,6 +3,19 @@
 # Builds a set of projects using ONOS archetypes.
 # -----------------------------------------------------------------------------
 
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0)
+
+summary:
+ Builds a set of projects using ONOS archetypes.
+
+_EOF_
+}
+
+[ "$1" = "-h" ] && _usage && exit 0
+
 set -e
 
 export AROOT=/tmp/foo
diff --git a/tools/test/bin/onos-batch b/tools/test/bin/onos-batch
old mode 100755
new mode 100644
index 67864a2..ae28891
--- a/tools/test/bin/onos-batch
+++ b/tools/test/bin/onos-batch
@@ -3,6 +3,28 @@
 # Executes selected set of ONOS commands using the batch mode.
 # -----------------------------------------------------------------------------
 
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0) [node] <commands>
+
+options:
+- [node] <commands>  : node to run <commands>
+
+summary:
+ Executes selected set of ONOS commands using the batch mode.
+
+ <commands> is a comma-separated list of ONOS CLI commands.
+
+ If [node] isn't specified, the defualt target becomes \$OCI. When no commands
+ are specified, the commands 'summary','intents','flows', and 'hosts' are
+ executed against \$OCI.
+
+_EOF_
+}
+
+[ "$1" = "-h" ] && _usage && exit 0
+
 [ ! -d "$ONOS_ROOT" ] && echo "ONOS_ROOT is not defined" >&2 && exit 1
 . $ONOS_ROOT/tools/build/envDefaults
 
diff --git a/tools/test/bin/onos-config b/tools/test/bin/onos-config
old mode 100755
new mode 100644
index 5c3ab02..348cb83
--- a/tools/test/bin/onos-config
+++ b/tools/test/bin/onos-config
@@ -3,6 +3,28 @@
 # Remotely configures & starts ONOS for the first time.
 # -----------------------------------------------------------------------------
 
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0) [node]
+
+options:
+- [node] : The node to configure
+
+summary:
+ Remotely configures and starts ONOS for the first time.
+
+ The procedure for configruing a node include determining base features,
+ applications to load at startup, and clustering and logical network view
+ configurations, among others.
+
+ If [node] isn't specified, the defualt target becomes \$OCI.
+
+_EOF_
+}
+
+[ "$1" = "-h" ] && _usage && exit 0
+
 [ ! -d "$ONOS_ROOT" ] && echo "ONOS_ROOT is not defined" >&2 && exit 1
 . $ONOS_ROOT/tools/build/envDefaults
 
diff --git a/tools/test/bin/onos-install b/tools/test/bin/onos-install
old mode 100755
new mode 100644
index 7384c2e..139944e
--- a/tools/test/bin/onos-install
+++ b/tools/test/bin/onos-install
@@ -3,6 +3,32 @@
 # Remotely pushes bits to a remote node and installs ONOS on it.
 # -----------------------------------------------------------------------------
 
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0) [-fn] [-m] <settings> [node]
+
+flags:
+- -f            : forces uninstall of currently installed ONOS
+- -n            : do not copy over onos.conf upstart configuration file.
+- -m <settings> : pass <settings> XML file to remote maven installation
+
+options:
+- [node] : remote node to install ONOS on.
+
+summary:
+ Remotely pushes bits to a remote node and installs ONOS on it.
+
+ The [-n] flag assumes that Upstart is used. The [-f] flag depends on
+ and 'onos-config'.
+
+ If [node] is not specified the default target is \$OCI.
+
+_EOF_
+}
+
+[ "$1" = "-h" ] && _usage && exit 0
+
 [ ! -d "$ONOS_ROOT" ] && echo "ONOS_ROOT is not defined" >&2 && exit 1
 . $ONOS_ROOT/tools/build/envDefaults
 
diff --git a/tools/test/bin/onos-push-bits b/tools/test/bin/onos-push-bits
old mode 100755
new mode 100644
index 8c9276f..4d425c6
--- a/tools/test/bin/onos-push-bits
+++ b/tools/test/bin/onos-push-bits
@@ -2,6 +2,24 @@
 # -----------------------------------------------------------------------------
 # Remotely pushes bits to a remote node in preparation for install.
 # -----------------------------------------------------------------------------
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0) [node]
+
+options:
+- [node] : the target node to prime for installation
+
+summary:
+ Remotely pushes bits to a remote node in preparation for install.
+
+ $(basename $0) is invoked as part of 'onos-install', and shouldn't be
+ directly invoked for the most part.
+
+_EOF_
+}
+
+[ "$1" = "-h" ] && _usage && exit 0
 
 [ ! -d "$ONOS_ROOT" ] && echo "ONOS_ROOT is not defined" >&2 && exit 1
 . $ONOS_ROOT/tools/build/envDefaults
diff --git a/tools/test/bin/onos-uninstall b/tools/test/bin/onos-uninstall
old mode 100755
new mode 100644
index 7a8b9a5..11e5ba2
--- a/tools/test/bin/onos-uninstall
+++ b/tools/test/bin/onos-uninstall
@@ -3,6 +3,24 @@
 # Remotely stops & uninstalls ONOS on the specified node.
 # -----------------------------------------------------------------------------
 
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0) [node]
+
+options:
+- [node] : The remote instance to uninstall ONOS from.
+
+summary:
+ Remotely stops and uninstalls ONOS on the specified node.
+
+ If [node] isn't specified, \$OCI becomes the target.
+
+_EOF_
+}
+
+[ "$1" = "-h" ] && _usage && exit 0
+
 [ ! -d "$ONOS_ROOT" ] && echo "ONOS_ROOT is not defined" >&2 && exit 1
 . $ONOS_ROOT/tools/build/envDefaults
 
diff --git a/tools/test/bin/onos-watch b/tools/test/bin/onos-watch
old mode 100755
new mode 100644
index 28e88c2..11962f9
--- a/tools/test/bin/onos-watch
+++ b/tools/test/bin/onos-watch
@@ -2,6 +2,30 @@
 # -----------------------------------------------------------------------------
 # Monitors selected set of ONOS commands using the system watch command.
 # -----------------------------------------------------------------------------
+function _usage () {
+cat << _EOF_
+usage:
+ $(basename $0) [node] <commands> [watchflags]
+
+options:
+- [node] <commands> : the node to run the commands against
+- [watchflags]      : flags to be passed to the watch command.
+
+summary:
+ Monitors selected set of ONOS commands using the system watch command.
+
+ <commands> is a comma-sepatarted list of ONOS CLI commands. If no commands
+ are supplied, the commands run are 'summary', 'intents', 'flows', and
+ 'hosts' against \$OCI.
+
+ Note that [watchflags] only applies to platforms with the Linux-like watch
+ command. For other platforms, the default behavior of watch (refresh every 2
+ s) is emulated.
+
+_EOF_
+}
+
+[ "$1" = "-h" ] && _usage && exit 0
 
 [ ! -d "$ONOS_ROOT" ] && echo "ONOS_ROOT is not defined" >&2 && exit 1
 . $ONOS_ROOT/tools/build/envDefaults
@@ -14,4 +38,10 @@
 trap "rm -f $aux" EXIT
 
 echo "$commands" | tr ',' '\n' > $aux
-watch $3 "onos $node -b <$aux 2>/dev/null"
+
+# emulate watch if not Linux.
+if [ "$(uname)" != "Linux" ]; then
+    while clear; "onos $node -b <$aux 2>/dev/null" ; do sleep 2; done
+else
+    watch $3 "onos $node -b <$aux 2>/dev/null"
+fi