From: Bruno Haible <bruno@clisp.org>
Date: Mon, 6 Dec 2010 22:17:12 +0000 (+0100)
Subject: Update internal documentation.
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=19ce3a779b841b64c3f69038efbd7c36834fe260;p=pspp

Update internal documentation.

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

diff --git a/ChangeLog b/ChangeLog
index 606d9bb0d7..fc04230a1b 100644
--- 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 964c5981d2..18ed6e728c 100644
--- 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