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
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/*".
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.
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:
23 AC_DEFUN([gl_FUNC_FOO],
26 if test $ac_cv_func_foo = no; then
31 # Prerequisites of lib/foo.c.
32 AC_DEFUN([gl_PREREQ_FOO], [
33 dnl Many AC_CHECK_* invocations.
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:
43 dnl Prerequisites of lib/foo.c.
44 dnl Many AC_CHECK_* invocations.
46 dnl Prerequisites of lib/foobar.c.
47 dnl Many AC_CHECK_* invocations.
50 - When a module FOO depends on a module BAR, you do *not* generally need
59 because the maintainers might want to use locally modified / renamed copies
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.
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.
76 - After ANY modifications of an m4 file, you should increment its serial
77 number (in the first line). Also, if this first line features a particular
78 release, _remove_ this release stamp. Example: Change
80 # setenv.m4 serial 2 (gettext-0.11.1)