@node Makefile Conventions
@chapter Makefile Conventions
-@comment standards.texi does not print an index, but make.texinfo does.
@cindex makefile, conventions for
@cindex conventions for makefiles
@cindex standards for makefiles
-@c Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-
+@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
+@c 2004, 2005, 2006, 2007, 2008, 2010 Free Software Foundation, Inc.
+@c
@c Permission is granted to copy, distribute and/or modify this document
-@c under the terms of the GNU Free Documentation License, Version 1.2
+@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, with no
@c Front-Cover Texts, and with no Back-Cover Texts.
@end iftex
describes conventions for writing the Makefiles for GNU programs.
Using Automake will help you write a Makefile that follows these
-conventions.
+conventions. For more information on portable Makefiles, see
+@sc{posix} and @ref{Portable Make, Portable Make Programming,, autoconf,
+Autoconf}.
+
@menu
* Makefile Basics:: General conventions for Makefiles.
@smallexample
foo.1 : foo.man sedscript
- sed -e sedscript foo.man > foo.1
+ sed -f sedscript foo.man > foo.1
@end smallexample
@noindent
@smallexample
foo.1 : foo.man sedscript
- sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
+ sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@@
@end smallexample
GNU distributions usually contain some files which are not source
@section Utilities in Makefiles
Write the Makefile commands (and any shell scripts, such as
-@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any
-special features of @code{ksh} or @code{bash}.
+@code{configure}) to run under @code{sh} (both the traditional Bourne
+shell and the @sc{posix} shell), not @code{csh}. Don't use any
+special features of @code{ksh} or @code{bash}, or @sc{posix} features
+not widely supported in traditional Bourne @code{sh}.
The @code{configure} script and the Makefile rules for building and
installation should not use any utilities directly except these:
@c mkfifo mknod tee uname
@example
-awk 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
+awk cat cmp cp diff echo egrep expr false grep install-info ln ls
+mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
@end example
-The compression program @code{gzip} can be used in the @code{dist} rule.
+Compression programs such as @code{gzip} can be used in the
+@code{dist} rule.
+
+Generally, stick to the widely-supported (usually
+@sc{posix}-specified) options and features of these programs. For
+example, don't use @samp{mkdir -p}, convenient as it may be, because a
+few systems don't support it at all and with others, it is not safe
+for parallel execution. For a list of known incompatibilities, see
+@ref{Portable Shell, Portable Shell Programming,, autoconf, Autoconf}.
-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.
It is a good idea to avoid creating symbolic links in makefiles, since a
-few systems don't support them.
+few file systems don't support them.
The Makefile rules for building and installation can also use compilers
and related programs, but should do so via @code{make} variables so that the
@node DESTDIR
-@section @code{DESTDIR}: support for staged installs
+@section @code{DESTDIR}: Support for Staged Installs
@vindex DESTDIR
@cindex staged installs
useful.
If your installation step would normally install
-@file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an
+@file{/usr/local/bin/foo} and @file{/usr/@/local/@/lib/@/libfoo.a}, then an
installation invoked as in the example above would install
@file{/tmp/stage/usr/local/bin/foo} and
@file{/tmp/stage/usr/local/lib/libfoo.a} instead.
default settings specified here so that all GNU packages behave
identically, allowing the installer to achieve any desired layout.
+@cindex directories, creating installation
+@cindex installation directories, creating
+All installation directories, and their parent directories, should be
+created (if necessary) before they are installed into.
+
These first two variables set the root for the installation. All the
other installation directories should be subdirectories of one of
these two, and nothing should be directly installed into these two
variables so that you can move these program-specific files without
altering the location for Info files, man pages, etc.
+@c raggedright (not until next Texinfo release)
This should normally be @file{/usr/local/share}, but write it as
@file{$(datarootdir)}. (If you are using Autoconf, write it as
@samp{@@datadir@@}.)
+@c end raggedright
The definition of @samp{datadir} is the same for all packages, so you
should install your data in a subdirectory thereof. Most packages
@table @samp
@item includedir
-@c rewritten to avoid overfull hbox --roland
The directory for installing header files to be included by user
programs with the C @samp{#include} preprocessor directive. This
should normally be @file{/usr/local/include}, but write it as
the @code{install-info} program if it is present. @code{install-info}
is a program that edits the Info @file{dir} file to add or update the
menu entry for the given Info file; it is part of the Texinfo package.
-Here is a sample rule to install an Info file:
+
+Here is a sample rule to install an Info file that also tries to
+handle some additional situations, such as @code{install-info} not
+being present.
@comment This example has been carefully formatted for the Make manual.
@comment Please do not reformat it without talking to bug-make@gnu.org.
@smallexample
-$(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 $(DESTDIR)$@@; \
+do-install-info: foo.info installdirs
+ $(NORMAL_INSTALL)
+# Prefer an info file in . to one in srcdir.
+ if test -f foo.info; then d=.; \
+ else d="$(srcdir)"; fi; \
+ $(INSTALL_DATA) $$d/foo.info \
+ "$(DESTDIR)$(infodir)/foo.info"
# Run install-info only if it exists.
# Use `if' instead of just prepending `-' to the
# line so we notice real errors from install-info.
-# We use `$(SHELL) -c' because some shells do not
+# Use `$(SHELL) -c' because some shells do not
# fail gracefully when there is an unknown command.
+ $(POST_INSTALL)
if $(SHELL) -c 'install-info --version' \
>/dev/null 2>&1; then \
- install-info --dir-file=$(DESTDIR)$(infodir)/dir \
- $(DESTDIR)$(infodir)/foo.info; \
+ install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
+ "$(DESTDIR)$(infodir)/foo.info"; \
else true; fi
@end smallexample
Compress the tar file with @code{gzip}. For example, the actual
distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
+It is ok to support other free compression formats as well.
The @code{dist} target should explicitly depend on all non-source files
that are in the distribution, to make sure they are up to date in the
It's useful to add a target named @samp{installdirs} to create the
directories where files are installed, and their parent directories.
There is a script called @file{mkinstalldirs} which is convenient for
-this; you can find it in the Texinfo package.
-@c It's in /gd/gnu/lib/mkinstalldirs.
+this; you can find it in the Gnulib package.
You can use a rule like this:
@comment This has been carefully formatted to look decent in the Make manual.
@end smallexample
@noindent
-or, if you wish to support @env{DESTDIR},
+or, if you wish to support @env{DESTDIR} (strongly encouraged),
@smallexample
# Make sure all installation directories (e.g. $(bindir))
projects / gnulib.git / blobdiff