m4/README

   1 Many of the files in this directory are shared between the coreutils,
   2 diffutils, tar and gettext packages -- and others, so if you
   3 change them, try to ensure that you don't break those packages.
   4 That's hard without a systematic approach, but here is a set of conventions
   5 that makes it easy.
   6
   7 - The lib/ sources are split into modules.  Usually the module of a
   8   lib/foo.h and lib/foo.c is called "foo" - not unexpected, hey! -, but
   9   in more ambiguous cases you can look up the module a file belongs to
  10   by doing "grep lib/foo.c modules/*".
  11
  12 - For every module there is an autoconf macro file, usually called
  13   m4/foo.m4 according to the module name.  When you modify lib/foo.h or
  14   lib/foo.c, remember to modify m4/foo.m4 as well!
  15   What if you don't find m4/foo.m4? This probably means that the module
  16   doesn't need autoconf support up to now (again, take a look in modules/*).
  17   So you might need to create one.
  18
  19 - A module which defines a replacement function (i.e. a function which is
  20   compiled only on systems which lack it or where it exists but doesn't
  21   work satisfactorily) has a .m4 file with typically the following structure:
  22
  23   AC_DEFUN([gl_FUNC_FOO],
  24   [
  25     AC_REPLACE_FUNCS(foo)
  26     if test $ac_cv_func_foo = no; then
  27       gl_PREREQ_FOO
  28     fi
  29   ])
  30
  31   # Prerequisites of lib/foo.c.
  32   AC_DEFUN([gl_PREREQ_FOO], [
  33     dnl Many AC_CHECK_* invocations.
  34   ])
  35
  36 - A module which is compiled on all platforms can define multiple functions
  37   and be spread across multiple source files (although each time you do
  38   this you should consider splitting the module, if the source files could
  39   be independent). The .m4 file has typically the following structure:
  40
  41   AC_DEFUN([gl_FOO],
  42   [
  43     dnl Prerequisites of lib/foo.c.
  44     dnl Many AC_CHECK_* invocations.
  45
  46     dnl Prerequisites of lib/foobar.c.
  47     dnl Many AC_CHECK_* invocations.
  48   ])
  49
  50 - When a module FOO depends on a module BAR, you do *not* generally need
  51   to write
  52
  53   AC_DEFUN([gl_FOO],
  54   [
  55     AC_REQUIRE([gl_BAR])
  56     ...
  57   ])
  58
  59   because the maintainers might want to use locally modified / renamed copies
  60   of the module BAR.
  61
  62 - If the autoconf tests for the modules FOO and BAR have some checks in
  63   common, still list them separately. Autoconf has two mechanisms for
  64   avoiding that a configure file runs the same test twice: AC_REQUIRE
  65   and AC_CACHE_CHECK. Trying to omit the checks leads to maintenance
  66   problems: If FOO depends on BAR, and you omit a check from FOO's .m4 file,
  67   later on, when someone modifies bar.c and removes the check from bar.m4,
  68   he will not remember that foo.c needs the check as well.
  69
  70 - Now, how can you find the prerequisites of lib/foo.c? Try this:
  71     "grep '#.*if' lib/foo.c | grep -v endif"
  72   and for each HAVE_* macro search in the autoconf documentation what could
  73   be the autoconf macro that provides it. This is only an approximation; in
  74   general you should look at all preprocessor directives in lib/foo.c.
  75
  76 - In AC_RUN_IFELSE invocations, try to put as much information about failed
  77   tests as possible in the exit code. The exit code is 0 for success and any
  78   value between 1 and 127 for failure. The exit code is printed in config.log;
  79   therefore when an AC_RUN_IFELSE invocation failed, it is possible to analyze
  80   the failure immediately if sufficient information is contained in the exit
  81   code.
  82
  83   For a program that performs a single test, the typical idiom is:
  84
  85       if (do_test1 ())
  86         return 1;
  87       return 0;
  88
  89   For a test that performs a test with some preparation, the typical idiom is
  90   to return an enumerated value:
  91
  92       if (prep1 ())
  93         return 1;
  94       else if (prep2 ())
  95         return 2;
  96       else if (prep3 ())
  97         return 3;
  98       else if (do_test1 ())
  99         return 4;
 100       return 0;
 101
 102   For multiple independent tests in a single program, you can return a bit
 103   mask with up to 7 bits:
 104
 105       int result = 0;
 106       if (do_test1 ())
 107         result |= 1;
 108       if (do_test2 ())
 109         result |= 2;
 110       if (do_test3 ())
 111         result |= 4;
 112       return result;
 113
 114   For more than 7 independent tests, you have to map some possible test
 115   failures to same bit.
 116
 117 - After ANY modifications of an m4 file, you should increment its serial
 118   number (in the first line). Also, if this first line features a particular
 119   release, _remove_ this release stamp. Example: Change
 120
 121     # setenv.m4 serial 2 (gettext-0.11.1)
 122
 123   into
 124
 125     # setenv.m4 serial 3