Re: return values of test programs in *.m4 macros

[Bruno Haible]

Hi Eric, Ralf,

I've now pushed the big patch, with some explanations in m4/README (attached
below).

Ralf Wildenhues wrote:
> Well, I think what Eric was hinting at was that, for example, some tests
> in Autoconf's and Automake's own test suites interpret an exit status of
> 77 from a configure execution within that test run to infer that the
> test should be skipped.
> ...
> it wouldn't be a big leap to
> think that some gnulib-using packages interpreted an exit from configure
> with status 77 to infer some hint about skipping.

For me it is crystal clear that AC_RUN_IFELSE is a different
macro than Autoconf AT_* tests and Automake TESTS. Therefore I don't
know what you would like to see documented. But feel free to add some
wording to m4/README if that can avoid confusion.

> IMVHO a NEWS entry should be good enough to warn about this possible
> semantic change, however.

There is no semantic change, not even a "possible" semantic change.
The only thing that has changed is that exit codes printed in config.log
are different now. This is not worth stating in the NEWS file.

But again, if you think some wording is needed so that people don't
confuse configure-time tests with testsuite tests, please add it
to m4/README.

Bruno


2010-12-06  Bruno Haible  <address@hidden>

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

*** m4/README.orig      Mon Dec  6 23:16:50 2010
--- m4/README   Mon Dec  6 23:16:06 2010
***************
*** 73,78 ****
--- 73,119 ----
    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