8.6 Special handling for LIBOBJS and ALLOCA

The ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables list object files that should be compiled into the project to provide an implementation for functions that are missing or broken on the host system. They are substituted by ‘configure’.

These variables are defined by Autoconf macros such as AC_LIBOBJ, AC_REPLACE_FUNCS (see (autoconf)Generic Functions section `Generic Function Checks' in The Autoconf Manual), or AC_FUNC_ALLOCA (see (autoconf)Particular Functions section `Particular Function Checks' in The Autoconf Manual). Many other Autoconf macros call AC_LIBOBJ or AC_REPLACE_FUNCS to populate ‘$(LIBOBJS)’.

Using these variables is very similar to doing conditional compilation using AC_SUBST variables, as described in Conditional compilation of sources. That is, when building a program, ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ should be added to the associated ‘*_LDADD’ variable, or to the ‘*_LIBADD’ variable when building a library. However there is no need to list the corresponding sources in ‘EXTRA_*_SOURCES’ nor to define ‘*_DEPENDENCIES’. Automake automatically adds ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ to the dependencies, and it will discover the list of corresponding source files automatically (by tracing the invocations of the AC_LIBSOURCE Autoconf macros). However, if you have already defined ‘*_DEPENDENCIES’ explicitly for an unrelated reason, then you have to add these variables manually.

These variables are usually used to build a portability library that is linked with all the programs of the project. We now review a sample setup. First, ‘configure.ac’ contains some checks that affect either LIBOBJS or ALLOCA.

# configure.ac
…
AC_CONFIG_LIBOBJ_DIR([lib])
…
AC_FUNC_MALLOC             dnl May add malloc.$(OBJEXT) to LIBOBJS
AC_FUNC_MEMCMP             dnl May add memcmp.$(OBJEXT) to LIBOBJS
AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
AC_FUNC_ALLOCA             dnl May add alloca.$(OBJEXT) to ALLOCA
…
AC_CONFIG_FILES([
  lib/Makefile
  src/Makefile
])
AC_OUTPUT

The AC_CONFIG_LIBOBJ_DIR tells Autoconf that the source files of these object files are to be found in the ‘lib/’ directory. Automake can also use this information, otherwise it expects the source files are to be in the directory where the ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables are used.

The ‘lib/’ directory should therefore contain ‘malloc.c’, ‘memcmp.c’, ‘strdup.c’, ‘alloca.c’. Here is its ‘Makefile.am’:

# lib/Makefile.am

noinst_LIBRARIES = libcompat.a
libcompat_a_SOURCES =
libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)

The library can have any name, of course, and anyway it is not going to be installed: it just holds the replacement versions of the missing or broken functions so we can later link them in. Many projects also include extra functions, specific to the project, in that library: they are simply added on the _SOURCES line.

There is a small trap here, though: ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ might be empty, and building an empty library is not portable. You should ensure that there is always something to put in ‘libcompat.a’. Most projects will also add some utility functions in that directory, and list them in libcompat_a_SOURCES, so in practice ‘libcompat.a’ cannot be empty.

Finally here is how this library could be used from the ‘src/’ directory.

# src/Makefile.am

# Link all programs in this directory with libcompat.a
LDADD = ../lib/libcompat.a

bin_PROGRAMS = tool1 tool2 …
tool1_SOURCES = …
tool2_SOURCES = …

When option ‘subdir-objects’ is not used, as in the above example, the variables ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ can only be used in the directory where their sources lie. E.g., here it would be wrong to use ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ in ‘src/Makefile.am’. However if both ‘subdir-objects’ and AC_CONFIG_LIBOBJ_DIR are used, it is OK to use these variables in other directories. For instance ‘src/Makefile.am’ could be changed as follows.

# src/Makefile.am

AUTOMAKE_OPTIONS = subdir-objects
LDADD = $(LIBOBJS) $(ALLOCA)

bin_PROGRAMS = tool1 tool2 …
tool1_SOURCES = …
tool2_SOURCES = …

Because ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ contain object file names that end with ‘.$(OBJEXT)’, they are not suitable for Libtool libraries (where the expected object extension is ‘.lo’): LTLIBOBJS and LTALLOCA should be used instead.

LTLIBOBJS is defined automatically by Autoconf and should not be defined by hand (as in the past), however at the time of writing LTALLOCA still needs to be defined from ALLOCA manually. See (autoconf)AC_LIBOBJ vs LIBOBJS section `AC_LIBOBJ vs. LIBOBJS' in The Autoconf Manual.