init.sh: improve comments

* tests/init.sh: Recommend the one-line init.sh-sourcing idiom:
. "${srcdir=.}/init.sh"; path_prepend_ .
Add a note about path_prepend_ and the alternative of using
TESTS_ENVIRONMENT.

diff --git a/ChangeLog b/ChangeLog
index 4581ef9d319c1f67dbcec6e98f2315c54a01e519..1f55576ad7a46e1ced131ab4f62126d92a3e0fb9 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2010-05-07  Jim Meyering  <meyering@redhat.com>
+
+       init.sh: improve comments
+       * tests/init.sh: Recommend the one-line init.sh-sourcing idiom:
+       . "${srcdir=.}/init.sh"; path_prepend_ .
+       Add a note about path_prepend_ and the alternative of using
+       TESTS_ENVIRONMENT.
+
 2010-05-06  Sergey Poznyakoff  <gray@gnu.org.ua>
 
        exclude: Unescape hashed patterns in wildcard mode.

diff --git a/tests/init.sh b/tests/init.sh
index 512e8763846846c1182353b38023ce68e3ffe52c..777273697011883491a2a8111b3d6cb18c9eb0e5 100644 (file)
--- a/tests/init.sh
+++ b/tests/init.sh
@@ -21,11 +21,16 @@
 # The typical skeleton of a test looks like this:
 #
 #   #!/bin/sh
-#   : ${srcdir=.}
-#   . "$srcdir/init.sh"; path_prepend_ .
+#   . "${srcdir=.}/init.sh"; path_prepend_ .
 #   Execute some commands.
 #   Note that these commands are executed in a subdirectory, therefore you
 #   need to prepend "../" to relative filenames in the build directory.
+#   Note that the "path_prepend_ ." is useful only if the body of your
+#   test invokes programs residing in the initial directory.
+#   For example, if the programs you want to test are in src/, and this test
+#   script is named tests/test-1, then you would use "path_prepend_ ../src",
+#   or perhaps export PATH='$(abs_top_builddir)/src$(PATH_SEPARATOR)'"$$PATH"
+#   to all tests via automake's TESTS_ENVIRONMENT.
 #   Set the exit code 0 for success, 77 for skipped, or 1 or other for failure.
 #   Use the skip_ and fail_ functions to print a diagnostic and then exit
 #   with the corresponding exit code.