Update internal documentation.

* m4/README: Document new idioms for AC_RUN_IFELSE invocations.

diff --git a/ChangeLog b/ChangeLog
index 606d9bb0d78eecbe453909ca283e1fb28a85fa90..fc04230a1b557618dab1e61adfb2c876bc42df26 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2010-12-06  Bruno Haible  <bruno@clisp.org>
+
+       Update internal documentation.
+       * m4/README: Document new idioms for AC_RUN_IFELSE invocations.
+
 2010-12-04  Bruno Haible  <bruno@clisp.org>
 
        Put more information about failed tests into the test return codes.

diff --git a/m4/README b/m4/README
index 964c5981d2fea78b1c9f7249a95b71c67342189c..18ed6e728c6239e81615cf9f57935b67bf66b788 100644 (file)
--- a/m4/README
+++ b/m4/README
@@ -73,6 +73,47 @@ that makes it easy.
   be the autoconf macro that provides it. This is only an approximation; in
   general you should look at all preprocessor directives in lib/foo.c.
 
+- In AC_RUN_IFELSE invocations, try to put as much information about failed
+  tests as possible in the exit code. The exit code is 0 for success and any
+  value between 1 and 127 for failure. The exit code is printed in config.log;
+  therefore when an AC_RUN_IFELSE invocation failed, it is possible to analyze
+  the failure immediately if sufficient information is contained in the exit
+  code.
+
+  For a program that performs a single test, the typical idiom is:
+
+      if (do_test1 ())
+        return 1;
+      return 0;
+
+  For a test that performs a test with some preparation, the typical idiom is
+  to return an enumerated value:
+
+      if (prep1 ())
+        return 1;
+      else if (prep2 ())
+        return 2;
+      else if (prep3 ())
+        return 3;
+      else if (do_test1 ())
+        return 4;
+      return 0;
+
+  For multiple independent tests in a single program, you can return a bit
+  mask with up to 7 bits:
+
+      int result = 0;
+      if (do_test1 ())
+        result |= 1;
+      if (do_test2 ())
+        result |= 2;
+      if (do_test3 ())
+        result |= 4;
+      return result;
+
+  For more than 7 independent tests, you have to map some possible test
+  failures to same bit.
+
 - After ANY modifications of an m4 file, you should increment its serial
   number (in the first line). Also, if this first line features a particular
   release, _remove_ this release stamp. Example: Change