standards: Makefile Basics

1 
1 7.2.1 General Conventions for Makefiles
1 ---------------------------------------
1 
1 Every Makefile should contain this line:
1 
1      SHELL = /bin/sh
1 
1 to avoid trouble on systems where the 'SHELL' variable might be
1 inherited from the environment.  (This is never a problem with GNU
1 'make'.)
1 
1    Different 'make' programs have incompatible suffix lists and implicit
1 rules, and this sometimes creates confusion or misbehavior.  So it is a
1 good idea to set the suffix list explicitly using only the suffixes you
1 need in the particular Makefile, like this:
1 
1      .SUFFIXES:
1      .SUFFIXES: .c .o
1 
1 The first line clears out the suffix list, the second introduces all
1 suffixes which may be subject to implicit rules in this Makefile.
1 
1    Don't assume that '.' is in the path for command execution.  When you
1 need to run programs that are a part of your package during the make,
1 please make sure that it uses './' if the program is built as part of
1 the make or '$(srcdir)/' if the file is an unchanging part of the source
1 code.  Without one of these prefixes, the current search path is used.
1 
1    The distinction between './' (the "build directory") and '$(srcdir)/'
1 (the "source directory") is important because users can build in a
1 separate directory using the '--srcdir' option to 'configure'.  A rule
1 of the form:
1 
1      foo.1 : foo.man sedscript
1              sed -f sedscript foo.man > foo.1
1 
1 will fail when the build directory is not the source directory, because
1 'foo.man' and 'sedscript' are in the source directory.
1 
1    When using GNU 'make', relying on 'VPATH' to find the source file
1 will work in the case where there is a single dependency file, since the
1 'make' automatic variable '$<' will represent the source file wherever
1 it is.  (Many versions of 'make' set '$<' only in implicit rules.)  A
1 Makefile target like
1 
1      foo.o : bar.c
1              $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
1 
1 should instead be written as
1 
1      foo.o : bar.c
1              $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
1 
1 in order to allow 'VPATH' to work correctly.  When the target has
1 multiple dependencies, using an explicit '$(srcdir)' is the easiest way
1 to make the rule work well.  For example, the target above for 'foo.1'
1 is best written as:
1 
1      foo.1 : foo.man sedscript
1              sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@
1 
1    GNU distributions usually contain some files which are not source
1 files--for example, Info files, and the output from Autoconf, Automake,
1 Bison or Flex.  Since these files normally appear in the source
1 directory, they should always appear in the source directory, not in the
1 build directory.  So Makefile rules to update them should put the
1 updated files in the source directory.
1 
1    However, if a file does not appear in the distribution, then the
1 Makefile should not put it in the source directory, because building a
1 program in ordinary circumstances should not modify the source directory
1 in any way.
1 
1    Try to make the build and installation targets, at least (and all
1 their subtargets) work correctly with a parallel 'make'.
1