Re: Use of config.h: summary of responses.

[Daniel Reed]

On 2004-09-14T10:14+0900, Andre Caldas wrote:
) > The former can be mitigated by having libexample's developers distribute a
) > libexample.m4 file which can be referenced during example-util's build
) > environment setup, to avoid requiring that example-util's developers track
) > libexample's individual requirements.
) But this also means that I have to learn how to write *.m4 files :-(

If you've ever written a configure source file, you already know basic m4 :)


) Can you give me some hints on:
)       * How to write this libexample.m4 ( a kind of sketch )

A highly-available example might be libtool:

To use libtool in your package, you add "AC_PROG_LIBTOOL" to your configure
source file (configure.in or configure.ac). This macro is not actually a
part of core autoconf; it is defined in a libtool.m4 file that is
distributed with the libtool package.

The autotools can pull macro definitions from files installed in autoconf's
or automake's macro directories (/usr/share/autoconf and
/usr/share/aclocal); in a directory specified on the command line of
"aclocal"; in the "acinclude.m4" file in your project's top-level directory;
or in the directory named by the AC_CONFIG_MACRO_DIR macro in your configure
source file.

The first two locations are relevant for packages that will be highly
available on the machines of developers of your package who might want to
modify your autotools source files (and generate configure, Makefile.in,
etc.). The last two locations are available if you want to guarantee the
macros will be available regardless of your developers' system environments.
The choice of distributing a dependency's macro files with your package does
not impact people compiling your package; it only affects people who will be
autoreconfing your package.

For example, you probably would not distribute libtool.m4 in either your
acinclude.m4 or your m4/ subdirectory, as it is very likely to be installed
on anyone's machine who uses the autotools. However, if your package
example-util has an optional dependency on liboptional, you may want to
distribute liboptional.m4 in your acinclude.m4 or m4/ subdirectory in case a
contributor does not have liboptional installed but wishes to autoreconf.
(And in some situations it may be that you need to distribute a stub macro
file that only calls into the actual liboptional.m4's routines if
liboptional.m4 is present, possibly depending on how weighty liboptional.m4
is.)


libexample's packaging might install libexample.m4 into /usr/share/aclocal
to provide a macro AC_LIB_EXAMPLE. This macro could AC_REQUIRE other
autoconf macros, call AC_CHECK_HEADERS, AC_TRY_LINK, AC_DEFINE, modify
CPPFLAGS, etc.--whatever is needed to guarantee that the minimum build
environment requirements are met for using libexample. (While still keeping
in mind that other software might be built in the same environment.)


(There may be other less-complicated m4 scripts already installed in your
/usr/share/autoconf or /usr/share/aclocal directories that can be useful
studies for self teaching m4.)


)       * How to install libexample.m4
)       * Where to install the *.m4 file

I believe there exists an automake target "aclocal_DATA" which can handle
this for you.

libtool's top-level Makefile.am includes a line equivalent to:
aclocal_DATA = libtool.m4 ltdl.m4


)       * Whether I should or not include a #ifdef HAVECONFIG_H in my installed
) headers

I would discourage any use of autoheader-generated headers in your interface
files. Try to make your interfaces completely ignorant of your actual
[eventual] build environment's characteristics, and instead depend on a
specific type of environment (in terms of a set of guarantees). Use your
example.m4 and AC_PROG_EXAMPLE to provide that environment (satisfy those
guarantees, or error if they are not satisfiable). Document the environment
you design for, for the benefit of dependent packages that do not use the
autotools (and hence do not use your m4 file).


For HAVE_CONFIG_H in particular, consider the following:

libexample.h uses #ifdef HAVE_CONFIG_H and includes extra code to change the
substance of the interface (API) based on preprocessor macros it expects to
be in its config.h.

example-util has its own config.h, which does not have all the same macros
libexample's config.h has. When libexample.h is included in example-util.c,
HAVE_CONFIG_H is defined, but "config.h" is not the "right" config.h file.

This can not be avoided by duplicating, in libexample.m4, the autoconf
checks libexample.h expects to populate config.h, as it is not universally
reasonable to require that all dependent projects use the autotools as their
build system. Your interfaces should "work" if used in the environment they
are designed for. This environment can happen by chance, or be created by
specific action on the part of a software builder, *or* it can be created by
the autotools. Hence, your interfaces should work even if the autotools are
not in use.


) Writing this e-mail I just realized that if there is a standard way to
) create and install libexample.m4 then most of the problems can be
) solved. Does this standard way exists?

I am not sure if there might be an automatable method of generating a
package-specific m4 file, no. That might be an interesting area to research.

-- 
Daniel Reed <address@hidden>    http://people.redhat.com/djr/   
http://naim.n.ml.org/
The pursuit of pretty formulas and neat theorems can no doubt quickly
degenerate into a silly vice, but so can the quest for austere
generalities which are so very general indeed that they are incapable
of application to any particular. -- Eric Temple Bell, Mathematician