automake: Program and Library Variables
1
1 8.4 Program and Library Variables
1 =================================
1
1 Associated with each program is a collection of variables that can be
1 used to modify how that program is built. There is a similar list of
1 such variables for each library. The canonical name of the program (or
1 library) is used as a base for naming these variables.
1
1 In the list below, we use the name “maude” to refer to the program or
1 library. In your ‘Makefile.am’ you would replace this with the
1 canonical name of your program. This list also refers to “maude” as a
1 program, but in general the same rules apply for both static and dynamic
1 libraries; the documentation below notes situations where programs and
1 libraries differ.
1
1 ‘maude_SOURCES’
1 This variable, if it exists, lists all the source files that are
1 compiled to build the program. These files are added to the
1 distribution by default. When building the program, Automake will
1 cause each source file to be compiled to a single ‘.o’ file (or
1 ‘.lo’ when using libtool). Normally these object files are named
1 after the source file, but other factors can change this. If a
1 file in the ‘_SOURCES’ variable has an unrecognized extension,
1 Automake will do one of two things with it. If a suffix rule
1 exists for turning files with the unrecognized extension into ‘.o’
1 files, then ‘automake’ will treat this file as it will any other
1 source file (⇒Support for Other Languages). Otherwise, the
1 file will be ignored as though it were a header file.
1
1 The prefixes ‘dist_’ and ‘nodist_’ can be used to control whether
1 files listed in a ‘_SOURCES’ variable are distributed. ‘dist_’ is
1 redundant, as sources are distributed by default, but it can be
1 specified for clarity if desired.
1
1 It is possible to have both ‘dist_’ and ‘nodist_’ variants of a
1 given ‘_SOURCES’ variable at once; this lets you easily distribute
1 some files and not others, for instance:
1
1 nodist_maude_SOURCES = nodist.c
1 dist_maude_SOURCES = dist-me.c
1
1 By default the output file (on Unix systems, the ‘.o’ file) will be
1 put into the current build directory. However, if the option
1 ‘subdir-objects’ is in effect in the current directory then the
1 ‘.o’ file will be put into the subdirectory named after the source
1 file. For instance, with ‘subdir-objects’ enabled,
1 ‘sub/dir/file.c’ will be compiled to ‘sub/dir/file.o’. Some people
1 prefer this mode of operation. You can specify ‘subdir-objects’ in
1 ‘AUTOMAKE_OPTIONS’ (⇒Options).
1
1 ‘EXTRA_maude_SOURCES’
1 Automake needs to know the list of files you intend to compile
1 _statically_. For one thing, this is the only way Automake has of
1 knowing what sort of language support a given ‘Makefile.in’
1 requires. (1) This means that, for example, you can’t put a
1 configure substitution like ‘@my_sources@’ into a ‘_SOURCES’
1 variable. If you intend to conditionally compile source files and
1 use ‘configure’ to substitute the appropriate object names into,
1 e.g., ‘_LDADD’ (see below), then you should list the corresponding
1 source files in the ‘EXTRA_’ variable.
1
1 This variable also supports ‘dist_’ and ‘nodist_’ prefixes. For
1 instance, ‘nodist_EXTRA_maude_SOURCES’ would list extra sources
1 that may need to be built, but should not be distributed.
1
1 ‘maude_AR’
1 A static library is created by default by invoking ‘$(AR)
1 $(ARFLAGS)’ followed by the name of the library and then the
1 objects being put into the library. You can override this by
1 setting the ‘_AR’ variable. This is usually used with C++; some
1 C++ compilers require a special invocation in order to instantiate
1 all the templates that should go into a library. For instance, the
1 SGI C++ compiler likes this variable set like so:
1 libmaude_a_AR = $(CXX) -ar -o
1
1 ‘maude_LIBADD’
1 Extra objects can be added to a _library_ using the ‘_LIBADD’
1 variable. For instance, this should be used for objects determined
1 by ‘configure’ (⇒A Library).
1
1 In the case of libtool libraries, ‘maude_LIBADD’ can also refer to
1 other libtool libraries.
1
1 ‘maude_LDADD’
1 Extra objects (‘*.$(OBJEXT)’) and libraries (‘*.a’, ‘*.la’) can be
1 added to a _program_ by listing them in the ‘_LDADD’ variable. For
1 instance, this should be used for objects determined by ‘configure’
1 (⇒Linking).
1
1 ‘_LDADD’ and ‘_LIBADD’ are inappropriate for passing
1 program-specific linker flags (except for ‘-l’, ‘-L’, ‘-dlopen’ and
1 ‘-dlpreopen’). Use the ‘_LDFLAGS’ variable for this purpose.
1
1 For instance, if your ‘configure.ac’ uses ‘AC_PATH_XTRA’, you could
1 link your program against the X libraries like so:
1
1 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
1
1 We recommend that you use ‘-l’ and ‘-L’ only when referring to
1 third-party libraries, and give the explicit file names of any
1 library built by your package. Doing so will ensure that
1 ‘maude_DEPENDENCIES’ (see below) is correctly defined by default.
1
1 ‘maude_LDFLAGS’
1 This variable is used to pass extra flags to the link step of a
1 program or a shared library. It overrides the ‘AM_LDFLAGS’
1 variable.
1
1 ‘maude_LIBTOOLFLAGS’
1 This variable is used to pass extra options to ‘libtool’. It
1 overrides the ‘AM_LIBTOOLFLAGS’ variable. These options are output
1 before ‘libtool’’s ‘--mode=MODE’ option, so they should not be
1 mode-specific options (those belong to the compiler or linker
1 flags). ⇒Libtool Flags.
1
1 ‘maude_DEPENDENCIES’
1 ‘EXTRA_maude_DEPENDENCIES’
1 It is also occasionally useful to have a target (program or
1 library) depend on some other file that is not actually part of
1 that target. This can be done using the ‘_DEPENDENCIES’ variable.
1 Each target depends on the contents of such a variable, but no
1 further interpretation is done.
1
1 Since these dependencies are associated to the link rule used to
1 create the programs they should normally list files used by the
1 link command. That is ‘*.$(OBJEXT)’, ‘*.a’, or ‘*.la’ files for
1 programs; ‘*.lo’ and ‘*.la’ files for Libtool libraries; and
1 ‘*.$(OBJEXT)’ files for static libraries. In rare cases you may
1 need to add other kinds of files such as linker scripts, but
1 _listing a source file in ‘_DEPENDENCIES’ is wrong_. If some
1 source file needs to be built before all the components of a
1 program are built, consider using the ‘BUILT_SOURCES’ variable
1 (⇒Sources).
1
1 If ‘_DEPENDENCIES’ is not supplied, it is computed by Automake.
1 The automatically-assigned value is the contents of ‘_LDADD’ or
1 ‘_LIBADD’, with most configure substitutions, ‘-l’, ‘-L’, ‘-dlopen’
1 and ‘-dlpreopen’ options removed. The configure substitutions that
1 are left in are only ‘$(LIBOBJS)’ and ‘$(ALLOCA)’; these are left
1 because it is known that they will not cause an invalid value for
1 ‘_DEPENDENCIES’ to be generated.
1
1 ‘_DEPENDENCIES’ is more likely used to perform conditional
1 compilation using an ‘AC_SUBST’ variable that contains a list of
DONTPRINTYET 1 objects. ⇒Conditional Sources, and *noteConditional
1DONTPRINTYET 1 objects. ⇒Conditional Sources, and ⇒Conditional
Libtool Sources.
1
1 The ‘EXTRA_*_DEPENDENCIES’ variable may be useful for cases where
1 you merely want to augment the ‘automake’-generated ‘_DEPENDENCIES’
1 variable rather than replacing it.
1
1 ‘maude_LINK’
1 You can override the linker on a per-program basis. By default the
1 linker is chosen according to the languages used by the program.
1 For instance, a program that includes C++ source code would use the
1 C++ compiler to link. The ‘_LINK’ variable must hold the name of a
1 command that can be passed all the ‘.o’ file names and libraries to
1 link against as arguments. Note that the name of the underlying
1 program is _not_ passed to ‘_LINK’; typically one uses ‘$@’:
1
1 maude_LINK = $(CCLD) -magic -o $@
1
1 If a ‘_LINK’ variable is not supplied, it may still be generated
1 and used by Automake due to the use of per-target link flags such
1 as ‘_CFLAGS’, ‘_LDFLAGS’ or ‘_LIBTOOLFLAGS’, in cases where they
1 apply.
1
1 ‘maude_CCASFLAGS’
1 ‘maude_CFLAGS’
1 ‘maude_CPPFLAGS’
1 ‘maude_CXXFLAGS’
1 ‘maude_FFLAGS’
1 ‘maude_GCJFLAGS’
1 ‘maude_LFLAGS’
1 ‘maude_OBJCFLAGS’
1 ‘maude_OBJCXXFLAGS’
1 ‘maude_RFLAGS’
1 ‘maude_UPCFLAGS’
1 ‘maude_YFLAGS’
1 Automake allows you to set compilation flags on a per-program (or
1 per-library) basis. A single source file can be included in
1 several programs, and it will potentially be compiled with
1 different flags for each program. This works for any language
1 directly supported by Automake. These “per-target compilation
1 flags” are ‘_CCASFLAGS’, ‘_CFLAGS’, ‘_CPPFLAGS’, ‘_CXXFLAGS’,
1 ‘_FFLAGS’, ‘_GCJFLAGS’, ‘_LFLAGS’, ‘_OBJCFLAGS’, ‘_OBJCXXFLAGS’,
1 ‘_RFLAGS’, ‘_UPCFLAGS’, and ‘_YFLAGS’.
1
1 When using a per-target compilation flag, Automake will choose a
1 different name for the intermediate object files. Ordinarily a
1 file like ‘sample.c’ will be compiled to produce ‘sample.o’.
1 However, if the program’s ‘_CFLAGS’ variable is set, then the
1 object file will be named, for instance, ‘maude-sample.o’. (See
1 also ⇒Renamed Objects).
1
1 In compilations with per-target flags, the ordinary ‘AM_’ form of
1 the flags variable is _not_ automatically included in the
1 compilation (however, the user form of the variable _is_ included).
1 So for instance, if you want the hypothetical ‘maude’ compilations
1 to also use the value of ‘AM_CFLAGS’, you would need to write:
1
1 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
1
1 ⇒Flag Variables Ordering, for more discussion about the
1 interaction between user variables, ‘AM_’ shadow variables, and
1 per-target variables.
1
1 ‘maude_SHORTNAME’
1 On some platforms the allowable file names are very short. In
1 order to support these systems and per-target compilation flags at
1 the same time, Automake allows you to set a “short name” that will
1 influence how intermediate object files are named. For instance,
1 in the following example,
1
1 bin_PROGRAMS = maude
1 maude_CPPFLAGS = -DSOMEFLAG
1 maude_SHORTNAME = m
1 maude_SOURCES = sample.c ...
1
1 the object file would be named ‘m-sample.o’ rather than
1 ‘maude-sample.o’.
1
1 This facility is rarely needed in practice, and we recommend
1 avoiding it until you find it is required.
1
1 ---------- Footnotes ----------
1
1 (1) There are other, more obscure reasons for this limitation as
1 well.
1