cs-hosts-list: Document the --arches, --kernels and --suites options

These have a rather counterintuitive behaviour which is nevertheless
useful.  Document it, and the reasoning.

CC: Roger Pau Monne <roger.pau@citrix.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>

diff --git a/cs-hosts-list b/cs-hosts-list
index 16b52192dbebae7c6b4d94c054244160df647d9e..306b04ea0d369b733b8031b68814fc43e2f0dfe5 100755 (executable)
--- a/cs-hosts-list
+++ b/cs-hosts-list
@@ -22,6 +22,43 @@
 # prints the names of all hosts which have all of the HOSTFLAGs set,
 # one per line
 
+# options
+#
+#    --arches=ARCH,...
+#             For each host, also print an architecture and a kernel
+#             which are suitable for use with the host (with spaces in
+#             between).  "Suitable" means that the the hostflag
+#             arch-[KERNEL-]ARCH is set, where [KERNEL-] means "linux".
+#
+#             If there is no suitable arch/kernel combination, prints
+#             "NONE NONE" instead.  NB, such hosts are not
+#             excluded from the list.
+#
+#             The arch/kernel search loops over kernels (see
+#             --kernels), and for each kernel loops over arches (in
+#             the order specified here), and stops at the first match.
+#             Ie the kernel ordering takes priority.
+#
+#    --kernels=KERNEL,...
+#             Specifies an alternative list of kernels to try.
+#             The default is "xen" and "linux".
+#             Ignored unless --arches also specified.
+#
+#    --suites=SUITE,....
+#             For each host, also print a Debian suite which is
+#             suitable for use with the host.  "Suitable" means
+#             the hostflag suite-SUITE is set.  If there is no
+#             suitable suite, prints "NONE" instead.
+#
+#             May be combined with --arches.  The output for
+#             --arches always comes first.
+#
+# We still list hosts for which some of the requested information is
+# lacking because such a situation would represent some kind of
+# misconfiguration.  Printing NONE will cause a consumer such as
+# make-hosts-flight to generate jobs which will fail, rather than
+# simply ignoring the problem.
+
 use strict qw(vars);
 use DBI;
 unshift @INC, qw(.);