@end ifclear
@end iftex
describes conventions for writing the Makefiles for GNU programs.
+Using Automake will help you write a Makefile that follows these
+conventions.
@menu
* Makefile Basics:: General Conventions for Makefiles
* Command Variables:: Variables for Specifying Commands
* Directory Variables:: Variables for Installation Directories
* Standard Targets:: Standard Targets for Users
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
@end menu
@node Makefile Basics
of the source code. Without one of these prefixes, the current search
path is used.
-The distinction between @file{./} and @file{$(srcdir)/} is important
-when using the @samp{--srcdir} option to @file{configure}. A rule of
-the form:
+The distinction between @file{./} (the @dfn{build directory}) and
+@file{$(srcdir)/} (the @dfn{source directory}) is important because
+users can build in a separate directory using the @samp{--srcdir} option
+to @file{configure}. A rule of the form:
@smallexample
foo.1 : foo.man sedscript
@end smallexample
@noindent
-will fail when the current directory is not the source directory,
-because @file{foo.man} and @file{sedscript} are not in the current
-directory.
+will fail when the build directory is not the source directory, because
+@file{foo.man} and @file{sedscript} are in the the source directory.
When using GNU @code{make}, relying on @samp{VPATH} to find the source
file will work in the case where there is a single dependency file,
sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
@end smallexample
+GNU distributions usually contain some files which are not source
+files---for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex. Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory. So Makefile rules to update them should put the
+updated files in the source directory.
+
+However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
Try to make the build and installation targets, at least (and all their
subtargets) work correctly with a parallel @code{make}.
The @code{configure} script and the Makefile rules for building and
installation should not use any utilities directly except these:
+@c dd find
+@c gunzip gzip md5sum
+@c mkfifo mknod tee uname
+
@example
-cat cmp cp echo egrep expr false grep
-ln mkdir mv pwd rm rmdir sed test touch true
+cat cmp cp diff echo egrep expr false grep install-info
+ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
@end example
+The compression program @code{gzip} can be used in the @code{dist} rule.
+
Stick to the generally supported options for these programs. For
example, don't use @samp{mkdir -p}, convenient as it may be, because
most systems don't support it.
mean:
@example
-ar bison cc flex install ld lex
+ar bison cc flex install ld ldconfig lex
make makeinfo ranlib texi2dvi yacc
@end example
-Use the following @code{make} variables:
+Use the following @code{make} variables to run those programs:
@example
-$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX)
+$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
@end example
-When you use @code{ranlib}, you should make sure nothing bad happens if
-the system does not have @code{ranlib}. Arrange to ignore an error
-from that command, and print a message before the command to tell the
-user that failure of the @code{ranlib} command does not mean a problem.
-(The Autoconf @samp{AC_PROG_RANLIB} macro can help with this.)
+When you use @code{ranlib} or @code{ldconfig}, you should make sure
+nothing bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
+this.)
If you use symbolic links, you should implement a fallback for systems
that don't have symbolic links.
+Additional utilities that can be used via Make variables are:
+
+@example
+chgrp chmod chown mknod
+@end example
+
It is ok to use other utilities in Makefile portions (or scripts)
intended only for particular systems where you know those utilities
exist.
Each program-name variable should come with an options variable that is
used to supply options to the program. Append @samp{FLAGS} to the
program-name variable name to get the options variable name---for
-example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to
-this rule, but we keep it because it is standard.) Use @code{CPPFLAGS}
-in any compilation command that runs the preprocessor, and use
-@code{LDFLAGS} in any compilation command that does linking as well as
-in any direct use of @code{ld}.
+example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C
+compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
+exceptions to this rule, but we keep them because they are standard.)
+Use @code{CPPFLAGS} in any compilation command that runs the
+preprocessor, and use @code{LDFLAGS} in any compilation command that
+does linking as well as in any direct use of @code{ld}.
If there are C compiler options that @emph{must} be used for proper
compilation of certain files, do not include them in @code{CFLAGS}.
containing compiler options, so the user can use @code{CFLAGS} to
override the others.
+@code{CFLAGS} should be used in every invocation of the C compiler,
+both those which do compilation and those which do linking.
+
Every Makefile should define the variable @code{INSTALL}, which is the
basic command for installing a file into the system.
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
@end example
+Optionally, you may prepend the value of @code{DESTDIR} to the target
+filename. Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later. Do not
+set the value of @code{DESTDIR} in your Makefile, and do not include it
+in any installed files. With support for @code{DESTDIR}, the above
+examples become:
+
+@example
+$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+@end example
+
@noindent
Always use a file name, not a directory name, as the second argument of
the installation commands. Use a separate command for each file to be
@file{/usr} will be a symbolic link to @file{/}.
(If you are using Autoconf, write it as @samp{@@prefix@@}.)
+Running @samp{make install} with a different value of @code{prefix}
+from the one used to build the program should @var{not} recompile
+the program.
+
@item exec_prefix
A prefix used in constructing the default values of some of the
variables listed below. The default value of @code{exec_prefix} should
Generally, @code{$(exec_prefix)} is used for directories that contain
machine-specific files (such as executables and subroutine libraries),
while @code{$(prefix)} is used directly for other directories.
+
+Running @samp{make install} with a different value of @code{exec_prefix}
+from the one used to build the program should @var{not} recompile the
+program.
@end table
Executable programs are installed in one of the following directories.
write it as @file{$(prefix)/etc}.
(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
-@c rewritten to avoid overfull hbox --tower
-Do not install executables
-@c here
-in this directory (they probably
-belong in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not
-install files that are modified in the normal course of their use
-(programs whose purpose is to change the configuration of the system
-excluded). Those probably belong in @file{$(localstatedir)}.
+Do not install executables here in this directory (they probably belong
+in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install
+files that are modified in the normal course of their use (programs
+whose purpose is to change the configuration of the system excluded).
+Those probably belong in @file{$(localstatedir)}.
@item sharedstatedir
The directory for installing architecture-independent data files which
as @file{$(prefix)/info}.
(If you are using Autoconf, write it as @samp{@@infodir@@}.)
+@item lispdir
+The directory for installing any Emacs Lisp files in this package. By
+default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
+should be written as @file{$(prefix)/share/emacs/site-lisp}.
+
+If you are using Autoconf, write the default as @samp{@@lispdir@@}.
+In order to make @samp{@@lispdir@@} work, you need the following lines
+in your @file{configure.in} file:
+
+@example
+lispdir='$@{datadir@}/emacs/site-lisp'
+AC_SUBST(lispdir)
+@end example
+
@item includedir
@c rewritten to avoid overfull hbox --roland
The directory for installing header files to be included by user
@file{$(prefix)/include}.
(If you are using Autoconf, write it as @samp{@@includedir@@}.)
-Most compilers other than GCC do not look for header files in
+Most compilers other than GCC do not look for header files in directory
@file{/usr/local/include}. So installing the header files this way is
only useful with GCC. Sometimes this is not a problem because some
libraries are only really intended to work with GCC. But some libraries
@comment This example has been carefully formatted for the Make manual.
@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
@smallexample
-$(infodir)/foo.info: foo.info
+$(DESTDIR)$(infodir)/foo.info: foo.info
+ $(POST_INSTALL)
# There may be a newer info file in . than in srcdir.
-if test -f foo.info; then d=.; \
else d=$(srcdir); fi; \
- $(INSTALL_DATA) $$d/foo.info $@@; \
+ $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \
# Run install-info only if it exists.
# Use `if' instead of just prepending `-' to the
# line so we notice real errors from install-info.
# fail gracefully when there is an unknown command.
if $(SHELL) -c 'install-info --version' \
>/dev/null 2>&1; then \
- install-info --dir-file=$(infodir)/dir \
- $(infodir)/foo.info; \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/foo.info; \
else true; fi
@end smallexample
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands. @xref{Install Command
+Categories}.
+
@item uninstall
-Delete all the installed files that the @samp{install} target would
-create (but not the noninstalled files such as @samp{make all} would
-create).
+Delete all the installed files---the copies that the @samp{install}
+target creates.
This rule should not modify the directories where compilation is done,
only the directories where files are installed.
+The uninstallation commands are divided into three categories, just like
+the installation commands. @xref{Install Command Categories}.
+
@item install-strip
Like @code{install}, but strip the executable files while installing
-them. The definition of this target can be very simple:
+them. In many cases, the definition of this target can be very simple:
@smallexample
install-strip:
run the @code{makeinfo} program, which is part of the Texinfo
distribution.
+Normally a GNU distribution comes with Info files, and that means the
+Info files are present in the source directory. Therefore, the Make
+rule for an info file should update it in the source directory. When
+users build the package, ordinarily Make will not update the Info files
+because they will already be up to date.
+
@item dvi
Generate DVI files for all Texinfo documentation.
For example:
named, use @code{ln} or @code{cp} to install the proper files in it, and
then @code{tar} that subdirectory.
-Compress the tar file with @code{gzip}. For example, the actual
+Compress the tar file file with @code{gzip}. For example, the actual
distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
The @code{dist} target should explicitly depend on all non-source files
This rule should not modify the directories where compilation is done.
It should do nothing but create installation directories.
@end table
+
+@node Install Command Categories
+@section Install Command Categories
+
+@cindex pre-installation commands
+@cindex post-installation commands
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands.
+
+Normal commands move files into their proper places, and set their
+modes. They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+Pre-installation and post-installation commands may alter other files;
+in particular, they can edit global configuration files or data bases.
+
+Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+The most common use for a post-installation command is to run
+@code{install-info}. This cannot be done with a normal command, since
+it alters a file (the Info directory) which does not come entirely and
+solely from the package being installed. It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+Most programs don't need any pre-installation commands, but we have the
+feature just in case it is needed.
+
+To classify the commands in the @code{install} rule into these three
+categories, insert @dfn{category lines} among them. A category line
+specifies the category for the commands that follow.
+
+A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end. There are three
+variables you can use, one for each category; the variable name
+specifies the category. Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+@emph{should not} define them in the makefile).
+
+Here are the three possible category lines, each with a comment that
+explains what it means:
+
+@smallexample
+ $(PRE_INSTALL) # @r{Pre-install commands follow.}
+ $(POST_INSTALL) # @r{Post-install commands follow.}
+ $(NORMAL_INSTALL) # @r{Normal commands follow.}
+@end smallexample
+
+If you don't use a category line at the beginning of the @code{install}
+rule, all the commands are classified as normal until the first category
+line. If you don't use any category lines, all the commands are
+classified as normal.
+
+These are the category lines for @code{uninstall}:
+
+@smallexample
+ $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.}
+ $(POST_UNINSTALL) # @r{Post-uninstall commands follow.}
+ $(NORMAL_UNINSTALL) # @r{Normal commands follow.}
+@end smallexample
+
+Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+If the @code{install} or @code{uninstall} target has any dependencies
+which act as subroutines of installation, then you should start
+@emph{each} dependency's commands with a category line, and start the
+main target's commands with a category line also. This way, you can
+ensure that each command is placed in the right category regardless of
+which of the dependencies actually run.
+
+Pre-installation and post-installation commands should not run any
+programs except for these:
+
+@example
+[ basename bash cat chgrp chmod chown cmp cp dd diff echo
+egrep expand expr false fgrep find getopt grep gunzip gzip
+hostname install install-info kill ldconfig ln ls md5sum
+mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+test touch true uname xargs yes
+@end example
+
+@cindex binary packages
+The reason for distinguishing the commands in this way is for the sake
+of making binary packages. Typically a binary package contains all the
+executables and other files that need to be installed, and has its own
+method of installing them---so it does not need to run the normal
+installation commands. But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+Programs to build binary packages work by extracting the
+pre-installation and post-installation commands. Here is one way of
+extracting the pre-installation commands:
+
+@smallexample
+make -n install -o all \
+ PRE_INSTALL=pre-install \
+ POST_INSTALL=post-install \
+ NORMAL_INSTALL=normal-install \
+ | gawk -f pre-install.awk
+@end smallexample
+
+@noindent
+where the file @file{pre-install.awk} could contain this:
+
+@smallexample
+$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
+on @{print $0@}
+$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
+@end smallexample
+
+The resulting file of pre-installation commands is executed as a shell
+script as part of installing the binary package.
projects / chise / xemacs-chise.git.1 / blobdiff