make: Install Command Categories

1 
1 16.7 Install Command Categories
1 ===============================
1 
1 When writing the 'install' target, you must classify all the commands
1 into three categories: normal ones, "pre-installation" commands and
1 "post-installation" commands.
1 
1    Normal commands move files into their proper places, and set their
1 modes.  They may not alter any files except the ones that come entirely
1 from the package they belong to.
1 
1    Pre-installation and post-installation commands may alter other
1 files; in particular, they can edit global configuration files or data
1 bases.
1 
1    Pre-installation commands are typically executed before the normal
1 commands, and post-installation commands are typically run after the
1 normal commands.
1 
1    The most common use for a post-installation command is to run
1 'install-info'.  This cannot be done with a normal command, since it
1 alters a file (the Info directory) which does not come entirely and
1 solely from the package being installed.  It is a post-installation
1 command because it needs to be done after the normal command which
1 installs the package's Info files.
1 
1    Most programs don't need any pre-installation commands, but we have
1 the feature just in case it is needed.
1 
1    To classify the commands in the 'install' rule into these three
1 categories, insert "category lines" among them.  A category line
1 specifies the category for the commands that follow.
1 
1    A category line consists of a tab and a reference to a special Make
1 variable, plus an optional comment at the end.  There are three
1 variables you can use, one for each category; the variable name
1 specifies the category.  Category lines are no-ops in ordinary execution
1 because these three Make variables are normally undefined (and you
1 _should not_ define them in the makefile).
1 
1    Here are the three possible category lines, each with a comment that
1 explains what it means:
1 
1              $(PRE_INSTALL)     # Pre-install commands follow.
1              $(POST_INSTALL)    # Post-install commands follow.
1              $(NORMAL_INSTALL)  # Normal commands follow.
1 
1    If you don't use a category line at the beginning of the 'install'
1 rule, all the commands are classified as normal until the first category
1 line.  If you don't use any category lines, all the commands are
1 classified as normal.
1 
1    These are the category lines for 'uninstall':
1 
1              $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
1              $(POST_UNINSTALL)    # Post-uninstall commands follow.
1              $(NORMAL_UNINSTALL)  # Normal commands follow.
1 
1    Typically, a pre-uninstall command would be used for deleting entries
1 from the Info directory.
1 
1    If the 'install' or 'uninstall' target has any dependencies which act
1 as subroutines of installation, then you should start _each_
1 dependency's commands with a category line, and start the main target's
1 commands with a category line also.  This way, you can ensure that each
1 command is placed in the right category regardless of which of the
1 dependencies actually run.
1 
1    Pre-installation and post-installation commands should not run any
1 programs except for these:
1 
1      [ basename bash cat chgrp chmod chown cmp cp dd diff echo
1      egrep expand expr false fgrep find getopt grep gunzip gzip
1      hostname install install-info kill ldconfig ln ls md5sum
1      mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
1      test touch true uname xargs yes
1 
1    The reason for distinguishing the commands in this way is for the
1 sake of making binary packages.  Typically a binary package contains all
1 the executables and other files that need to be installed, and has its
1 own method of installing them--so it does not need to run the normal
1 installation commands.  But installing the binary package does need to
1 execute the pre-installation and post-installation commands.
1 
1    Programs to build binary packages work by extracting the
1 pre-installation and post-installation commands.  Here is one way of
1 extracting the pre-installation commands (the '-s' option to 'make' is
1 needed to silence messages about entering subdirectories):
1 
1      make -s -n install -o all \
1            PRE_INSTALL=pre-install \
1            POST_INSTALL=post-install \
1            NORMAL_INSTALL=normal-install \
1        | gawk -f pre-install.awk
1 
1 where the file 'pre-install.awk' could contain this:
1 
1      $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
1      on {print $0}
1      $0 ~ /^pre-install[ \t]*$/ {on = 1}
1