automake: LIBOBJS

1 
1 8.6 Special handling for ‘LIBOBJS’ and ‘ALLOCA’
1 ===============================================
1 
1 The ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables list object files that should
1 be compiled into the project to provide an implementation for functions
1 that are missing or broken on the host system.  They are substituted by
1 ‘configure’.
1 
1    These variables are defined by Autoconf macros such as ‘AC_LIBOBJ’,
DONTPRINTYET 11 ‘AC_REPLACE_FUNCS’ (⇒Generic Function Checks (autoconf)Generic
 Functions.), or ‘AC_FUNC_ALLOCA’ (*noteParticular Function Checks:
1DONTPRINTYET 11 ‘AC_REPLACE_FUNCS’ (⇒Generic Function Checks (autoconf)Generic
 Functions.), or ‘AC_FUNC_ALLOCA’ (⇒Particular Function Checks

 (autoconf)Particular Functions.).  Many other Autoconf macros call
1 ‘AC_LIBOBJ’ or ‘AC_REPLACE_FUNCS’ to populate ‘$(LIBOBJS)’.
1 
1    Using these variables is very similar to doing conditional
11 compilation using ‘AC_SUBST’ variables, as described in ⇒
 Conditional Sources.  That is, when building a program, ‘$(LIBOBJS)’
1 and ‘$(ALLOCA)’ should be added to the associated ‘*_LDADD’ variable, or
1 to the ‘*_LIBADD’ variable when building a library.  However there is no
1 need to list the corresponding sources in ‘EXTRA_*_SOURCES’ nor to
1 define ‘*_DEPENDENCIES’.  Automake automatically adds ‘$(LIBOBJS)’ and
1 ‘$(ALLOCA)’ to the dependencies, and it will discover the list of
1 corresponding source files automatically (by tracing the invocations of
1 the ‘AC_LIBSOURCE’ Autoconf macros).  If you have already defined
1 ‘*_DEPENDENCIES’ explicitly for an unrelated reason, then you either
1 need to add these variables manually, or use ‘EXTRA_*_DEPENDENCIES’
1 instead of ‘*_DEPENDENCIES’.
1 
1    These variables are usually used to build a portability library that
1 is linked with all the programs of the project.  We now review a sample
1 setup.  First, ‘configure.ac’ contains some checks that affect either
1 ‘LIBOBJS’ or ‘ALLOCA’.
1 
1      # configure.ac
1      ...
1      AC_CONFIG_LIBOBJ_DIR([lib])
1      ...
1      AC_FUNC_MALLOC             dnl May add malloc.$(OBJEXT) to LIBOBJS
1      AC_FUNC_MEMCMP             dnl May add memcmp.$(OBJEXT) to LIBOBJS
1      AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
1      AC_FUNC_ALLOCA             dnl May add alloca.$(OBJEXT) to ALLOCA
1      ...
1      AC_CONFIG_FILES([
1        lib/Makefile
1        src/Makefile
1      ])
1      AC_OUTPUT
1 
1    The ‘AC_CONFIG_LIBOBJ_DIR’ tells Autoconf that the source files of
1 these object files are to be found in the ‘lib/’ directory.  Automake
1 can also use this information, otherwise it expects the source files are
1 to be in the directory where the ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables
1 are used.
1 
1    The ‘lib/’ directory should therefore contain ‘malloc.c’, ‘memcmp.c’,
1 ‘strdup.c’, ‘alloca.c’.  Here is its ‘Makefile.am’:
1 
1      # lib/Makefile.am
1 
1      noinst_LIBRARIES = libcompat.a
1      libcompat_a_SOURCES =
1      libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
1 
1    The library can have any name, of course, and anyway it is not going
1 to be installed: it just holds the replacement versions of the missing
1 or broken functions so we can later link them in.  Many projects also
1 include extra functions, specific to the project, in that library: they
1 are simply added on the ‘_SOURCES’ line.
1 
1    There is a small trap here, though: ‘$(LIBOBJS)’ and ‘$(ALLOCA)’
1 might be empty, and building an empty library is not portable.  You
1 should ensure that there is always something to put in ‘libcompat.a’.
1 Most projects will also add some utility functions in that directory,
1 and list them in ‘libcompat_a_SOURCES’, so in practice ‘libcompat.a’
1 cannot be empty.
1 
1    Finally here is how this library could be used from the ‘src/’
1 directory.
1 
1      # src/Makefile.am
1 
1      # Link all programs in this directory with libcompat.a
1      LDADD = ../lib/libcompat.a
1 
1      bin_PROGRAMS = tool1 tool2 ...
1      tool1_SOURCES = ...
1      tool2_SOURCES = ...
1 
1    When option ‘subdir-objects’ is not used, as in the above example,
1 the variables ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ can only be used in the
1 directory where their sources lie.  E.g., here it would be wrong to use
1 ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ in ‘src/Makefile.am’.  However if both
1 ‘subdir-objects’ and ‘AC_CONFIG_LIBOBJ_DIR’ are used, it is OK to use
1 these variables in other directories.  For instance ‘src/Makefile.am’
1 could be changed as follows.
1 
1      # src/Makefile.am
1 
1      AUTOMAKE_OPTIONS = subdir-objects
1      LDADD = $(LIBOBJS) $(ALLOCA)
1 
1      bin_PROGRAMS = tool1 tool2 ...
1      tool1_SOURCES = ...
1      tool2_SOURCES = ...
1 
1    Because ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ contain object file names that
1 end with ‘.$(OBJEXT)’, they are not suitable for Libtool libraries
1 (where the expected object extension is ‘.lo’): ‘LTLIBOBJS’ and
1 ‘LTALLOCA’ should be used instead.
1 
1    ‘LTLIBOBJS’ is defined automatically by Autoconf and should not be
1 defined by hand (as in the past), however at the time of writing
11 ‘LTALLOCA’ still needs to be defined from ‘ALLOCA’ manually.  ⇒
 ‘AC_LIBOBJ’ vs. ‘LIBOBJS’ (autoconf)AC_LIBOBJ vs LIBOBJS.
1