automake: Extending

1 
1 23.1 Extending Automake Rules
1 =============================
1 
1 With some minor exceptions (for example ‘_PROGRAMS’ variables, ‘TESTS’,
1 or ‘XFAIL_TESTS’) being rewritten to append ‘$(EXEEXT)’), the contents
1 of a ‘Makefile.am’ is copied to ‘Makefile.in’ verbatim.
1 
1    These copying semantics mean that many problems can be worked around
1 by simply adding some ‘make’ variables and rules to ‘Makefile.am’.
1 Automake will ignore these additions.
1 
1    Since a ‘Makefile.in’ is built from data gathered from three
1 different places (‘Makefile.am’, ‘configure.ac’, and ‘automake’ itself),
1 it is possible to have conflicting definitions of rules or variables.
1 When building ‘Makefile.in’ the following priorities are respected by
1 ‘automake’ to ensure the user always has the last word:
1 
1    • User defined variables in ‘Makefile.am’ have priority over
1      variables ‘AC_SUBST’ed from ‘configure.ac’, and ‘AC_SUBST’ed
1      variables have priority over ‘automake’-defined variables.
1    • As far as rules are concerned, a user-defined rule overrides any
1      ‘automake’-defined rule for the same target.
1 
1    These overriding semantics make it possible to fine tune some default
1 settings of Automake, or replace some of its rules.  Overriding Automake
1 rules is often inadvisable, particularly in the topmost directory of a
11 package with subdirectories.  The ‘-Woverride’ option (⇒automake
 Invocation) comes in handy to catch overridden definitions.
1 
1    Note that Automake does not make any distinction between rules with
1 commands and rules that only specify dependencies.  So it is not
1 possible to append new dependencies to an ‘automake’-defined target
1 without redefining the entire rule.
1 
1    However, various useful targets have a ‘-local’ version you can
1 specify in your ‘Makefile.am’.  Automake will supplement the standard
1 target with these user-supplied targets.
1 
1    The targets that support a local version are ‘all’, ‘info’, ‘dvi’,
1 ‘ps’, ‘pdf’, ‘html’, ‘check’, ‘install-data’, ‘install-dvi’,
1 ‘install-exec’, ‘install-html’, ‘install-info’, ‘install-pdf’,
1 ‘install-ps’, ‘uninstall’, ‘installdirs’, ‘installcheck’ and the various
1 ‘clean’ targets (‘mostlyclean’, ‘clean’, ‘distclean’, and
1 ‘maintainer-clean’).
1 
1    Note that there are no ‘uninstall-exec-local’ or
1 ‘uninstall-data-local’ targets; just use ‘uninstall-local’.  It doesn’t
1 make sense to uninstall just data or just executables.
1 
1    For instance, here is one way to erase a subdirectory during ‘make
1 clean’ (⇒Clean).
1 
1      clean-local:
1              -rm -rf testSubDir
1 
1    You may be tempted to use ‘install-data-local’ to install a file to
11 some hard-coded location, but you should avoid this (⇒Hard-Coded
 Install Paths).
1 
1    With the ‘-local’ targets, there is no particular guarantee of
1 execution order; typically, they are run early, but with parallel make,
1 there is no way to be sure of that.
1 
1    In contrast, some rules also have a way to run another rule, called a
1 “hook”; hooks are always executed after the main rule’s work is done.
1 The hook is named after the principal target, with ‘-hook’ appended.
1 The targets allowing hooks are ‘install-data’, ‘install-exec’,
1 ‘uninstall’, ‘dist’, and ‘distcheck’.
1 
1    For instance, here is how to create a hard link to an installed
1 program:
1 
1      install-exec-hook:
1              ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
1                 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
1 
1    Although cheaper and more portable than symbolic links, hard links
1 will not work everywhere (for instance, OS/2 does not have ‘ln’).
1 Ideally you should fall back to ‘cp -p’ when ‘ln’ does not work.  An
1 easy way, if symbolic links are acceptable to you, is to add
11 ‘AC_PROG_LN_S’ to ‘configure.ac’ (⇒Particular Program Checks
 (autoconf)Particular Programs.) and use ‘$(LN_S)’ in ‘Makefile.am’.
1 
1    For instance, here is how you could install a versioned copy of a
1 program using ‘$(LN_S)’:
1 
1      install-exec-hook:
1              cd $(DESTDIR)$(bindir) && \
1                mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
1                $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
1 
1    Note that we rename the program so that a new version will erase the
1 symbolic link, not the real binary.  Also we ‘cd’ into the destination
1 directory in order to create relative links.
1 
1    When writing ‘install-exec-hook’ or ‘install-data-hook’, please bear
1 in mind that the exec/data distinction is based on the installation
1 directory, not on the primary used (⇒The Two Parts of Install).
1 So a ‘foo_SCRIPTS’ will be installed by ‘install-data’, and a
1 ‘barexec_SCRIPTS’ will be installed by ‘install-exec’.  You should
1 define your hooks consequently.
1