diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 36 | ||||
| -rw-r--r-- | doc/Makefile.in | 673 | ||||
| -rw-r--r-- | doc/fdl.texi | 506 | ||||
| -rw-r--r-- | doc/make-stds.texi | 1157 | ||||
| -rw-r--r-- | doc/make.info | 187 | ||||
| -rw-r--r-- | doc/make.info-1 | 7066 | ||||
| -rw-r--r-- | doc/make.info-2 | 5053 | ||||
| -rw-r--r-- | doc/make.texi | 11458 | ||||
| -rw-r--r-- | doc/stamp-vti | 4 | ||||
| -rw-r--r-- | doc/version.texi | 4 |
10 files changed, 26144 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..67eec3a --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,36 @@ +# -*-Makefile-*-, or close enough +# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +# 2010 Free Software Foundation, Inc. +# This file is part of GNU Make. +# +# GNU Make is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation; either version 3 of the License, or (at your option) any later +# version. +# +# GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# this program. If not, see <http://www.gnu.org/licenses/>. + +TEXI2HTML = texi2html +TEXI2HTML_FLAGS = -split_chapter + +info_TEXINFOS = make.texi +make_TEXINFOS = fdl.texi make-stds.texi + +CLEANFILES = make*.html + +## ----------------------------- ## +## Other documentation formats. ## +## ----------------------------- ## + +html: make_1.html + +make_1.html: $(info_TEXINFOS) $(make_TEXINFOS) + $(TEXI2HTML) $(TEXI2HTML_FLAGS) $(srcdir)/make.texi + +.PHONY: html diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..a1089bc --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,673 @@ +# Makefile.in generated by automake 1.11.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# -*-Makefile-*-, or close enough +# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +# 2010 Free Software Foundation, Inc. +# This file is part of GNU Make. +# +# GNU Make is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation; either version 3 of the License, or (at your option) any later +# version. +# +# GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# this program. If not, see <http://www.gnu.org/licenses/>. +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +DIST_COMMON = $(make_TEXINFOS) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in $(srcdir)/stamp-vti \ + $(srcdir)/version.texi +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/config/dospaths.m4 \ + $(top_srcdir)/config/gettext.m4 $(top_srcdir)/config/iconv.m4 \ + $(top_srcdir)/config/isc-posix.m4 \ + $(top_srcdir)/config/lib-ld.m4 \ + $(top_srcdir)/config/lib-link.m4 \ + $(top_srcdir)/config/lib-prefix.m4 $(top_srcdir)/config/nls.m4 \ + $(top_srcdir)/config/po.m4 $(top_srcdir)/config/progtest.m4 \ + $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.in +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(SHELL) $(top_srcdir)/config/mkinstalldirs +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +SOURCES = +DIST_SOURCES = +INFO_DEPS = $(srcdir)/make.info +TEXINFO_TEX = $(top_srcdir)/config/texinfo.tex +am__TEXINFO_TEX_DIR = $(top_srcdir)/config +DVIS = make.dvi +PDFS = make.pdf +PSS = make.ps +HTMLS = make.html +TEXINFOS = make.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +AMTAR = @AMTAR@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +GETLOADAVG_LIBS = @GETLOADAVG_LIBS@ +GLOBINC = @GLOBINC@ +GLOBLIB = @GLOBLIB@ +GMSGFMT = @GMSGFMT@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INTLLIBS = @INTLLIBS@ +KMEM_GROUP = @KMEM_GROUP@ +LDFLAGS = @LDFLAGS@ +LIBICONV = @LIBICONV@ +LIBINTL = @LIBINTL@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LTLIBICONV = @LTLIBICONV@ +LTLIBINTL = @LTLIBINTL@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MAKE_HOST = @MAKE_HOST@ +MKDIR_P = @MKDIR_P@ +MKINSTALLDIRS = @MKINSTALLDIRS@ +MSGFMT = @MSGFMT@ +MSGMERGE = @MSGMERGE@ +NEED_SETGID = @NEED_SETGID@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +POSUB = @POSUB@ +RANLIB = @RANLIB@ +REMOTE = @REMOTE@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +USE_NLS = @USE_NLS@ +VERSION = @VERSION@ +XGETTEXT = @XGETTEXT@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +TEXI2HTML = texi2html +TEXI2HTML_FLAGS = -split_chapter +info_TEXINFOS = make.texi +make_TEXINFOS = fdl.texi make-stds.texi +CLEANFILES = make*.html +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +.texi.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + $(am__cd) $(srcdir); \ + else \ + rc=$$?; \ + $(am__cd) $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texi.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texi.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +$(srcdir)/make.info: make.texi $(srcdir)/version.texi $(make_TEXINFOS) +make.dvi: make.texi $(srcdir)/version.texi $(make_TEXINFOS) +make.pdf: make.texi $(srcdir)/version.texi $(make_TEXINFOS) +make.html: make.texi $(srcdir)/version.texi $(make_TEXINFOS) +$(srcdir)/version.texi: $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: make.texi $(top_srcdir)/configure + @(dir=.; test -f ./make.texi || dir=$(srcdir); \ + set `$(SHELL) $(top_srcdir)/config/mdate-sh $$dir/make.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp + @cmp -s vti.tmp $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi"; \ + cp vti.tmp $(srcdir)/version.texi) + -@rm -f vti.tmp + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp + +maintainer-clean-vti: + -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi +.dvi.ps: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && \ + (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf make.aux make.cp make.cps make.fn make.fns make.ky make.kys \ + make.log make.pg make.tmp make.toc make.tp make.tps make.vr + +clean-aminfo: + -test -z "make.dvi make.pdf make.ps make.html" \ + || rm -rf make.dvi make.pdf make.ps make.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-aminfo clean-generic mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d$$p"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + dist-info distclean distclean-generic distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti mostlyclean mostlyclean-aminfo \ + mostlyclean-generic mostlyclean-vti pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-dvi-am uninstall-html-am \ + uninstall-info-am uninstall-pdf-am uninstall-ps-am + + +html: make_1.html + +make_1.html: $(info_TEXINFOS) $(make_TEXINFOS) + $(TEXI2HTML) $(TEXI2HTML_FLAGS) $(srcdir)/make.texi + +.PHONY: html + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/fdl.texi b/doc/fdl.texi new file mode 100644 index 0000000..fc19ddd --- /dev/null +++ b/doc/fdl.texi @@ -0,0 +1,506 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, La@TeX{} input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/doc/make-stds.texi b/doc/make-stds.texi new file mode 100644 index 0000000..7cc9537 --- /dev/null +++ b/doc/make-stds.texi @@ -0,0 +1,1157 @@ +@comment This file is included by both standards.texi and make.texinfo. +@comment It was broken out of standards.texi on 1/6/93 by roland. + +@node Makefile Conventions +@chapter Makefile Conventions +@cindex makefile, conventions for +@cindex conventions for makefiles +@cindex standards for makefiles + +@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.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. +@c A copy of the license is included in the section entitled ``GNU +@c Free Documentation License''. + +This +@ifinfo +node +@end ifinfo +@iftex +@ifset CODESTD +section +@end ifset +@ifclear CODESTD +chapter +@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. 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. +* Utilities in Makefiles:: Utilities to be used in Makefiles. +* Command Variables:: Variables for specifying commands. +* DESTDIR:: Supporting staged installs. +* 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 +@section General Conventions for Makefiles + +Every Makefile should contain this line: + +@example +SHELL = /bin/sh +@end example + +@noindent +to avoid trouble on systems where the @code{SHELL} variable might be +inherited from the environment. (This is never a problem with GNU +@code{make}.) + +Different @code{make} programs have incompatible suffix lists and +implicit rules, and this sometimes creates confusion or misbehavior. So +it is a good idea to set the suffix list explicitly using only the +suffixes you need in the particular Makefile, like this: + +@example +.SUFFIXES: +.SUFFIXES: .c .o +@end example + +@noindent +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + +Don't assume that @file{.} is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses @file{./} if the program is built as +part of the make or @file{$(srcdir)/} if the file is an unchanging part +of the source code. Without one of these prefixes, the current search +path is used. + +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 + sed -f sedscript foo.man > foo.1 +@end smallexample + +@noindent +will fail when the build directory is not the source directory, because +@file{foo.man} and @file{sedscript} are in 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, +since the @code{make} automatic variable @samp{$<} will represent the +source file wherever it is. (Many versions of @code{make} set @samp{$<} +only in implicit rules.) A Makefile target like + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o +@end smallexample + +@noindent +should instead be written as + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ +@end smallexample + +@noindent +in order to allow @samp{VPATH} to work correctly. When the target has +multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest +way to make the rule work well. For example, the target above for +@file{foo.1} is best written as: + +@smallexample +foo.1 : foo.man sedscript + sed -f $(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}. + +@node Utilities in Makefiles +@section Utilities in Makefiles + +Write the Makefile commands (and any shell scripts, such as +@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 dd find +@c gunzip gzip md5sum +@c mkfifo mknod tee uname + +@example +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 + +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}. + + +It is a good idea to avoid creating symbolic links in makefiles, since a +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 +user can substitute alternatives. Here are some of the programs we +mean: + +@example +ar bison cc flex install ld ldconfig lex +make makeinfo ranlib texi2dvi yacc +@end example + +Use the following @code{make} variables to run those programs: + +@example +$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) +$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) +@end example + +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. + +@node Command Variables +@section Variables for Specifying Commands + +Makefiles should provide variables for overriding certain commands, options, +and so on. + +In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named @code{BISON} whose default +value is set with @samp{BISON = bison}, and refer to it with +@code{$(BISON)} whenever you need to use Bison. + +File management utilities such as @code{ln}, @code{rm}, @code{mv}, and +so on, need not be referred to through variables in this way, since users +don't need to replace them with other programs. + +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 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}. +Users expect to be able to specify @code{CFLAGS} freely themselves. +Instead, arrange to pass the necessary options to the C compiler +independently of @code{CFLAGS}, by writing them explicitly in the +compilation commands or by defining an implicit rule, like this: + +@smallexample +CFLAGS = -g +ALL_CFLAGS = -I. $(CFLAGS) +.c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< +@end smallexample + +Do include the @samp{-g} option in @code{CFLAGS}, because that is not +@emph{required} for proper compilation. You can consider it a default +that is only recommended. If the package is set up so that it is +compiled with GCC by default, then you might as well include @samp{-O} +in the default value of @code{CFLAGS} as well. + +Put @code{CFLAGS} last in the compilation command, after other variables +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. + +Every Makefile should also define the variables @code{INSTALL_PROGRAM} +and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should +be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be +@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the +commands for actual installation, for executables and non-executables +respectively. Minimal use of these variables is as follows: + +@example +$(INSTALL_PROGRAM) foo $(bindir)/foo +$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a +@end example + +However, it is preferable to support a @code{DESTDIR} prefix on the +target files, as explained in the next section. + +It is acceptable, but not required, to install multiple files in one +command, with the final argument being a directory, as in: + +@example +$(INSTALL_PROGRAM) foo bar baz $(bindir) +@end example + + +@node DESTDIR +@section @code{DESTDIR}: Support for Staged Installs + +@vindex DESTDIR +@cindex staged installs +@cindex installations, staged + +@code{DESTDIR} is a variable prepended to each installed target file, +like this: + +@example +$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo +$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a +@end example + +The @code{DESTDIR} variable is specified by the user on the @code{make} +command line as an absolute file name. For example: + +@example +make DESTDIR=/tmp/stage install +@end example + +@noindent +@code{DESTDIR} should be supported only in the @code{install*} and +@code{uninstall*} targets, as those are the only targets where it is +useful. + +If your installation step would normally install +@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. + +Prepending the variable @code{DESTDIR} to each target in this way +provides for @dfn{staged installs}, where the installed files are not +placed directly into their expected location but are instead copied +into a temporary location (@code{DESTDIR}). However, installed files +maintain their relative directory structure and any embedded file names +will not be modified. + +You should not set the value of @code{DESTDIR} in your @file{Makefile} +at all; then the files are installed into their expected locations by +default. Also, specifying @code{DESTDIR} should not change the +operation of the software in any way, so its value should not be +included in any file contents. + +@code{DESTDIR} support is commonly used in package creation. It is +also helpful to users who want to understand what a given package will +install where, and to allow users who don't normally have permissions +to install into protected areas to build and install before gaining +those permissions. Finally, it can be useful with tools such as +@code{stow}, where code is installed in one place but made to appear +to be installed somewhere else using symbolic links or special mount +operations. So, we strongly recommend GNU packages support +@code{DESTDIR}, though it is not an absolute requirement. + + +@node Directory Variables +@section Variables for Installation Directories + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables and the values they should have in GNU packages are +described below. They are based on a standard file system layout; +variants of it are used in GNU/Linux and other modern operating +systems. + +Installers are expected to override these values when calling +@command{make} (e.g., @kbd{make prefix=/usr install} or +@command{configure} (e.g., @kbd{configure --prefix=/usr}). GNU +packages should not try to guess which value should be appropriate for +these variables on the system they are being installed onto: use the +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 +directories. + +@table @code +@item prefix +@vindex prefix +A prefix used in constructing the default values of the variables listed +below. The default value of @code{prefix} should be @file{/usr/local}. +When building the complete GNU system, the prefix will be empty and +@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 @emph{not} recompile the +program. + +@item exec_prefix +@vindex 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 +be @code{$(prefix)}. +(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) + +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 @emph{not} recompile the +program. +@end table + +Executable programs are installed in one of the following directories. + +@table @code +@item bindir +@vindex bindir +The directory for installing executable programs that users can run. +This should normally be @file{/usr/local/bin}, but write it as +@file{$(exec_prefix)/bin}. +(If you are using Autoconf, write it as @samp{@@bindir@@}.) + +@item sbindir +@vindex sbindir +The directory for installing executable programs that can be run from +the shell, but are only generally useful to system administrators. This +should normally be @file{/usr/local/sbin}, but write it as +@file{$(exec_prefix)/sbin}. +(If you are using Autoconf, write it as @samp{@@sbindir@@}.) + +@item libexecdir +@vindex libexecdir +@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 +The directory for installing executable programs to be run by other +programs rather than by users. This directory should normally be +@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. +(If you are using Autoconf, write it as @samp{@@libexecdir@@}.) + +The definition of @samp{libexecdir} is the same for all packages, so +you should install your data in a subdirectory thereof. Most packages +install their data under @file{$(libexecdir)/@var{package-name}/}, +possibly within additional subdirectories thereof, such as +@file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}. +@end table + +Data files used by the program during its execution are divided into +categories in two ways. + +@itemize @bullet +@item +Some files are normally modified by programs; others are never normally +modified (though users may edit some of these). + +@item +Some files are architecture-independent and can be shared by all +machines at a site; some are architecture-dependent and can be shared +only by machines of the same kind and operating system; others may never +be shared between two machines. +@end itemize + +This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + +Here are the variables Makefiles should use to specify directories +to put these various kinds of files in: + +@table @samp +@item datarootdir +The root of the directory tree for read-only architecture-independent +data files. This should normally be @file{/usr/local/share}, but +write it as @file{$(prefix)/share}. (If you are using Autoconf, write +it as @samp{@@datarootdir@@}.) @samp{datadir}'s default value is +based on this variable; so are @samp{infodir}, @samp{mandir}, and +others. + +@item datadir +The directory for installing idiosyncratic read-only +architecture-independent data files for this program. This is usually +the same place as @samp{datarootdir}, but we use the two separate +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 +install their data under @file{$(datadir)/@var{package-name}/}. + +@item sysconfdir +The directory for installing read-only data files that pertain to a +single machine--that is to say, files for configuring a host. Mailer +and network configuration files, @file{/etc/passwd}, and so forth belong +here. All the files in this directory should be ordinary ASCII text +files. This directory should normally be @file{/usr/local/etc}, but +write it as @file{$(prefix)/etc}. +(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) + +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 +the programs modify while they run. This should normally be +@file{/usr/local/com}, but write it as @file{$(prefix)/com}. +(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) + +@item localstatedir +The directory for installing data files which the programs modify while +they run, and that pertain to one specific machine. Users should never +need to modify files in this directory to configure the package's +operation; put such configuration information in separate files that go +in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} +should normally be @file{/usr/local/var}, but write it as +@file{$(prefix)/var}. +(If you are using Autoconf, write it as @samp{@@localstatedir@@}.) +@end table + +These variables specify the directory for installing certain specific +types of files, if your program has them. Every GNU package should +have Info files, so every program needs @samp{infodir}, but not all +need @samp{libdir} or @samp{lispdir}. + +@table @samp +@item includedir +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 +@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 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 +are intended to work with other compilers. They should install their +header files in two places, one specified by @code{includedir} and one +specified by @code{oldincludedir}. + +@item oldincludedir +The directory for installing @samp{#include} header files for use with +compilers other than GCC. This should normally be @file{/usr/include}. +(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) + +The Makefile commands should check whether the value of +@code{oldincludedir} is empty. If it is, they should not try to use +it; they should cancel the second installation of the header files. + +A package should not replace an existing header in this directory unless +the header came from the same package. Thus, if your Foo package +provides a header file @file{foo.h}, then it should install the header +file in the @code{oldincludedir} directory if either (1) there is no +@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo +package. + +To tell whether @file{foo.h} came from the Foo package, put a magic +string in the file---part of a comment---and @code{grep} for that string. + +@item docdir +The directory for installing documentation files (other than Info) for +this package. By default, it should be +@file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as +@file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf, +write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which +may include a version number, prevents collisions among files with +common names, such as @file{README}. + +@item infodir +The directory for installing the Info files for this package. By +default, it should be @file{/usr/local/share/info}, but it should be +written as @file{$(datarootdir)/info}. (If you are using Autoconf, +write it as @samp{@@infodir@@}.) @code{infodir} is separate from +@code{docdir} for compatibility with existing practice. + +@item htmldir +@itemx dvidir +@itemx pdfdir +@itemx psdir +Directories for installing documentation files in the particular +format. They should all be set to @code{$(docdir)} by default. (If +you are using Autoconf, write them as @samp{@@htmldir@@}, +@samp{@@dvidir@@}, etc.) Packages which supply several translations +of their documentation should install them in +@samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where +@var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}. + +@item libdir +The directory for object files and libraries of object code. Do not +install executables here, they probably ought to go in @file{$(libexecdir)} +instead. The value of @code{libdir} should normally be +@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. +(If you are using Autoconf, write it as @samp{@@libdir@@}.) + +@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{$(datarootdir)/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='$@{datarootdir@}/emacs/site-lisp' +AC_SUBST(lispdir) +@end example + +@item localedir +The directory for installing locale-specific message catalogs for this +package. By default, it should be @file{/usr/local/share/locale}, but +it should be written as @file{$(datarootdir)/locale}. (If you are +using Autoconf, write it as @samp{@@localedir@@}.) This directory +usually has a subdirectory per locale. +@end table + +Unix-style man pages are installed in one of the following: + +@table @samp +@item mandir +The top-level directory for installing the man pages (if any) for this +package. It will normally be @file{/usr/local/share/man}, but you +should write it as @file{$(datarootdir)/man}. (If you are using +Autoconf, write it as @samp{@@mandir@@}.) + +@item man1dir +The directory for installing section 1 man pages. Write it as +@file{$(mandir)/man1}. +@item man2dir +The directory for installing section 2 man pages. Write it as +@file{$(mandir)/man2} +@item @dots{} + +@strong{Don't make the primary documentation for any GNU software be a +man page. Write a manual in Texinfo instead. Man pages are just for +the sake of people running GNU software on Unix, which is a secondary +application only.} + +@item manext +The file name extension for the installed man page. This should contain +a period followed by the appropriate digit; it should normally be @samp{.1}. + +@item man1ext +The file name extension for installed section 1 man pages. +@item man2ext +The file name extension for installed section 2 man pages. +@item @dots{} +Use these names instead of @samp{manext} if the package needs to install man +pages in more than one section of the manual. +@end table + +And finally, you should set the following variable: + +@table @samp +@item srcdir +The directory for the sources being compiled. The value of this +variable is normally inserted by the @code{configure} shell script. +(If you are using Autoconf, use @samp{srcdir = @@srcdir@@}.) +@end table + +For example: + +@smallexample +@c I have changed some of the comments here slightly to fix an overfull +@c hbox, so the make manual can format correctly. --roland +# Common prefix for installation directories. +# NOTE: This directory must exist when you start the install. +prefix = /usr/local +datarootdir = $(prefix)/share +datadir = $(datarootdir) +exec_prefix = $(prefix) +# Where to put the executable for the command `gcc'. +bindir = $(exec_prefix)/bin +# Where to put the directories used by the compiler. +libexecdir = $(exec_prefix)/libexec +# Where to put the Info files. +infodir = $(datarootdir)/info +@end smallexample + +If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the @code{install} rule to create these subdirectories. + +Do not expect the user to include the subdirectory name in the value of +any of the variables listed above. The idea of having a uniform set of +variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + +At times, not all of these variables may be implemented in the current +release of Autoconf and/or Automake; but as of Autoconf@tie{}2.60, we +believe all of them are. When any are missing, the descriptions here +serve as specifications for what Autoconf will implement. As a +programmer, you can either use a development version of Autoconf or +avoid using these variables until a stable release is made which +supports them. + + +@node Standard Targets +@section Standard Targets for Users + +All GNU programs should have the following targets in their Makefiles: + +@table @samp +@item all +Compile the entire program. This should be the default target. This +target need not rebuild any documentation files; Info files should +normally be included in the distribution, and DVI (and other +documentation format) files should be made only when explicitly asked +for. + +By default, the Make rules should compile and link with @samp{-g}, so +that executable programs have debugging symbols. Users who don't mind +being helpless can strip the executables later if they wish. + +@item install +Compile the program and copy the executables, libraries, and so on to +the file names where they should reside for actual use. If there is a +simple test to verify that a program is properly installed, this target +should run that test. + +Do not strip executables when installing them. Devil-may-care users can +use the @code{install-strip} target to do that. + +If possible, write the @code{install} target rule so that it does not +modify anything in the directory where the program was built, provided +@samp{make all} has just been done. This is convenient for building the +program under one user name and installing it under another. + +The commands should create all the directories in which files are to be +installed, if they don't already exist. This includes the directories +specified as the values of the variables @code{prefix} and +@code{exec_prefix}, as well as all subdirectories that are needed. +One way to do this is by means of an @code{installdirs} target +as described below. + +Use @samp{-} before any command for installing a man page, so that +@code{make} will ignore any errors. This is in case there are systems +that don't have the Unix man page documentation system installed. + +The way to install Info files is to copy them into @file{$(infodir)} +with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run +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 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 +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. +# 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"; \ + 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 install-html +@itemx install-dvi +@itemx install-pdf +@itemx install-ps +These targets install documentation in formats other than Info; +they're intended to be called explicitly by the person installing the +package, if that format is desired. GNU prefers Info files, so these +must be installed by the @code{install} target. + +When you have many documentation files to install, we recommend that +you avoid collisions and clutter by arranging for these targets to +install in subdirectories of the appropriate installation directory, +such as @code{htmldir}. As one example, if your package has multiple +manuals, and you wish to install HTML documentation with many files +(such as the ``split'' mode output by @code{makeinfo --html}), you'll +certainly want to use subdirectories, or two nodes with the same name +in different manuals will overwrite each other. + +Please make these @code{install-@var{format}} targets invoke the +commands for the @var{format} target, for example, by making +@var{format} a dependency. + +@item uninstall +Delete all the installed files---the copies that the @samp{install} +and @samp{install-*} targets create. + +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. In simple cases, this target can use the @code{install} target in +a simple way: + +@smallexample +install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install +@end smallexample + +But if the package installs scripts as well as real executables, the +@code{install-strip} target can't just refer to the @code{install} +target; it has to strip the executables but not the scripts. + +@code{install-strip} should not strip the executables in the build +directory which are being copied for installation. It should only strip +the copies that are installed. + +Normally we do not recommend stripping an executable unless you are sure +the program has no bugs. However, it can be reasonable to install a +stripped executable for actual execution while saving the unstripped +executable elsewhere in case there is a bug. + +@comment The gratuitous blank line here is to make the table look better +@comment in the printed Make manual. Please leave it in. +@item clean + +Delete all files in the current directory that are normally created by +building the program. Also delete files in other directories if they +are created by this makefile. However, don't delete the files that +record the configuration. Also preserve files that could be made by +building, but normally aren't because the distribution comes with +them. There is no need to delete parent directories that were created +with @samp{mkdir -p}, since they could have existed anyway. + +Delete @file{.dvi} files here if they are not part of the distribution. + +@item distclean +Delete all files in the current directory (or created by this +makefile) that are created by configuring or building the program. If +you have unpacked the source and built the program without creating +any other files, @samp{make distclean} should leave only the files +that were in the distribution. However, there is no need to delete +parent directories that were created with @samp{mkdir -p}, since they +could have existed anyway. + +@item mostlyclean +Like @samp{clean}, but may refrain from deleting a few files that people +normally don't want to recompile. For example, the @samp{mostlyclean} +target for GCC does not delete @file{libgcc.a}, because recompiling it +is rarely necessary and takes a lot of time. + +@item maintainer-clean +Delete almost everything that can be reconstructed with this Makefile. +This typically includes everything deleted by @code{distclean}, plus +more: C source files produced by Bison, tags tables, Info files, and +so on. + +The reason we say ``almost everything'' is that running the command +@samp{make maintainer-clean} should not delete @file{configure} even +if @file{configure} can be remade using a rule in the Makefile. More +generally, @samp{make maintainer-clean} should not delete anything +that needs to exist in order to run @file{configure} and then begin to +build the program. Also, there is no need to delete parent +directories that were created with @samp{mkdir -p}, since they could +have existed anyway. These are the only exceptions; +@code{maintainer-clean} should delete everything else that can be +rebuilt. + +The @samp{maintainer-clean} target is intended to be used by a maintainer of +the package, not by ordinary users. You may need special tools to +reconstruct some of the files that @samp{make maintainer-clean} deletes. +Since these files are normally included in the distribution, we don't +take care to make them easy to reconstruct. If you find you need to +unpack the full distribution again, don't blame us. + +To help make users aware of this, the commands for the special +@code{maintainer-clean} target should start with these two: + +@smallexample +@@echo 'This command is intended for maintainers to use; it' +@@echo 'deletes files that may need special tools to rebuild.' +@end smallexample + +@item TAGS +Update a tags table for this program. +@c ADR: how? + +@item info +Generate any Info files needed. The best way to write the rules is as +follows: + +@smallexample +info: foo.info + +foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{MAKEINFO} in the Makefile. It should +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 +@itemx html +@itemx pdf +@itemx ps +Generate documentation files in the given format. These targets +should always exist, but any or all can be a no-op if the given output +format cannot be generated. These targets should not be dependencies +of the @code{all} target; the user must manually invoke them. + +Here's an example rule for generating DVI files from Texinfo: + +@smallexample +dvi: foo.dvi + +foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{TEXI2DVI} in the Makefile. It should +run the program @code{texi2dvi}, which is part of the Texinfo +distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work +of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, +write just the dependencies, and allow GNU @code{make} to provide the command. + +Here's another example, this one for generating HTML from Texinfo: + +@smallexample +html: foo.html + +foo.html: foo.texi chap1.texi chap2.texi + $(TEXI2HTML) $(srcdir)/foo.texi +@end smallexample + +@noindent +Again, you would define the variable @code{TEXI2HTML} in the Makefile; +for example, it might run @code{makeinfo --no-split --html} +(@command{makeinfo} is part of the Texinfo distribution). + +@item dist +Create a distribution tar file for this program. The tar file should be +set up so that the file names in the tar file start with a subdirectory +name which is the name of the package it is a distribution for. This +name can include the version number. + +For example, the distribution tar file of GCC version 1.40 unpacks into +a subdirectory named @file{gcc-1.40}. + +The easiest way to do this is to create a subdirectory appropriately +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 +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 +distribution. +@ifset CODESTD +@xref{Releases, , Making Releases}. +@end ifset +@ifclear CODESTD +@xref{Releases, , Making Releases, standards, GNU Coding Standards}. +@end ifclear + +@item check +Perform self-tests (if any). The user must build the program before +running the tests, but need not install the program; you should write +the self-tests so that they work when the program is built but not +installed. +@end table + +The following targets are suggested as conventional names, for programs +in which they are useful. + +@table @code +@item installcheck +Perform installation tests (if any). The user must build and install +the program before running the tests. You should not assume that +@file{$(bindir)} is in the search path. + +@item installdirs +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 Gnulib package. +You can use a rule like this: + +@comment This has been carefully formatted to look decent in the Make manual. +@comment Please be sure not to make it extend any further to the right.--roland +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) +@end smallexample + +@noindent +or, if you wish to support @env{DESTDIR} (strongly encouraged), + +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs \ + $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ + $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ + $(DESTDIR)$(mandir) +@end smallexample + +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 (the @option{-s} option to +@command{make} is needed to silence messages about entering +subdirectories): + +@smallexample +make -s -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 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@} +on @{print $0@} +$0 ~ /^pre-install[ \t]*$/ @{on = 1@} +@end smallexample diff --git a/doc/make.info b/doc/make.info new file mode 100644 index 0000000..bd28f2b --- /dev/null +++ b/doc/make.info @@ -0,0 +1,187 @@ +This is make.info, produced by makeinfo version 4.13 from make.texi. + +This file documents the GNU `make' utility, which determines +automatically which pieces of a large program need to be recompiled, +and issues the commands to recompile them. + + This is Edition 0.71, last updated 19 July 2010, of `The GNU Make +Manual', for GNU `make' version 3.82. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover Texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Make: (make). Remake files automatically. +END-INFO-DIR-ENTRY + + +Indirect: +make.info-1: 1319 +make.info-2: 293656 + +Tag Table: +(Indirect) +Node: Top1319 +Node: Overview14709 +Node: Preparing15719 +Node: Reading16690 +Node: Bugs17617 +Node: Introduction19446 +Node: Rule Introduction21037 +Node: Simple Makefile22970 +Node: How Make Works26666 +Node: Variables Simplify29321 +Node: make Deduces31527 +Node: Combine By Prerequisite33260 +Node: Cleanup34289 +Node: Makefiles35707 +Node: Makefile Contents36543 +Node: Makefile Names39649 +Node: Include41260 +Ref: Include-Footnote-145008 +Node: MAKEFILES Variable45142 +Node: Remaking Makefiles46683 +Node: Overriding Makefiles50907 +Node: Reading Makefiles52935 +Node: Secondary Expansion55947 +Node: Rules63388 +Node: Rule Example66060 +Node: Rule Syntax66914 +Node: Prerequisite Types69507 +Node: Wildcards72374 +Node: Wildcard Examples74092 +Node: Wildcard Pitfall75441 +Node: Wildcard Function77230 +Node: Directory Search79014 +Node: General Search80148 +Node: Selective Search81855 +Node: Search Algorithm84843 +Node: Recipes/Search87361 +Node: Implicit/Search88684 +Node: Libraries/Search89626 +Node: Phony Targets91596 +Node: Force Targets96665 +Node: Empty Targets97702 +Node: Special Targets99007 +Node: Multiple Targets106862 +Node: Multiple Rules108727 +Node: Static Pattern110945 +Node: Static Usage111597 +Node: Static versus Implicit115316 +Node: Double-Colon117057 +Node: Automatic Prerequisites118817 +Node: Recipes123095 +Node: Recipe Syntax124268 +Node: Splitting Lines126383 +Node: Variables in Recipes129483 +Node: Echoing130802 +Node: Execution132077 +Ref: Execution-Footnote-1133488 +Node: One Shell133633 +Node: Choosing the Shell136948 +Node: Parallel141094 +Node: Errors144815 +Node: Interrupts148483 +Node: Recursion150066 +Node: MAKE Variable152164 +Node: Variables/Recursion154411 +Node: Options/Recursion159861 +Node: -w Option165021 +Node: Canned Recipes166016 +Node: Empty Recipes169000 +Node: Using Variables170148 +Node: Reference173523 +Node: Flavors175081 +Node: Advanced180821 +Node: Substitution Refs181326 +Node: Computed Names182879 +Node: Values187425 +Node: Setting188342 +Node: Appending190378 +Node: Override Directive194304 +Node: Multi-Line195931 +Node: Undefine Directive198754 +Node: Environment199840 +Node: Target-specific202091 +Node: Pattern-specific205108 +Node: Suppressing Inheritance206954 +Node: Special Variables208408 +Node: Conditionals213121 +Node: Conditional Example213834 +Node: Conditional Syntax216397 +Node: Testing Flags222127 +Node: Functions223228 +Node: Syntax of Functions224659 +Node: Text Functions226858 +Node: File Name Functions235429 +Node: Conditional Functions240651 +Node: Foreach Function243025 +Node: Call Function246237 +Node: Value Function249122 +Node: Eval Function250559 +Node: Origin Function252835 +Node: Flavor Function256051 +Node: Shell Function257117 +Node: Make Control Functions258751 +Node: Running260413 +Node: Makefile Arguments262396 +Node: Goals263112 +Node: Instead of Execution267851 +Node: Avoiding Compilation271433 +Node: Overriding273407 +Node: Testing275710 +Node: Options Summary277594 +Node: Implicit Rules287992 +Node: Using Implicit290137 +Node: Catalogue of Rules293656 +Node: Implicit Variables303004 +Node: Chained Rules307761 +Node: Pattern Rules311772 +Node: Pattern Intro313307 +Node: Pattern Examples315895 +Node: Automatic Variables317701 +Node: Pattern Match325059 +Node: Match-Anything Rules328382 +Node: Canceling Rules332256 +Node: Last Resort332970 +Node: Suffix Rules334799 +Node: Implicit Rule Search338524 +Node: Archives342023 +Node: Archive Members342721 +Node: Archive Update344331 +Node: Archive Symbols346242 +Node: Archive Pitfalls347476 +Node: Archive Suffix Rules348198 +Node: Features349745 +Node: Missing358290 +Node: Makefile Conventions362017 +Node: Makefile Basics362996 +Node: Utilities in Makefiles366163 +Node: Command Variables368661 +Node: DESTDIR371900 +Node: Directory Variables374067 +Node: Standard Targets388682 +Ref: Standard Targets-Footnote-1402458 +Node: Install Command Categories402558 +Node: Quick Reference407084 +Node: Error Messages418767 +Node: Complex Makefile426463 +Node: GNU Free Documentation License434974 +Node: Concept Index460136 +Node: Name Index526637 + +End Tag Table diff --git a/doc/make.info-1 b/doc/make.info-1 new file mode 100644 index 0000000..509ce05 --- /dev/null +++ b/doc/make.info-1 @@ -0,0 +1,7066 @@ +This is make.info, produced by makeinfo version 4.13 from make.texi. + +This file documents the GNU `make' utility, which determines +automatically which pieces of a large program need to be recompiled, +and issues the commands to recompile them. + + This is Edition 0.71, last updated 19 July 2010, of `The GNU Make +Manual', for GNU `make' version 3.82. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover Texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Make: (make). Remake files automatically. +END-INFO-DIR-ENTRY + + +File: make.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) + +GNU `make' +********** + +This file documents the GNU `make' utility, which determines +automatically which pieces of a large program need to be recompiled, +and issues the commands to recompile them. + + This is Edition 0.71, last updated 19 July 2010, of `The GNU Make +Manual', for GNU `make' version 3.82. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover Texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + +* Menu: + +* Overview:: Overview of `make'. +* Introduction:: An introduction to `make'. +* Makefiles:: Makefiles tell `make' what to do. +* Rules:: Rules describe when a file must be remade. +* Recipes:: Recipes say how to remake a file. +* Using Variables:: You can use variables to avoid repetition. +* Conditionals:: Use or ignore parts of the makefile based + on the values of variables. +* Functions:: Many powerful ways to manipulate text. +* Invoking make: Running. How to invoke `make' on the command line. +* Implicit Rules:: Use implicit rules to treat many files alike, + based on their file names. +* Archives:: How `make' can update library archives. +* Features:: Features GNU `make' has over other `make's. +* Missing:: What GNU `make' lacks from other `make's. +* Makefile Conventions:: Conventions for writing makefiles for + GNU programs. +* Quick Reference:: A quick reference for experienced users. +* Error Messages:: A list of common errors generated by `make'. +* Complex Makefile:: A real example of a straightforward, + but nontrivial, makefile. + +* GNU Free Documentation License:: License for copying this manual +* Concept Index:: Index of Concepts +* Name Index:: Index of Functions, Variables, & Directives + + --- The Detailed Node Listing --- + +Overview of `make' + +* Preparing:: Preparing and running make +* Reading:: On reading this text +* Bugs:: Problems and bugs + +An Introduction to Makefiles + +* Rule Introduction:: What a rule looks like. +* Simple Makefile:: A simple makefile +* How Make Works:: How `make' processes this makefile +* Variables Simplify:: Variables make makefiles simpler +* make Deduces:: Letting `make' deduce the recipe +* Combine By Prerequisite:: Another style of makefile +* Cleanup:: Rules for cleaning the directory + +Writing Makefiles + +* Makefile Contents:: What makefiles contain. +* Makefile Names:: How to name your makefile. +* Include:: How one makefile can use another makefile. +* MAKEFILES Variable:: The environment can specify extra makefiles. +* Remaking Makefiles:: How makefiles get remade. +* Overriding Makefiles:: How to override part of one makefile + with another makefile. +* Reading Makefiles:: How makefiles are parsed. +* Secondary Expansion:: How and when secondary expansion is performed. + +Writing Rules + +* Rule Example:: An example explained. +* Rule Syntax:: General syntax explained. +* Prerequisite Types:: There are two types of prerequisites. +* Wildcards:: Using wildcard characters such as `*'. +* Directory Search:: Searching other directories for source files. +* Phony Targets:: Using a target that is not a real file's name. +* Force Targets:: You can use a target without a recipe + or prerequisites to mark other targets + as phony. +* Empty Targets:: When only the date matters and the + files are empty. +* Special Targets:: Targets with special built-in meanings. +* Multiple Targets:: When to make use of several targets in a rule. +* Multiple Rules:: How to use several rules with the same target. +* Static Pattern:: Static pattern rules apply to multiple targets + and can vary the prerequisites according to + the target name. +* Double-Colon:: How to use a special kind of rule to allow + several independent rules for one target. +* Automatic Prerequisites:: How to automatically generate rules giving + prerequisites from source files themselves. + +Using Wildcard Characters in File Names + +* Wildcard Examples:: Several examples +* Wildcard Pitfall:: Problems to avoid. +* Wildcard Function:: How to cause wildcard expansion where + it does not normally take place. + +Searching Directories for Prerequisites + +* General Search:: Specifying a search path that applies + to every prerequisite. +* Selective Search:: Specifying a search path + for a specified class of names. +* Search Algorithm:: When and how search paths are applied. +* Recipes/Search:: How to write recipes that work together + with search paths. +* Implicit/Search:: How search paths affect implicit rules. +* Libraries/Search:: Directory search for link libraries. + +Static Pattern Rules + +* Static Usage:: The syntax of static pattern rules. +* Static versus Implicit:: When are they better than implicit rules? + +Writing Recipes in Rules + +* Recipe Syntax:: Recipe syntax features and pitfalls. +* Echoing:: How to control when recipes are echoed. +* Execution:: How recipes are executed. +* Parallel:: How recipes can be executed in parallel. +* Errors:: What happens after a recipe execution error. +* Interrupts:: What happens when a recipe is interrupted. +* Recursion:: Invoking `make' from makefiles. +* Canned Recipes:: Defining canned recipes. +* Empty Recipes:: Defining useful, do-nothing recipes. + +Recipe Syntax + +* Splitting Lines:: Breaking long recipe lines for readability. +* Variables in Recipes:: Using `make' variables in recipes. + +Recipe Execution + +* Choosing the Shell:: How `make' chooses the shell used + to run recipes. + +Recursive Use of `make' + +* MAKE Variable:: The special effects of using `$(MAKE)'. +* Variables/Recursion:: How to communicate variables to a sub-`make'. +* Options/Recursion:: How to communicate options to a sub-`make'. +* -w Option:: How the `-w' or `--print-directory' option + helps debug use of recursive `make' commands. + +How to Use Variables + +* Reference:: How to use the value of a variable. +* Flavors:: Variables come in two flavors. +* Advanced:: Advanced features for referencing a variable. +* Values:: All the ways variables get their values. +* Setting:: How to set a variable in the makefile. +* Appending:: How to append more text to the old value + of a variable. +* Override Directive:: How to set a variable in the makefile even if + the user has set it with a command argument. +* Multi-Line:: An alternate way to set a variable + to a multi-line string. +* Environment:: Variable values can come from the environment. +* Target-specific:: Variable values can be defined on a per-target + basis. +* Pattern-specific:: Target-specific variable values can be applied + to a group of targets that match a pattern. +* Suppressing Inheritance:: Suppress inheritance of variables. +* Special Variables:: Variables with special meaning or behavior. + +Advanced Features for Reference to Variables + +* Substitution Refs:: Referencing a variable with + substitutions on the value. +* Computed Names:: Computing the name of the variable to refer to. + +Conditional Parts of Makefiles + +* Conditional Example:: Example of a conditional +* Conditional Syntax:: The syntax of conditionals. +* Testing Flags:: Conditionals that test flags. + +Functions for Transforming Text + +* Syntax of Functions:: How to write a function call. +* Text Functions:: General-purpose text manipulation functions. +* File Name Functions:: Functions for manipulating file names. +* Conditional Functions:: Functions that implement conditions. +* Foreach Function:: Repeat some text with controlled variation. +* Call Function:: Expand a user-defined function. +* Value Function:: Return the un-expanded value of a variable. +* Eval Function:: Evaluate the arguments as makefile syntax. +* Origin Function:: Find where a variable got its value. +* Flavor Function:: Find out the flavor of a variable. +* Shell Function:: Substitute the output of a shell command. +* Make Control Functions:: Functions that control how make runs. + +How to Run `make' + +* Makefile Arguments:: How to specify which makefile to use. +* Goals:: How to use goal arguments to specify which + parts of the makefile to use. +* Instead of Execution:: How to use mode flags to specify what + kind of thing to do with the recipes + in the makefile other than simply + execute them. +* Avoiding Compilation:: How to avoid recompiling certain files. +* Overriding:: How to override a variable to specify + an alternate compiler and other things. +* Testing:: How to proceed past some errors, to + test compilation. +* Options Summary:: Summary of Options + +Using Implicit Rules + +* Using Implicit:: How to use an existing implicit rule + to get the recipe for updating a file. +* Catalogue of Rules:: A list of built-in implicit rules. +* Implicit Variables:: How to change what predefined rules do. +* Chained Rules:: How to use a chain of implicit rules. +* Pattern Rules:: How to define new implicit rules. +* Last Resort:: How to define a recipe for rules which + cannot find any. +* Suffix Rules:: The old-fashioned style of implicit rule. +* Implicit Rule Search:: The precise algorithm for applying + implicit rules. + +Defining and Redefining Pattern Rules + +* Pattern Intro:: An introduction to pattern rules. +* Pattern Examples:: Examples of pattern rules. +* Automatic Variables:: How to use automatic variables in the + recipe of implicit rules. +* Pattern Match:: How patterns match. +* Match-Anything Rules:: Precautions you should take prior to + defining rules that can match any + target file whatever. +* Canceling Rules:: How to override or cancel built-in rules. + +Using `make' to Update Archive Files + +* Archive Members:: Archive members as targets. +* Archive Update:: The implicit rule for archive member targets. +* Archive Pitfalls:: Dangers to watch out for when using archives. +* Archive Suffix Rules:: You can write a special kind of suffix rule + for updating archives. + +Implicit Rule for Archive Member Targets + +* Archive Symbols:: How to update archive symbol directories. + + +File: make.info, Node: Overview, Next: Introduction, Prev: Top, Up: Top + +1 Overview of `make' +******************** + +The `make' utility automatically determines which pieces of a large +program need to be recompiled, and issues commands to recompile them. +This manual describes GNU `make', which was implemented by Richard +Stallman and Roland McGrath. Development since Version 3.76 has been +handled by Paul D. Smith. + + GNU `make' conforms to section 6.2 of `IEEE Standard 1003.2-1992' +(POSIX.2). + + Our examples show C programs, since they are most common, but you +can use `make' with any programming language whose compiler can be run +with a shell command. Indeed, `make' is not limited to programs. You +can use it to describe any task where some files must be updated +automatically from others whenever the others change. + +* Menu: + +* Preparing:: Preparing and Running Make +* Reading:: On Reading this Text +* Bugs:: Problems and Bugs + + +File: make.info, Node: Preparing, Next: Reading, Prev: Overview, Up: Overview + +Preparing and Running Make +========================== + + To prepare to use `make', you must write a file called the +"makefile" that describes the relationships among files in your program +and provides commands for updating each file. In a program, typically, +the executable file is updated from object files, which are in turn +made by compiling source files. + + Once a suitable makefile exists, each time you change some source +files, this simple shell command: + + make + +suffices to perform all necessary recompilations. The `make' program +uses the makefile data base and the last-modification times of the +files to decide which of the files need to be updated. For each of +those files, it issues the recipes recorded in the data base. + + You can provide command line arguments to `make' to control which +files should be recompiled, or how. *Note How to Run `make': Running. + + +File: make.info, Node: Reading, Next: Bugs, Prev: Preparing, Up: Overview + +1.1 How to Read This Manual +=========================== + +If you are new to `make', or are looking for a general introduction, +read the first few sections of each chapter, skipping the later +sections. In each chapter, the first few sections contain introductory +or general information and the later sections contain specialized or +technical information. The exception is the second chapter, *note An +Introduction to Makefiles: Introduction, all of which is introductory. + + If you are familiar with other `make' programs, see *note Features +of GNU `make': Features, which lists the enhancements GNU `make' has, +and *note Incompatibilities and Missing Features: Missing, which +explains the few things GNU `make' lacks that others have. + + For a quick summary, see *note Options Summary::, *note Quick +Reference::, and *note Special Targets::. + + +File: make.info, Node: Bugs, Prev: Reading, Up: Overview + +1.2 Problems and Bugs +===================== + +If you have problems with GNU `make' or think you've found a bug, +please report it to the developers; we cannot promise to do anything but +we might well want to fix it. + + Before reporting a bug, make sure you've actually found a real bug. +Carefully reread the documentation and see if it really says you can do +what you're trying to do. If it's not clear whether you should be able +to do something or not, report that too; it's a bug in the +documentation! + + Before reporting a bug or trying to fix it yourself, try to isolate +it to the smallest possible makefile that reproduces the problem. Then +send us the makefile and the exact results `make' gave you, including +any error or warning messages. Please don't paraphrase these messages: +it's best to cut and paste them into your report. When generating this +small makefile, be sure to not use any non-free or unusual tools in +your recipes: you can almost always emulate what such a tool would do +with simple shell commands. Finally, be sure to explain what you +expected to occur; this will help us decide whether the problem was +really in the documentation. + + Once you have a precise problem you can report it in one of two ways. +Either send electronic mail to: + + bug-make@gnu.org + +or use our Web-based project management tool, at: + + http://savannah.gnu.org/projects/make/ + +In addition to the information above, please be careful to include the +version number of `make' you are using. You can get this information +with the command `make --version'. Be sure also to include the type of +machine and operating system you are using. One way to obtain this +information is by looking at the final lines of output from the command +`make --help'. + + +File: make.info, Node: Introduction, Next: Makefiles, Prev: Overview, Up: Top + +2 An Introduction to Makefiles +****************************** + +You need a file called a "makefile" to tell `make' what to do. Most +often, the makefile tells `make' how to compile and link a program. + + In this chapter, we will discuss a simple makefile that describes +how to compile and link a text editor which consists of eight C source +files and three header files. The makefile can also tell `make' how to +run miscellaneous commands when explicitly asked (for example, to remove +certain files as a clean-up operation). To see a more complex example +of a makefile, see *note Complex Makefile::. + + When `make' recompiles the editor, each changed C source file must +be recompiled. If a header file has changed, each C source file that +includes the header file must be recompiled to be safe. Each +compilation produces an object file corresponding to the source file. +Finally, if any source file has been recompiled, all the object files, +whether newly made or saved from previous compilations, must be linked +together to produce the new executable editor. + +* Menu: + +* Rule Introduction:: What a rule looks like. +* Simple Makefile:: A Simple Makefile +* How Make Works:: How `make' Processes This Makefile +* Variables Simplify:: Variables Make Makefiles Simpler +* make Deduces:: Letting `make' Deduce the Recipes +* Combine By Prerequisite:: Another Style of Makefile +* Cleanup:: Rules for Cleaning the Directory + + +File: make.info, Node: Rule Introduction, Next: Simple Makefile, Prev: Introduction, Up: Introduction + +2.1 What a Rule Looks Like +========================== + +A simple makefile consists of "rules" with the following shape: + + TARGET ... : PREREQUISITES ... + RECIPE + ... + ... + + A "target" is usually the name of a file that is generated by a +program; examples of targets are executable or object files. A target +can also be the name of an action to carry out, such as `clean' (*note +Phony Targets::). + + A "prerequisite" is a file that is used as input to create the +target. A target often depends on several files. + + A "recipe" is an action that `make' carries out. A recipe may have +more than one command, either on the same line or each on its own line. +*Please note:* you need to put a tab character at the beginning of +every recipe line! This is an obscurity that catches the unwary. If +you prefer to prefix your recipes with a character other than tab, you +can set the `.RECIPEPREFIX' variable to an alternate character (*note +Special Variables::). + + Usually a recipe is in a rule with prerequisites and serves to +create a target file if any of the prerequisites change. However, the +rule that specifies a recipe for the target need not have +prerequisites. For example, the rule containing the delete command +associated with the target `clean' does not have prerequisites. + + A "rule", then, explains how and when to remake certain files which +are the targets of the particular rule. `make' carries out the recipe +on the prerequisites to create or update the target. A rule can also +explain how and when to carry out an action. *Note Writing Rules: +Rules. + + A makefile may contain other text besides rules, but a simple +makefile need only contain rules. Rules may look somewhat more +complicated than shown in this template, but all fit the pattern more +or less. + + +File: make.info, Node: Simple Makefile, Next: How Make Works, Prev: Rule Introduction, Up: Introduction + +2.2 A Simple Makefile +===================== + +Here is a straightforward makefile that describes the way an executable +file called `edit' depends on eight object files which, in turn, depend +on eight C source and three header files. + + In this example, all the C files include `defs.h', but only those +defining editing commands include `command.h', and only low level files +that change the editor buffer include `buffer.h'. + + edit : main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + cc -o edit main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + + main.o : main.c defs.h + cc -c main.c + kbd.o : kbd.c defs.h command.h + cc -c kbd.c + command.o : command.c defs.h command.h + cc -c command.c + display.o : display.c defs.h buffer.h + cc -c display.c + insert.o : insert.c defs.h buffer.h + cc -c insert.c + search.o : search.c defs.h buffer.h + cc -c search.c + files.o : files.c defs.h buffer.h command.h + cc -c files.c + utils.o : utils.c defs.h + cc -c utils.c + clean : + rm edit main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + +We split each long line into two lines using backslash-newline; this is +like using one long line, but is easier to read. + + To use this makefile to create the executable file called `edit', +type: + + make + + To use this makefile to delete the executable file and all the object +files from the directory, type: + + make clean + + In the example makefile, the targets include the executable file +`edit', and the object files `main.o' and `kbd.o'. The prerequisites +are files such as `main.c' and `defs.h'. In fact, each `.o' file is +both a target and a prerequisite. Recipes include `cc -c main.c' and +`cc -c kbd.c'. + + When a target is a file, it needs to be recompiled or relinked if any +of its prerequisites change. In addition, any prerequisites that are +themselves automatically generated should be updated first. In this +example, `edit' depends on each of the eight object files; the object +file `main.o' depends on the source file `main.c' and on the header +file `defs.h'. + + A recipe may follow each line that contains a target and +prerequisites. These recipes say how to update the target file. A tab +character (or whatever character is specified by the `.RECIPEPREFIX' +variable; *note Special Variables::) must come at the beginning of +every line in the recipe to distinguish recipes from other lines in the +makefile. (Bear in mind that `make' does not know anything about how +the recipes work. It is up to you to supply recipes that will update +the target file properly. All `make' does is execute the recipe you +have specified when the target file needs to be updated.) + + The target `clean' is not a file, but merely the name of an action. +Since you normally do not want to carry out the actions in this rule, +`clean' is not a prerequisite of any other rule. Consequently, `make' +never does anything with it unless you tell it specifically. Note that +this rule not only is not a prerequisite, it also does not have any +prerequisites, so the only purpose of the rule is to run the specified +recipe. Targets that do not refer to files but are just actions are +called "phony targets". *Note Phony Targets::, for information about +this kind of target. *Note Errors in Recipes: Errors, to see how to +cause `make' to ignore errors from `rm' or any other command. + + +File: make.info, Node: How Make Works, Next: Variables Simplify, Prev: Simple Makefile, Up: Introduction + +2.3 How `make' Processes a Makefile +=================================== + +By default, `make' starts with the first target (not targets whose +names start with `.'). This is called the "default goal". ("Goals" +are the targets that `make' strives ultimately to update. You can +override this behavior using the command line (*note Arguments to +Specify the Goals: Goals.) or with the `.DEFAULT_GOAL' special variable +(*note Other Special Variables: Special Variables.). + + In the simple example of the previous section, the default goal is to +update the executable program `edit'; therefore, we put that rule first. + + Thus, when you give the command: + + make + +`make' reads the makefile in the current directory and begins by +processing the first rule. In the example, this rule is for relinking +`edit'; but before `make' can fully process this rule, it must process +the rules for the files that `edit' depends on, which in this case are +the object files. Each of these files is processed according to its +own rule. These rules say to update each `.o' file by compiling its +source file. The recompilation must be done if the source file, or any +of the header files named as prerequisites, is more recent than the +object file, or if the object file does not exist. + + The other rules are processed because their targets appear as +prerequisites of the goal. If some other rule is not depended on by the +goal (or anything it depends on, etc.), that rule is not processed, +unless you tell `make' to do so (with a command such as `make clean'). + + Before recompiling an object file, `make' considers updating its +prerequisites, the source file and header files. This makefile does not +specify anything to be done for them--the `.c' and `.h' files are not +the targets of any rules--so `make' does nothing for these files. But +`make' would update automatically generated C programs, such as those +made by Bison or Yacc, by their own rules at this time. + + After recompiling whichever object files need it, `make' decides +whether to relink `edit'. This must be done if the file `edit' does +not exist, or if any of the object files are newer than it. If an +object file was just recompiled, it is now newer than `edit', so `edit' +is relinked. + + Thus, if we change the file `insert.c' and run `make', `make' will +compile that file to update `insert.o', and then link `edit'. If we +change the file `command.h' and run `make', `make' will recompile the +object files `kbd.o', `command.o' and `files.o' and then link the file +`edit'. + + +File: make.info, Node: Variables Simplify, Next: make Deduces, Prev: How Make Works, Up: Introduction + +2.4 Variables Make Makefiles Simpler +==================================== + +In our example, we had to list all the object files twice in the rule +for `edit' (repeated here): + + edit : main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + cc -o edit main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + + Such duplication is error-prone; if a new object file is added to the +system, we might add it to one list and forget the other. We can +eliminate the risk and simplify the makefile by using a variable. +"Variables" allow a text string to be defined once and substituted in +multiple places later (*note How to Use Variables: Using Variables.). + + It is standard practice for every makefile to have a variable named +`objects', `OBJECTS', `objs', `OBJS', `obj', or `OBJ' which is a list +of all object file names. We would define such a variable `objects' +with a line like this in the makefile: + + objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + +Then, each place we want to put a list of the object file names, we can +substitute the variable's value by writing `$(objects)' (*note How to +Use Variables: Using Variables.). + + Here is how the complete simple makefile looks when you use a +variable for the object files: + + objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + + edit : $(objects) + cc -o edit $(objects) + main.o : main.c defs.h + cc -c main.c + kbd.o : kbd.c defs.h command.h + cc -c kbd.c + command.o : command.c defs.h command.h + cc -c command.c + display.o : display.c defs.h buffer.h + cc -c display.c + insert.o : insert.c defs.h buffer.h + cc -c insert.c + search.o : search.c defs.h buffer.h + cc -c search.c + files.o : files.c defs.h buffer.h command.h + cc -c files.c + utils.o : utils.c defs.h + cc -c utils.c + clean : + rm edit $(objects) + + +File: make.info, Node: make Deduces, Next: Combine By Prerequisite, Prev: Variables Simplify, Up: Introduction + +2.5 Letting `make' Deduce the Recipes +===================================== + +It is not necessary to spell out the recipes for compiling the +individual C source files, because `make' can figure them out: it has an +"implicit rule" for updating a `.o' file from a correspondingly named +`.c' file using a `cc -c' command. For example, it will use the recipe +`cc -c main.c -o main.o' to compile `main.c' into `main.o'. We can +therefore omit the recipes from the rules for the object files. *Note +Using Implicit Rules: Implicit Rules. + + When a `.c' file is used automatically in this way, it is also +automatically added to the list of prerequisites. We can therefore omit +the `.c' files from the prerequisites, provided we omit the recipe. + + Here is the entire example, with both of these changes, and a +variable `objects' as suggested above: + + objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + + edit : $(objects) + cc -o edit $(objects) + + main.o : defs.h + kbd.o : defs.h command.h + command.o : defs.h command.h + display.o : defs.h buffer.h + insert.o : defs.h buffer.h + search.o : defs.h buffer.h + files.o : defs.h buffer.h command.h + utils.o : defs.h + + .PHONY : clean + clean : + rm edit $(objects) + +This is how we would write the makefile in actual practice. (The +complications associated with `clean' are described elsewhere. See +*note Phony Targets::, and *note Errors in Recipes: Errors.) + + Because implicit rules are so convenient, they are important. You +will see them used frequently. + + +File: make.info, Node: Combine By Prerequisite, Next: Cleanup, Prev: make Deduces, Up: Introduction + +2.6 Another Style of Makefile +============================= + +When the objects of a makefile are created only by implicit rules, an +alternative style of makefile is possible. In this style of makefile, +you group entries by their prerequisites instead of by their targets. +Here is what one looks like: + + objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + + edit : $(objects) + cc -o edit $(objects) + + $(objects) : defs.h + kbd.o command.o files.o : command.h + display.o insert.o search.o files.o : buffer.h + +Here `defs.h' is given as a prerequisite of all the object files; +`command.h' and `buffer.h' are prerequisites of the specific object +files listed for them. + + Whether this is better is a matter of taste: it is more compact, but +some people dislike it because they find it clearer to put all the +information about each target in one place. + + +File: make.info, Node: Cleanup, Prev: Combine By Prerequisite, Up: Introduction + +2.7 Rules for Cleaning the Directory +==================================== + +Compiling a program is not the only thing you might want to write rules +for. Makefiles commonly tell how to do a few other things besides +compiling a program: for example, how to delete all the object files +and executables so that the directory is `clean'. + + Here is how we could write a `make' rule for cleaning our example +editor: + + clean: + rm edit $(objects) + + In practice, we might want to write the rule in a somewhat more +complicated manner to handle unanticipated situations. We would do +this: + + .PHONY : clean + clean : + -rm edit $(objects) + +This prevents `make' from getting confused by an actual file called +`clean' and causes it to continue in spite of errors from `rm'. (See +*note Phony Targets::, and *note Errors in Recipes: Errors.) + +A rule such as this should not be placed at the beginning of the +makefile, because we do not want it to run by default! Thus, in the +example makefile, we want the rule for `edit', which recompiles the +editor, to remain the default goal. + + Since `clean' is not a prerequisite of `edit', this rule will not +run at all if we give the command `make' with no arguments. In order +to make the rule run, we have to type `make clean'. *Note How to Run +`make': Running. + + +File: make.info, Node: Makefiles, Next: Rules, Prev: Introduction, Up: Top + +3 Writing Makefiles +******************* + +The information that tells `make' how to recompile a system comes from +reading a data base called the "makefile". + +* Menu: + +* Makefile Contents:: What makefiles contain. +* Makefile Names:: How to name your makefile. +* Include:: How one makefile can use another makefile. +* MAKEFILES Variable:: The environment can specify extra makefiles. +* Remaking Makefiles:: How makefiles get remade. +* Overriding Makefiles:: How to override part of one makefile + with another makefile. +* Reading Makefiles:: How makefiles are parsed. +* Secondary Expansion:: How and when secondary expansion is performed. + + +File: make.info, Node: Makefile Contents, Next: Makefile Names, Prev: Makefiles, Up: Makefiles + +3.1 What Makefiles Contain +========================== + +Makefiles contain five kinds of things: "explicit rules", "implicit +rules", "variable definitions", "directives", and "comments". Rules, +variables, and directives are described at length in later chapters. + + * An "explicit rule" says when and how to remake one or more files, + called the rule's "targets". It lists the other files that the + targets depend on, called the "prerequisites" of the target, and + may also give a recipe to use to create or update the targets. + *Note Writing Rules: Rules. + + * An "implicit rule" says when and how to remake a class of files + based on their names. It describes how a target may depend on a + file with a name similar to the target and gives a recipe to + create or update such a target. *Note Using Implicit Rules: + Implicit Rules. + + * A "variable definition" is a line that specifies a text string + value for a variable that can be substituted into the text later. + The simple makefile example shows a variable definition for + `objects' as a list of all object files (*note Variables Make + Makefiles Simpler: Variables Simplify.). + + * A "directive" is an instruction for `make' to do something special + while reading the makefile. These include: + + * Reading another makefile (*note Including Other Makefiles: + Include.). + + * Deciding (based on the values of variables) whether to use or + ignore a part of the makefile (*note Conditional Parts of + Makefiles: Conditionals.). + + * Defining a variable from a verbatim string containing + multiple lines (*note Defining Multi-Line Variables: + Multi-Line.). + + * `#' in a line of a makefile starts a "comment". It and the rest + of the line are ignored, except that a trailing backslash not + escaped by another backslash will continue the comment across + multiple lines. A line containing just a comment (with perhaps + spaces before it) is effectively blank, and is ignored. If you + want a literal `#', escape it with a backslash (e.g., `\#'). + Comments may appear on any line in the makefile, although they are + treated specially in certain situations. + + You cannot use comments within variable references or function + calls: any instance of `#' will be treated literally (rather than + as the start of a comment) inside a variable reference or function + call. + + Comments within a recipe are passed to the shell, just as with any + other recipe text. The shell decides how to interpret it: whether + or not this is a comment is up to the shell. + + Within a `define' directive, comments are not ignored during the + definition of the variable, but rather kept intact in the value of + the variable. When the variable is expanded they will either be + treated as `make' comments or as recipe text, depending on the + context in which the variable is evaluated. + + +File: make.info, Node: Makefile Names, Next: Include, Prev: Makefile Contents, Up: Makefiles + +3.2 What Name to Give Your Makefile +=================================== + +By default, when `make' looks for the makefile, it tries the following +names, in order: `GNUmakefile', `makefile' and `Makefile'. + + Normally you should call your makefile either `makefile' or +`Makefile'. (We recommend `Makefile' because it appears prominently +near the beginning of a directory listing, right near other important +files such as `README'.) The first name checked, `GNUmakefile', is not +recommended for most makefiles. You should use this name if you have a +makefile that is specific to GNU `make', and will not be understood by +other versions of `make'. Other `make' programs look for `makefile' and +`Makefile', but not `GNUmakefile'. + + If `make' finds none of these names, it does not use any makefile. +Then you must specify a goal with a command argument, and `make' will +attempt to figure out how to remake it using only its built-in implicit +rules. *Note Using Implicit Rules: Implicit Rules. + + If you want to use a nonstandard name for your makefile, you can +specify the makefile name with the `-f' or `--file' option. The +arguments `-f NAME' or `--file=NAME' tell `make' to read the file NAME +as the makefile. If you use more than one `-f' or `--file' option, you +can specify several makefiles. All the makefiles are effectively +concatenated in the order specified. The default makefile names +`GNUmakefile', `makefile' and `Makefile' are not checked automatically +if you specify `-f' or `--file'. + + +File: make.info, Node: Include, Next: MAKEFILES Variable, Prev: Makefile Names, Up: Makefiles + +3.3 Including Other Makefiles +============================= + +The `include' directive tells `make' to suspend reading the current +makefile and read one or more other makefiles before continuing. The +directive is a line in the makefile that looks like this: + + include FILENAMES... + +FILENAMES can contain shell file name patterns. If FILENAMES is empty, +nothing is included and no error is printed. + + Extra spaces are allowed and ignored at the beginning of the line, +but the first character must not be a tab (or the value of +`.RECIPEPREFIX')--if the line begins with a tab, it will be considered +a recipe line. Whitespace is required between `include' and the file +names, and between file names; extra whitespace is ignored there and at +the end of the directive. A comment starting with `#' is allowed at +the end of the line. If the file names contain any variable or +function references, they are expanded. *Note How to Use Variables: +Using Variables. + + For example, if you have three `.mk' files, `a.mk', `b.mk', and +`c.mk', and `$(bar)' expands to `bish bash', then the following +expression + + include foo *.mk $(bar) + + is equivalent to + + include foo a.mk b.mk c.mk bish bash + + When `make' processes an `include' directive, it suspends reading of +the containing makefile and reads from each listed file in turn. When +that is finished, `make' resumes reading the makefile in which the +directive appears. + + One occasion for using `include' directives is when several programs, +handled by individual makefiles in various directories, need to use a +common set of variable definitions (*note Setting Variables: Setting.) +or pattern rules (*note Defining and Redefining Pattern Rules: Pattern +Rules.). + + Another such occasion is when you want to generate prerequisites from +source files automatically; the prerequisites can be put in a file that +is included by the main makefile. This practice is generally cleaner +than that of somehow appending the prerequisites to the end of the main +makefile as has been traditionally done with other versions of `make'. +*Note Automatic Prerequisites::. + + If the specified name does not start with a slash, and the file is +not found in the current directory, several other directories are +searched. First, any directories you have specified with the `-I' or +`--include-dir' option are searched (*note Summary of Options: Options +Summary.). Then the following directories (if they exist) are +searched, in this order: `PREFIX/include' (normally `/usr/local/include' +(1)) `/usr/gnu/include', `/usr/local/include', `/usr/include'. + + If an included makefile cannot be found in any of these directories, +a warning message is generated, but it is not an immediately fatal +error; processing of the makefile containing the `include' continues. +Once it has finished reading makefiles, `make' will try to remake any +that are out of date or don't exist. *Note How Makefiles Are Remade: +Remaking Makefiles. Only after it has tried to find a way to remake a +makefile and failed, will `make' diagnose the missing makefile as a +fatal error. + + If you want `make' to simply ignore a makefile which does not exist +or cannot be remade, with no error message, use the `-include' +directive instead of `include', like this: + + -include FILENAMES... + + This acts like `include' in every way except that there is no error +(not even a warning) if any of the FILENAMES (or any prerequisites of +any of the FILENAMES) do not exist or cannot be remade. + + For compatibility with some other `make' implementations, `sinclude' +is another name for `-include'. + + ---------- Footnotes ---------- + + (1) GNU Make compiled for MS-DOS and MS-Windows behaves as if PREFIX +has been defined to be the root of the DJGPP tree hierarchy. + + +File: make.info, Node: MAKEFILES Variable, Next: Remaking Makefiles, Prev: Include, Up: Makefiles + +3.4 The Variable `MAKEFILES' +============================ + +If the environment variable `MAKEFILES' is defined, `make' considers +its value as a list of names (separated by whitespace) of additional +makefiles to be read before the others. This works much like the +`include' directive: various directories are searched for those files +(*note Including Other Makefiles: Include.). In addition, the default +goal is never taken from one of these makefiles (or any makefile +included by them) and it is not an error if the files listed in +`MAKEFILES' are not found. + + The main use of `MAKEFILES' is in communication between recursive +invocations of `make' (*note Recursive Use of `make': Recursion.). It +usually is not desirable to set the environment variable before a +top-level invocation of `make', because it is usually better not to +mess with a makefile from outside. However, if you are running `make' +without a specific makefile, a makefile in `MAKEFILES' can do useful +things to help the built-in implicit rules work better, such as +defining search paths (*note Directory Search::). + + Some users are tempted to set `MAKEFILES' in the environment +automatically on login, and program makefiles to expect this to be done. +This is a very bad idea, because such makefiles will fail to work if +run by anyone else. It is much better to write explicit `include' +directives in the makefiles. *Note Including Other Makefiles: Include. + + +File: make.info, Node: Remaking Makefiles, Next: Overriding Makefiles, Prev: MAKEFILES Variable, Up: Makefiles + +3.5 How Makefiles Are Remade +============================ + +Sometimes makefiles can be remade from other files, such as RCS or SCCS +files. If a makefile can be remade from other files, you probably want +`make' to get an up-to-date version of the makefile to read in. + + To this end, after reading in all makefiles, `make' will consider +each as a goal target and attempt to update it. If a makefile has a +rule which says how to update it (found either in that very makefile or +in another one) or if an implicit rule applies to it (*note Using +Implicit Rules: Implicit Rules.), it will be updated if necessary. +After all makefiles have been checked, if any have actually been +changed, `make' starts with a clean slate and reads all the makefiles +over again. (It will also attempt to update each of them over again, +but normally this will not change them again, since they are already up +to date.) + + If you know that one or more of your makefiles cannot be remade and +you want to keep `make' from performing an implicit rule search on +them, perhaps for efficiency reasons, you can use any normal method of +preventing implicit rule lookup to do so. For example, you can write +an explicit rule with the makefile as the target, and an empty recipe +(*note Using Empty Recipes: Empty Recipes.). + + If the makefiles specify a double-colon rule to remake a file with a +recipe but no prerequisites, that file will always be remade (*note +Double-Colon::). In the case of makefiles, a makefile that has a +double-colon rule with a recipe but no prerequisites will be remade +every time `make' is run, and then again after `make' starts over and +reads the makefiles in again. This would cause an infinite loop: +`make' would constantly remake the makefile, and never do anything +else. So, to avoid this, `make' will *not* attempt to remake makefiles +which are specified as targets of a double-colon rule with a recipe but +no prerequisites. + + If you do not specify any makefiles to be read with `-f' or `--file' +options, `make' will try the default makefile names; *note What Name to +Give Your Makefile: Makefile Names. Unlike makefiles explicitly +requested with `-f' or `--file' options, `make' is not certain that +these makefiles should exist. However, if a default makefile does not +exist but can be created by running `make' rules, you probably want the +rules to be run so that the makefile can be used. + + Therefore, if none of the default makefiles exists, `make' will try +to make each of them in the same order in which they are searched for +(*note What Name to Give Your Makefile: Makefile Names.) until it +succeeds in making one, or it runs out of names to try. Note that it +is not an error if `make' cannot find or make any makefile; a makefile +is not always necessary. + + When you use the `-t' or `--touch' option (*note Instead of +Executing Recipes: Instead of Execution.), you would not want to use an +out-of-date makefile to decide which targets to touch. So the `-t' +option has no effect on updating makefiles; they are really updated +even if `-t' is specified. Likewise, `-q' (or `--question') and `-n' +(or `--just-print') do not prevent updating of makefiles, because an +out-of-date makefile would result in the wrong output for other targets. +Thus, `make -f mfile -n foo' will update `mfile', read it in, and then +print the recipe to update `foo' and its prerequisites without running +it. The recipe printed for `foo' will be the one specified in the +updated contents of `mfile'. + + However, on occasion you might actually wish to prevent updating of +even the makefiles. You can do this by specifying the makefiles as +goals in the command line as well as specifying them as makefiles. +When the makefile name is specified explicitly as a goal, the options +`-t' and so on do apply to them. + + Thus, `make -f mfile -n mfile foo' would read the makefile `mfile', +print the recipe needed to update it without actually running it, and +then print the recipe needed to update `foo' without running that. The +recipe for `foo' will be the one specified by the existing contents of +`mfile'. + + +File: make.info, Node: Overriding Makefiles, Next: Reading Makefiles, Prev: Remaking Makefiles, Up: Makefiles + +3.6 Overriding Part of Another Makefile +======================================= + +Sometimes it is useful to have a makefile that is mostly just like +another makefile. You can often use the `include' directive to include +one in the other, and add more targets or variable definitions. +However, it is illegal for two makefiles to give different recipes for +the same target. But there is another way. + + In the containing makefile (the one that wants to include the other), +you can use a match-anything pattern rule to say that to remake any +target that cannot be made from the information in the containing +makefile, `make' should look in another makefile. *Note Pattern +Rules::, for more information on pattern rules. + + For example, if you have a makefile called `Makefile' that says how +to make the target `foo' (and other targets), you can write a makefile +called `GNUmakefile' that contains: + + foo: + frobnicate > foo + + %: force + @$(MAKE) -f Makefile $@ + force: ; + + If you say `make foo', `make' will find `GNUmakefile', read it, and +see that to make `foo', it needs to run the recipe `frobnicate > foo'. +If you say `make bar', `make' will find no way to make `bar' in +`GNUmakefile', so it will use the recipe from the pattern rule: `make +-f Makefile bar'. If `Makefile' provides a rule for updating `bar', +`make' will apply the rule. And likewise for any other target that +`GNUmakefile' does not say how to make. + + The way this works is that the pattern rule has a pattern of just +`%', so it matches any target whatever. The rule specifies a +prerequisite `force', to guarantee that the recipe will be run even if +the target file already exists. We give the `force' target an empty +recipe to prevent `make' from searching for an implicit rule to build +it--otherwise it would apply the same match-anything rule to `force' +itself and create a prerequisite loop! + + +File: make.info, Node: Reading Makefiles, Next: Secondary Expansion, Prev: Overriding Makefiles, Up: Makefiles + +3.7 How `make' Reads a Makefile +=============================== + +GNU `make' does its work in two distinct phases. During the first +phase it reads all the makefiles, included makefiles, etc. and +internalizes all the variables and their values, implicit and explicit +rules, and constructs a dependency graph of all the targets and their +prerequisites. During the second phase, `make' uses these internal +structures to determine what targets will need to be rebuilt and to +invoke the rules necessary to do so. + + It's important to understand this two-phase approach because it has a +direct impact on how variable and function expansion happens; this is +often a source of some confusion when writing makefiles. Here we will +present a summary of the phases in which expansion happens for different +constructs within the makefile. We say that expansion is "immediate" +if it happens during the first phase: in this case `make' will expand +any variables or functions in that section of a construct as the +makefile is parsed. We say that expansion is "deferred" if expansion +is not performed immediately. Expansion of a deferred construct is not +performed until either the construct appears later in an immediate +context, or until the second phase. + + You may not be familiar with some of these constructs yet. You can +reference this section as you become familiar with them, in later +chapters. + +Variable Assignment +------------------- + +Variable definitions are parsed as follows: + + IMMEDIATE = DEFERRED + IMMEDIATE ?= DEFERRED + IMMEDIATE := IMMEDIATE + IMMEDIATE += DEFERRED or IMMEDIATE + + define IMMEDIATE + DEFERRED + endef + + define IMMEDIATE = + DEFERRED + endef + + define IMMEDIATE ?= + DEFERRED + endef + + define IMMEDIATE := + IMMEDIATE + endef + + define IMMEDIATE += + DEFERRED or IMMEDIATE + endef + + For the append operator, `+=', the right-hand side is considered +immediate if the variable was previously set as a simple variable +(`:='), and deferred otherwise. + +Conditional Directives +---------------------- + +Conditional directives are parsed immediately. This means, for +example, that automatic variables cannot be used in conditional +directives, as automatic variables are not set until the recipe for +that rule is invoked. If you need to use automatic variables in a +conditional directive you _must_ move the condition into the recipe and +use shell conditional syntax instead. + +Rule Definition +--------------- + +A rule is always expanded the same way, regardless of the form: + + IMMEDIATE : IMMEDIATE ; DEFERRED + DEFERRED + + That is, the target and prerequisite sections are expanded +immediately, and the recipe used to construct the target is always +deferred. This general rule is true for explicit rules, pattern rules, +suffix rules, static pattern rules, and simple prerequisite definitions. + + +File: make.info, Node: Secondary Expansion, Prev: Reading Makefiles, Up: Makefiles + +3.8 Secondary Expansion +======================= + +In the previous section we learned that GNU `make' works in two +distinct phases: a read-in phase and a target-update phase (*note How +`make' Reads a Makefile: Reading Makefiles.). GNU make also has the +ability to enable a _second expansion_ of the prerequisites (only) for +some or all targets defined in the makefile. In order for this second +expansion to occur, the special target `.SECONDEXPANSION' must be +defined before the first prerequisite list that makes use of this +feature. + + If that special target is defined then in between the two phases +mentioned above, right at the end of the read-in phase, all the +prerequisites of the targets defined after the special target are +expanded a _second time_. In most circumstances this secondary +expansion will have no effect, since all variable and function +references will have been expanded during the initial parsing of the +makefiles. In order to take advantage of the secondary expansion phase +of the parser, then, it's necessary to _escape_ the variable or +function reference in the makefile. In this case the first expansion +merely un-escapes the reference but doesn't expand it, and expansion is +left to the secondary expansion phase. For example, consider this +makefile: + + .SECONDEXPANSION: + ONEVAR = onefile + TWOVAR = twofile + myfile: $(ONEVAR) $$(TWOVAR) + + After the first expansion phase the prerequisites list of the +`myfile' target will be `onefile' and `$(TWOVAR)'; the first +(unescaped) variable reference to ONEVAR is expanded, while the second +(escaped) variable reference is simply unescaped, without being +recognized as a variable reference. Now during the secondary expansion +the first word is expanded again but since it contains no variable or +function references it remains the static value `onefile', while the +second word is now a normal reference to the variable TWOVAR, which is +expanded to the value `twofile'. The final result is that there are +two prerequisites, `onefile' and `twofile'. + + Obviously, this is not a very interesting case since the same result +could more easily have been achieved simply by having both variables +appear, unescaped, in the prerequisites list. One difference becomes +apparent if the variables are reset; consider this example: + + .SECONDEXPANSION: + AVAR = top + onefile: $(AVAR) + twofile: $$(AVAR) + AVAR = bottom + + Here the prerequisite of `onefile' will be expanded immediately, and +resolve to the value `top', while the prerequisite of `twofile' will +not be full expanded until the secondary expansion and yield a value of +`bottom'. + + This is marginally more exciting, but the true power of this feature +only becomes apparent when you discover that secondary expansions +always take place within the scope of the automatic variables for that +target. This means that you can use variables such as `$@', `$*', etc. +during the second expansion and they will have their expected values, +just as in the recipe. All you have to do is defer the expansion by +escaping the `$'. Also, secondary expansion occurs for both explicit +and implicit (pattern) rules. Knowing this, the possible uses for this +feature increase dramatically. For example: + + .SECONDEXPANSION: + main_OBJS := main.o try.o test.o + lib_OBJS := lib.o api.o + + main lib: $$($$@_OBJS) + + Here, after the initial expansion the prerequisites of both the +`main' and `lib' targets will be `$($@_OBJS)'. During the secondary +expansion, the `$@' variable is set to the name of the target and so +the expansion for the `main' target will yield `$(main_OBJS)', or +`main.o try.o test.o', while the secondary expansion for the `lib' +target will yield `$(lib_OBJS)', or `lib.o api.o'. + + You can also mix in functions here, as long as they are properly +escaped: + + main_SRCS := main.c try.c test.c + lib_SRCS := lib.c api.c + + .SECONDEXPANSION: + main lib: $$(patsubst %.c,%.o,$$($$@_SRCS)) + + This version allows users to specify source files rather than object +files, but gives the same resulting prerequisites list as the previous +example. + + Evaluation of automatic variables during the secondary expansion +phase, especially of the target name variable `$$@', behaves similarly +to evaluation within recipes. However, there are some subtle +differences and "corner cases" which come into play for the different +types of rule definitions that `make' understands. The subtleties of +using the different automatic variables are described below. + +Secondary Expansion of Explicit Rules +------------------------------------- + +During the secondary expansion of explicit rules, `$$@' and `$$%' +evaluate, respectively, to the file name of the target and, when the +target is an archive member, the target member name. The `$$<' +variable evaluates to the first prerequisite in the first rule for this +target. `$$^' and `$$+' evaluate to the list of all prerequisites of +rules _that have already appeared_ for the same target (`$$+' with +repetitions and `$$^' without). The following example will help +illustrate these behaviors: + + .SECONDEXPANSION: + + foo: foo.1 bar.1 $$< $$^ $$+ # line #1 + + foo: foo.2 bar.2 $$< $$^ $$+ # line #2 + + foo: foo.3 bar.3 $$< $$^ $$+ # line #3 + + In the first prerequisite list, all three variables (`$$<', `$$^', +and `$$+') expand to the empty string. In the second, they will have +values `foo.1', `foo.1 bar.1', and `foo.1 bar.1' respectively. In the +third they will have values `foo.1', `foo.1 bar.1 foo.2 bar.2', and +`foo.1 bar.1 foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1' respectively. + + Rules undergo secondary expansion in makefile order, except that the +rule with the recipe is always evaluated last. + + The variables `$$?' and `$$*' are not available and expand to the +empty string. + +Secondary Expansion of Static Pattern Rules +------------------------------------------- + +Rules for secondary expansion of static pattern rules are identical to +those for explicit rules, above, with one exception: for static pattern +rules the `$$*' variable is set to the pattern stem. As with explicit +rules, `$$?' is not available and expands to the empty string. + +Secondary Expansion of Implicit Rules +------------------------------------- + +As `make' searches for an implicit rule, it substitutes the stem and +then performs secondary expansion for every rule with a matching target +pattern. The value of the automatic variables is derived in the same +fashion as for static pattern rules. As an example: + + .SECONDEXPANSION: + + foo: bar + + foo foz: fo%: bo% + + %oo: $$< $$^ $$+ $$* + + When the implicit rule is tried for target `foo', `$$<' expands to +`bar', `$$^' expands to `bar boo', `$$+' also expands to `bar boo', and +`$$*' expands to `f'. + + Note that the directory prefix (D), as described in *note Implicit +Rule Search Algorithm: Implicit Rule Search, is appended (after +expansion) to all the patterns in the prerequisites list. As an +example: + + .SECONDEXPANSION: + + /tmp/foo.o: + + %.o: $$(addsuffix /%.c,foo bar) foo.h + + The prerequisite list after the secondary expansion and directory +prefix reconstruction will be `/tmp/foo/foo.c /tmp/var/bar/foo.c +foo.h'. If you are not interested in this reconstruction, you can use +`$$*' instead of `%' in the prerequisites list. + + +File: make.info, Node: Rules, Next: Recipes, Prev: Makefiles, Up: Top + +4 Writing Rules +*************** + +A "rule" appears in the makefile and says when and how to remake +certain files, called the rule's "targets" (most often only one per +rule). It lists the other files that are the "prerequisites" of the +target, and the "recipe" to use to create or update the target. + + The order of rules is not significant, except for determining the +"default goal": the target for `make' to consider, if you do not +otherwise specify one. The default goal is the target of the first +rule in the first makefile. If the first rule has multiple targets, +only the first target is taken as the default. There are two +exceptions: a target starting with a period is not a default unless it +contains one or more slashes, `/', as well; and, a target that defines +a pattern rule has no effect on the default goal. (*Note Defining and +Redefining Pattern Rules: Pattern Rules.) + + Therefore, we usually write the makefile so that the first rule is +the one for compiling the entire program or all the programs described +by the makefile (often with a target called `all'). *Note Arguments to +Specify the Goals: Goals. + +* Menu: + +* Rule Example:: An example explained. +* Rule Syntax:: General syntax explained. +* Prerequisite Types:: There are two types of prerequisites. +* Wildcards:: Using wildcard characters such as `*'. +* Directory Search:: Searching other directories for source files. +* Phony Targets:: Using a target that is not a real file's name. +* Force Targets:: You can use a target without recipes + or prerequisites to mark other targets + as phony. +* Empty Targets:: When only the date matters and the + files are empty. +* Special Targets:: Targets with special built-in meanings. +* Multiple Targets:: When to make use of several targets in a rule. +* Multiple Rules:: How to use several rules with the same target. +* Static Pattern:: Static pattern rules apply to multiple targets + and can vary the prerequisites according to + the target name. +* Double-Colon:: How to use a special kind of rule to allow + several independent rules for one target. +* Automatic Prerequisites:: How to automatically generate rules giving + prerequisites from source files themselves. + + +File: make.info, Node: Rule Example, Next: Rule Syntax, Prev: Rules, Up: Rules + +4.1 Rule Example +================ + +Here is an example of a rule: + + foo.o : foo.c defs.h # module for twiddling the frobs + cc -c -g foo.c + + Its target is `foo.o' and its prerequisites are `foo.c' and +`defs.h'. It has one command in the recipe: `cc -c -g foo.c'. The +recipe starts with a tab to identify it as a recipe. + + This rule says two things: + + * How to decide whether `foo.o' is out of date: it is out of date if + it does not exist, or if either `foo.c' or `defs.h' is more recent + than it. + + * How to update the file `foo.o': by running `cc' as stated. The + recipe does not explicitly mention `defs.h', but we presume that + `foo.c' includes it, and that that is why `defs.h' was added to + the prerequisites. + + +File: make.info, Node: Rule Syntax, Next: Prerequisite Types, Prev: Rule Example, Up: Rules + +4.2 Rule Syntax +=============== + +In general, a rule looks like this: + + TARGETS : PREREQUISITES + RECIPE + ... + +or like this: + + TARGETS : PREREQUISITES ; RECIPE + RECIPE + ... + + The TARGETS are file names, separated by spaces. Wildcard +characters may be used (*note Using Wildcard Characters in File Names: +Wildcards.) and a name of the form `A(M)' represents member M in +archive file A (*note Archive Members as Targets: Archive Members.). +Usually there is only one target per rule, but occasionally there is a +reason to have more (*note Multiple Targets in a Rule: Multiple +Targets.). + + The RECIPE lines start with a tab character (or the first character +in the value of the `.RECIPEPREFIX' variable; *note Special +Variables::). The first recipe line may appear on the line after the +prerequisites, with a tab character, or may appear on the same line, +with a semicolon. Either way, the effect is the same. There are other +differences in the syntax of recipes. *Note Writing Recipes in Rules: +Recipes. + + Because dollar signs are used to start `make' variable references, +if you really want a dollar sign in a target or prerequisite you must +write two of them, `$$' (*note How to Use Variables: Using Variables.). +If you have enabled secondary expansion (*note Secondary Expansion::) +and you want a literal dollar sign in the prerequisites list, you must +actually write _four_ dollar signs (`$$$$'). + + You may split a long line by inserting a backslash followed by a +newline, but this is not required, as `make' places no limit on the +length of a line in a makefile. + + A rule tells `make' two things: when the targets are out of date, +and how to update them when necessary. + + The criterion for being out of date is specified in terms of the +PREREQUISITES, which consist of file names separated by spaces. +(Wildcards and archive members (*note Archives::) are allowed here too.) +A target is out of date if it does not exist or if it is older than any +of the prerequisites (by comparison of last-modification times). The +idea is that the contents of the target file are computed based on +information in the prerequisites, so if any of the prerequisites +changes, the contents of the existing target file are no longer +necessarily valid. + + How to update is specified by a RECIPE. This is one or more lines +to be executed by the shell (normally `sh'), but with some extra +features (*note Writing Recipes in Rules: Recipes.). + + +File: make.info, Node: Prerequisite Types, Next: Wildcards, Prev: Rule Syntax, Up: Rules + +4.3 Types of Prerequisites +========================== + +There are actually two different types of prerequisites understood by +GNU `make': normal prerequisites such as described in the previous +section, and "order-only" prerequisites. A normal prerequisite makes +two statements: first, it imposes an order in which recipes will be +invoked: the recipes for all prerequisites of a target will be +completed before the recipe for the target is run. Second, it imposes +a dependency relationship: if any prerequisite is newer than the +target, then the target is considered out-of-date and must be rebuilt. + + Normally, this is exactly what you want: if a target's prerequisite +is updated, then the target should also be updated. + + Occasionally, however, you have a situation where you want to impose +a specific ordering on the rules to be invoked _without_ forcing the +target to be updated if one of those rules is executed. In that case, +you want to define "order-only" prerequisites. Order-only +prerequisites can be specified by placing a pipe symbol (`|') in the +prerequisites list: any prerequisites to the left of the pipe symbol +are normal; any prerequisites to the right are order-only: + + TARGETS : NORMAL-PREREQUISITES | ORDER-ONLY-PREREQUISITES + + The normal prerequisites section may of course be empty. Also, you +may still declare multiple lines of prerequisites for the same target: +they are appended appropriately (normal prerequisites are appended to +the list of normal prerequisites; order-only prerequisites are appended +to the list of order-only prerequisites). Note that if you declare the +same file to be both a normal and an order-only prerequisite, the +normal prerequisite takes precedence (since they have a strict superset +of the behavior of an order-only prerequisite). + + Consider an example where your targets are to be placed in a separate +directory, and that directory might not exist before `make' is run. In +this situation, you want the directory to be created before any targets +are placed into it but, because the timestamps on directories change +whenever a file is added, removed, or renamed, we certainly don't want +to rebuild all the targets whenever the directory's timestamp changes. +One way to manage this is with order-only prerequisites: make the +directory an order-only prerequisite on all the targets: + + OBJDIR := objdir + OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o) + + $(OBJDIR)/%.o : %.c + $(COMPILE.c) $(OUTPUT_OPTION) $< + + all: $(OBJS) + + $(OBJS): | $(OBJDIR) + + $(OBJDIR): + mkdir $(OBJDIR) + + Now the rule to create the `objdir' directory will be run, if +needed, before any `.o' is built, but no `.o' will be built because the +`objdir' directory timestamp changed. + + +File: make.info, Node: Wildcards, Next: Directory Search, Prev: Prerequisite Types, Up: Rules + +4.4 Using Wildcard Characters in File Names +=========================================== + +A single file name can specify many files using "wildcard characters". +The wildcard characters in `make' are `*', `?' and `[...]', the same as +in the Bourne shell. For example, `*.c' specifies a list of all the +files (in the working directory) whose names end in `.c'. + + The character `~' at the beginning of a file name also has special +significance. If alone, or followed by a slash, it represents your home +directory. For example `~/bin' expands to `/home/you/bin'. If the `~' +is followed by a word, the string represents the home directory of the +user named by that word. For example `~john/bin' expands to +`/home/john/bin'. On systems which don't have a home directory for +each user (such as MS-DOS or MS-Windows), this functionality can be +simulated by setting the environment variable HOME. + + Wildcard expansion is performed by `make' automatically in targets +and in prerequisites. In recipes, the shell is responsible for +wildcard expansion. In other contexts, wildcard expansion happens only +if you request it explicitly with the `wildcard' function. + + The special significance of a wildcard character can be turned off by +preceding it with a backslash. Thus, `foo\*bar' would refer to a +specific file whose name consists of `foo', an asterisk, and `bar'. + +* Menu: + +* Wildcard Examples:: Several examples +* Wildcard Pitfall:: Problems to avoid. +* Wildcard Function:: How to cause wildcard expansion where + it does not normally take place. + + +File: make.info, Node: Wildcard Examples, Next: Wildcard Pitfall, Prev: Wildcards, Up: Wildcards + +4.4.1 Wildcard Examples +----------------------- + +Wildcards can be used in the recipe of a rule, where they are expanded +by the shell. For example, here is a rule to delete all the object +files: + + clean: + rm -f *.o + + Wildcards are also useful in the prerequisites of a rule. With the +following rule in the makefile, `make print' will print all the `.c' +files that have changed since the last time you printed them: + + print: *.c + lpr -p $? + touch print + +This rule uses `print' as an empty target file; see *note Empty Target +Files to Record Events: Empty Targets. (The automatic variable `$?' is +used to print only those files that have changed; see *note Automatic +Variables::.) + + Wildcard expansion does not happen when you define a variable. +Thus, if you write this: + + objects = *.o + +then the value of the variable `objects' is the actual string `*.o'. +However, if you use the value of `objects' in a target or prerequisite, +wildcard expansion will take place there. If you use the value of +`objects' in a recipe, the shell may perform wildcard expansion when +the recipe runs. To set `objects' to the expansion, instead use: + + objects := $(wildcard *.o) + +*Note Wildcard Function::. + + +File: make.info, Node: Wildcard Pitfall, Next: Wildcard Function, Prev: Wildcard Examples, Up: Wildcards + +4.4.2 Pitfalls of Using Wildcards +--------------------------------- + +Now here is an example of a naive way of using wildcard expansion, that +does not do what you would intend. Suppose you would like to say that +the executable file `foo' is made from all the object files in the +directory, and you write this: + + objects = *.o + + foo : $(objects) + cc -o foo $(CFLAGS) $(objects) + +The value of `objects' is the actual string `*.o'. Wildcard expansion +happens in the rule for `foo', so that each _existing_ `.o' file +becomes a prerequisite of `foo' and will be recompiled if necessary. + + But what if you delete all the `.o' files? When a wildcard matches +no files, it is left as it is, so then `foo' will depend on the +oddly-named file `*.o'. Since no such file is likely to exist, `make' +will give you an error saying it cannot figure out how to make `*.o'. +This is not what you want! + + Actually it is possible to obtain the desired result with wildcard +expansion, but you need more sophisticated techniques, including the +`wildcard' function and string substitution. *Note The Function +`wildcard': Wildcard Function. + + Microsoft operating systems (MS-DOS and MS-Windows) use backslashes +to separate directories in pathnames, like so: + + c:\foo\bar\baz.c + + This is equivalent to the Unix-style `c:/foo/bar/baz.c' (the `c:' +part is the so-called drive letter). When `make' runs on these +systems, it supports backslashes as well as the Unix-style forward +slashes in pathnames. However, this support does _not_ include the +wildcard expansion, where backslash is a quote character. Therefore, +you _must_ use Unix-style slashes in these cases. + + +File: make.info, Node: Wildcard Function, Prev: Wildcard Pitfall, Up: Wildcards + +4.4.3 The Function `wildcard' +----------------------------- + +Wildcard expansion happens automatically in rules. But wildcard +expansion does not normally take place when a variable is set, or +inside the arguments of a function. If you want to do wildcard +expansion in such places, you need to use the `wildcard' function, like +this: + + $(wildcard PATTERN...) + +This string, used anywhere in a makefile, is replaced by a +space-separated list of names of existing files that match one of the +given file name patterns. If no existing file name matches a pattern, +then that pattern is omitted from the output of the `wildcard' +function. Note that this is different from how unmatched wildcards +behave in rules, where they are used verbatim rather than ignored +(*note Wildcard Pitfall::). + + One use of the `wildcard' function is to get a list of all the C +source files in a directory, like this: + + $(wildcard *.c) + + We can change the list of C source files into a list of object files +by replacing the `.c' suffix with `.o' in the result, like this: + + $(patsubst %.c,%.o,$(wildcard *.c)) + +(Here we have used another function, `patsubst'. *Note Functions for +String Substitution and Analysis: Text Functions.) + + Thus, a makefile to compile all C source files in the directory and +then link them together could be written as follows: + + objects := $(patsubst %.c,%.o,$(wildcard *.c)) + + foo : $(objects) + cc -o foo $(objects) + +(This takes advantage of the implicit rule for compiling C programs, so +there is no need to write explicit rules for compiling the files. +*Note The Two Flavors of Variables: Flavors, for an explanation of +`:=', which is a variant of `='.) + + +File: make.info, Node: Directory Search, Next: Phony Targets, Prev: Wildcards, Up: Rules + +4.5 Searching Directories for Prerequisites +=========================================== + +For large systems, it is often desirable to put sources in a separate +directory from the binaries. The "directory search" features of `make' +facilitate this by searching several directories automatically to find +a prerequisite. When you redistribute the files among directories, you +do not need to change the individual rules, just the search paths. + +* Menu: + +* General Search:: Specifying a search path that applies + to every prerequisite. +* Selective Search:: Specifying a search path + for a specified class of names. +* Search Algorithm:: When and how search paths are applied. +* Recipes/Search:: How to write recipes that work together + with search paths. +* Implicit/Search:: How search paths affect implicit rules. +* Libraries/Search:: Directory search for link libraries. + + +File: make.info, Node: General Search, Next: Selective Search, Prev: Directory Search, Up: Directory Search + +4.5.1 `VPATH': Search Path for All Prerequisites +------------------------------------------------ + +The value of the `make' variable `VPATH' specifies a list of +directories that `make' should search. Most often, the directories are +expected to contain prerequisite files that are not in the current +directory; however, `make' uses `VPATH' as a search list for both +prerequisites and targets of rules. + + Thus, if a file that is listed as a target or prerequisite does not +exist in the current directory, `make' searches the directories listed +in `VPATH' for a file with that name. If a file is found in one of +them, that file may become the prerequisite (see below). Rules may then +specify the names of files in the prerequisite list as if they all +existed in the current directory. *Note Writing Recipes with Directory +Search: Recipes/Search. + + In the `VPATH' variable, directory names are separated by colons or +blanks. The order in which directories are listed is the order followed +by `make' in its search. (On MS-DOS and MS-Windows, semi-colons are +used as separators of directory names in `VPATH', since the colon can +be used in the pathname itself, after the drive letter.) + + For example, + + VPATH = src:../headers + +specifies a path containing two directories, `src' and `../headers', +which `make' searches in that order. + + With this value of `VPATH', the following rule, + + foo.o : foo.c + +is interpreted as if it were written like this: + + foo.o : src/foo.c + +assuming the file `foo.c' does not exist in the current directory but +is found in the directory `src'. + + +File: make.info, Node: Selective Search, Next: Search Algorithm, Prev: General Search, Up: Directory Search + +4.5.2 The `vpath' Directive +--------------------------- + +Similar to the `VPATH' variable, but more selective, is the `vpath' +directive (note lower case), which allows you to specify a search path +for a particular class of file names: those that match a particular +pattern. Thus you can supply certain search directories for one class +of file names and other directories (or none) for other file names. + + There are three forms of the `vpath' directive: + +`vpath PATTERN DIRECTORIES' + Specify the search path DIRECTORIES for file names that match + PATTERN. + + The search path, DIRECTORIES, is a list of directories to be + searched, separated by colons (semi-colons on MS-DOS and + MS-Windows) or blanks, just like the search path used in the + `VPATH' variable. + +`vpath PATTERN' + Clear out the search path associated with PATTERN. + +`vpath' + Clear all search paths previously specified with `vpath' + directives. + + A `vpath' pattern is a string containing a `%' character. The +string must match the file name of a prerequisite that is being searched +for, the `%' character matching any sequence of zero or more characters +(as in pattern rules; *note Defining and Redefining Pattern Rules: +Pattern Rules.). For example, `%.h' matches files that end in `.h'. +(If there is no `%', the pattern must match the prerequisite exactly, +which is not useful very often.) + + `%' characters in a `vpath' directive's pattern can be quoted with +preceding backslashes (`\'). Backslashes that would otherwise quote +`%' characters can be quoted with more backslashes. Backslashes that +quote `%' characters or other backslashes are removed from the pattern +before it is compared to file names. Backslashes that are not in +danger of quoting `%' characters go unmolested. + + When a prerequisite fails to exist in the current directory, if the +PATTERN in a `vpath' directive matches the name of the prerequisite +file, then the DIRECTORIES in that directive are searched just like +(and before) the directories in the `VPATH' variable. + + For example, + + vpath %.h ../headers + +tells `make' to look for any prerequisite whose name ends in `.h' in +the directory `../headers' if the file is not found in the current +directory. + + If several `vpath' patterns match the prerequisite file's name, then +`make' processes each matching `vpath' directive one by one, searching +all the directories mentioned in each directive. `make' handles +multiple `vpath' directives in the order in which they appear in the +makefile; multiple directives with the same pattern are independent of +each other. + + Thus, + + vpath %.c foo + vpath % blish + vpath %.c bar + +will look for a file ending in `.c' in `foo', then `blish', then `bar', +while + + vpath %.c foo:bar + vpath % blish + +will look for a file ending in `.c' in `foo', then `bar', then `blish'. + + +File: make.info, Node: Search Algorithm, Next: Recipes/Search, Prev: Selective Search, Up: Directory Search + +4.5.3 How Directory Searches are Performed +------------------------------------------ + +When a prerequisite is found through directory search, regardless of +type (general or selective), the pathname located may not be the one +that `make' actually provides you in the prerequisite list. Sometimes +the path discovered through directory search is thrown away. + + The algorithm `make' uses to decide whether to keep or abandon a +path found via directory search is as follows: + + 1. If a target file does not exist at the path specified in the + makefile, directory search is performed. + + 2. If the directory search is successful, that path is kept and this + file is tentatively stored as the target. + + 3. All prerequisites of this target are examined using this same + method. + + 4. After processing the prerequisites, the target may or may not need + to be rebuilt: + + a. If the target does _not_ need to be rebuilt, the path to the + file found during directory search is used for any + prerequisite lists which contain this target. In short, if + `make' doesn't need to rebuild the target then you use the + path found via directory search. + + b. If the target _does_ need to be rebuilt (is out-of-date), the + pathname found during directory search is _thrown away_, and + the target is rebuilt using the file name specified in the + makefile. In short, if `make' must rebuild, then the target + is rebuilt locally, not in the directory found via directory + search. + + This algorithm may seem complex, but in practice it is quite often +exactly what you want. + + Other versions of `make' use a simpler algorithm: if the file does +not exist, and it is found via directory search, then that pathname is +always used whether or not the target needs to be built. Thus, if the +target is rebuilt it is created at the pathname discovered during +directory search. + + If, in fact, this is the behavior you want for some or all of your +directories, you can use the `GPATH' variable to indicate this to +`make'. + + `GPATH' has the same syntax and format as `VPATH' (that is, a space- +or colon-delimited list of pathnames). If an out-of-date target is +found by directory search in a directory that also appears in `GPATH', +then that pathname is not thrown away. The target is rebuilt using the +expanded path. + + +File: make.info, Node: Recipes/Search, Next: Implicit/Search, Prev: Search Algorithm, Up: Directory Search + +4.5.4 Writing Recipes with Directory Search +------------------------------------------- + +When a prerequisite is found in another directory through directory +search, this cannot change the recipe of the rule; they will execute as +written. Therefore, you must write the recipe with care so that it +will look for the prerequisite in the directory where `make' finds it. + + This is done with the "automatic variables" such as `$^' (*note +Automatic Variables::). For instance, the value of `$^' is a list of +all the prerequisites of the rule, including the names of the +directories in which they were found, and the value of `$@' is the +target. Thus: + + foo.o : foo.c + cc -c $(CFLAGS) $^ -o $@ + +(The variable `CFLAGS' exists so you can specify flags for C +compilation by implicit rules; we use it here for consistency so it will +affect all C compilations uniformly; *note Variables Used by Implicit +Rules: Implicit Variables.) + + Often the prerequisites include header files as well, which you do +not want to mention in the recipe. The automatic variable `$<' is just +the first prerequisite: + + VPATH = src:../headers + foo.o : foo.c defs.h hack.h + cc -c $(CFLAGS) $< -o $@ + + +File: make.info, Node: Implicit/Search, Next: Libraries/Search, Prev: Recipes/Search, Up: Directory Search + +4.5.5 Directory Search and Implicit Rules +----------------------------------------- + +The search through the directories specified in `VPATH' or with `vpath' +also happens during consideration of implicit rules (*note Using +Implicit Rules: Implicit Rules.). + + For example, when a file `foo.o' has no explicit rule, `make' +considers implicit rules, such as the built-in rule to compile `foo.c' +if that file exists. If such a file is lacking in the current +directory, the appropriate directories are searched for it. If `foo.c' +exists (or is mentioned in the makefile) in any of the directories, the +implicit rule for C compilation is applied. + + The recipes of implicit rules normally use automatic variables as a +matter of necessity; consequently they will use the file names found by +directory search with no extra effort. + + +File: make.info, Node: Libraries/Search, Prev: Implicit/Search, Up: Directory Search + +4.5.6 Directory Search for Link Libraries +----------------------------------------- + +Directory search applies in a special way to libraries used with the +linker. This special feature comes into play when you write a +prerequisite whose name is of the form `-lNAME'. (You can tell +something strange is going on here because the prerequisite is normally +the name of a file, and the _file name_ of a library generally looks +like `libNAME.a', not like `-lNAME'.) + + When a prerequisite's name has the form `-lNAME', `make' handles it +specially by searching for the file `libNAME.so', and, if it is not +found, for the file `libNAME.a' in the current directory, in +directories specified by matching `vpath' search paths and the `VPATH' +search path, and then in the directories `/lib', `/usr/lib', and +`PREFIX/lib' (normally `/usr/local/lib', but MS-DOS/MS-Windows versions +of `make' behave as if PREFIX is defined to be the root of the DJGPP +installation tree). + + For example, if there is a `/usr/lib/libcurses.a' library on your +system (and no `/usr/lib/libcurses.so' file), then + + foo : foo.c -lcurses + cc $^ -o $@ + +would cause the command `cc foo.c /usr/lib/libcurses.a -o foo' to be +executed when `foo' is older than `foo.c' or than +`/usr/lib/libcurses.a'. + + Although the default set of files to be searched for is `libNAME.so' +and `libNAME.a', this is customizable via the `.LIBPATTERNS' variable. +Each word in the value of this variable is a pattern string. When a +prerequisite like `-lNAME' is seen, `make' will replace the percent in +each pattern in the list with NAME and perform the above directory +searches using each library filename. + + The default value for `.LIBPATTERNS' is `lib%.so lib%.a', which +provides the default behavior described above. + + You can turn off link library expansion completely by setting this +variable to an empty value. + + +File: make.info, Node: Phony Targets, Next: Force Targets, Prev: Directory Search, Up: Rules + +4.6 Phony Targets +================= + +A phony target is one that is not really the name of a file; rather it +is just a name for a recipe to be executed when you make an explicit +request. There are two reasons to use a phony target: to avoid a +conflict with a file of the same name, and to improve performance. + + If you write a rule whose recipe will not create the target file, the +recipe will be executed every time the target comes up for remaking. +Here is an example: + + clean: + rm *.o temp + +Because the `rm' command does not create a file named `clean', probably +no such file will ever exist. Therefore, the `rm' command will be +executed every time you say `make clean'. + + The phony target will cease to work if anything ever does create a +file named `clean' in this directory. Since it has no prerequisites, +the file `clean' would inevitably be considered up to date, and its +recipe would not be executed. To avoid this problem, you can explicitly +declare the target to be phony, using the special target `.PHONY' +(*note Special Built-in Target Names: Special Targets.) as follows: + + .PHONY : clean + +Once this is done, `make clean' will run the recipe regardless of +whether there is a file named `clean'. + + Since it knows that phony targets do not name actual files that +could be remade from other files, `make' skips the implicit rule search +for phony targets (*note Implicit Rules::). This is why declaring a +target phony is good for performance, even if you are not worried about +the actual file existing. + + Thus, you first write the line that states that `clean' is a phony +target, then you write the rule, like this: + + .PHONY: clean + clean: + rm *.o temp + + Another example of the usefulness of phony targets is in conjunction +with recursive invocations of `make' (for more information, see *note +Recursive Use of `make': Recursion.). In this case the makefile will +often contain a variable which lists a number of subdirectories to be +built. One way to handle this is with one rule whose recipe is a shell +loop over the subdirectories, like this: + + SUBDIRS = foo bar baz + + subdirs: + for dir in $(SUBDIRS); do \ + $(MAKE) -C $$dir; \ + done + + There are problems with this method, however. First, any error +detected in a submake is ignored by this rule, so it will continue to +build the rest of the directories even when one fails. This can be +overcome by adding shell commands to note the error and exit, but then +it will do so even if `make' is invoked with the `-k' option, which is +unfortunate. Second, and perhaps more importantly, you cannot take +advantage of `make''s ability to build targets in parallel (*note +Parallel Execution: Parallel.), since there is only one rule. + + By declaring the subdirectories as phony targets (you must do this as +the subdirectory obviously always exists; otherwise it won't be built) +you can remove these problems: + + SUBDIRS = foo bar baz + + .PHONY: subdirs $(SUBDIRS) + + subdirs: $(SUBDIRS) + + $(SUBDIRS): + $(MAKE) -C $@ + + foo: baz + + Here we've also declared that the `foo' subdirectory cannot be built +until after the `baz' subdirectory is complete; this kind of +relationship declaration is particularly important when attempting +parallel builds. + + A phony target should not be a prerequisite of a real target file; +if it is, its recipe will be run every time `make' goes to update that +file. As long as a phony target is never a prerequisite of a real +target, the phony target recipe will be executed only when the phony +target is a specified goal (*note Arguments to Specify the Goals: +Goals.). + + Phony targets can have prerequisites. When one directory contains +multiple programs, it is most convenient to describe all of the +programs in one makefile `./Makefile'. Since the target remade by +default will be the first one in the makefile, it is common to make +this a phony target named `all' and give it, as prerequisites, all the +individual programs. For example: + + all : prog1 prog2 prog3 + .PHONY : all + + prog1 : prog1.o utils.o + cc -o prog1 prog1.o utils.o + + prog2 : prog2.o + cc -o prog2 prog2.o + + prog3 : prog3.o sort.o utils.o + cc -o prog3 prog3.o sort.o utils.o + +Now you can say just `make' to remake all three programs, or specify as +arguments the ones to remake (as in `make prog1 prog3'). Phoniness is +not inherited: the prerequisites of a phony target are not themselves +phony, unless explicitly declared to be so. + + When one phony target is a prerequisite of another, it serves as a +subroutine of the other. For example, here `make cleanall' will delete +the object files, the difference files, and the file `program': + + .PHONY: cleanall cleanobj cleandiff + + cleanall : cleanobj cleandiff + rm program + + cleanobj : + rm *.o + + cleandiff : + rm *.diff + + +File: make.info, Node: Force Targets, Next: Empty Targets, Prev: Phony Targets, Up: Rules + +4.7 Rules without Recipes or Prerequisites +========================================== + +If a rule has no prerequisites or recipe, and the target of the rule is +a nonexistent file, then `make' imagines this target to have been +updated whenever its rule is run. This implies that all targets +depending on this one will always have their recipe run. + + An example will illustrate this: + + clean: FORCE + rm $(objects) + FORCE: + + Here the target `FORCE' satisfies the special conditions, so the +target `clean' that depends on it is forced to run its recipe. There +is nothing special about the name `FORCE', but that is one name +commonly used this way. + + As you can see, using `FORCE' this way has the same results as using +`.PHONY: clean'. + + Using `.PHONY' is more explicit and more efficient. However, other +versions of `make' do not support `.PHONY'; thus `FORCE' appears in +many makefiles. *Note Phony Targets::. + + +File: make.info, Node: Empty Targets, Next: Special Targets, Prev: Force Targets, Up: Rules + +4.8 Empty Target Files to Record Events +======================================= + +The "empty target" is a variant of the phony target; it is used to hold +recipes for an action that you request explicitly from time to time. +Unlike a phony target, this target file can really exist; but the file's +contents do not matter, and usually are empty. + + The purpose of the empty target file is to record, with its +last-modification time, when the rule's recipe was last executed. It +does so because one of the commands in the recipe is a `touch' command +to update the target file. + + The empty target file should have some prerequisites (otherwise it +doesn't make sense). When you ask to remake the empty target, the +recipe is executed if any prerequisite is more recent than the target; +in other words, if a prerequisite has changed since the last time you +remade the target. Here is an example: + + print: foo.c bar.c + lpr -p $? + touch print + +With this rule, `make print' will execute the `lpr' command if either +source file has changed since the last `make print'. The automatic +variable `$?' is used to print only those files that have changed +(*note Automatic Variables::). + + +File: make.info, Node: Special Targets, Next: Multiple Targets, Prev: Empty Targets, Up: Rules + +4.9 Special Built-in Target Names +================================= + +Certain names have special meanings if they appear as targets. + +`.PHONY' + The prerequisites of the special target `.PHONY' are considered to + be phony targets. When it is time to consider such a target, + `make' will run its recipe unconditionally, regardless of whether + a file with that name exists or what its last-modification time + is. *Note Phony Targets: Phony Targets. + +`.SUFFIXES' + The prerequisites of the special target `.SUFFIXES' are the list + of suffixes to be used in checking for suffix rules. *Note + Old-Fashioned Suffix Rules: Suffix Rules. + +`.DEFAULT' + The recipe specified for `.DEFAULT' is used for any target for + which no rules are found (either explicit rules or implicit rules). + *Note Last Resort::. If a `.DEFAULT' recipe is specified, every + file mentioned as a prerequisite, but not as a target in a rule, + will have that recipe executed on its behalf. *Note Implicit Rule + Search Algorithm: Implicit Rule Search. + +`.PRECIOUS' + The targets which `.PRECIOUS' depends on are given the following + special treatment: if `make' is killed or interrupted during the + execution of their recipes, the target is not deleted. *Note + Interrupting or Killing `make': Interrupts. Also, if the target + is an intermediate file, it will not be deleted after it is no + longer needed, as is normally done. *Note Chains of Implicit + Rules: Chained Rules. In this latter respect it overlaps with the + `.SECONDARY' special target. + + You can also list the target pattern of an implicit rule (such as + `%.o') as a prerequisite file of the special target `.PRECIOUS' to + preserve intermediate files created by rules whose target patterns + match that file's name. + +`.INTERMEDIATE' + The targets which `.INTERMEDIATE' depends on are treated as + intermediate files. *Note Chains of Implicit Rules: Chained Rules. + `.INTERMEDIATE' with no prerequisites has no effect. + +`.SECONDARY' + The targets which `.SECONDARY' depends on are treated as + intermediate files, except that they are never automatically + deleted. *Note Chains of Implicit Rules: Chained Rules. + + `.SECONDARY' with no prerequisites causes all targets to be treated + as secondary (i.e., no target is removed because it is considered + intermediate). + +`.SECONDEXPANSION' + If `.SECONDEXPANSION' is mentioned as a target anywhere in the + makefile, then all prerequisite lists defined _after_ it appears + will be expanded a second time after all makefiles have been read + in. *Note Secondary Expansion: Secondary Expansion. + +`.DELETE_ON_ERROR' + If `.DELETE_ON_ERROR' is mentioned as a target anywhere in the + makefile, then `make' will delete the target of a rule if it has + changed and its recipe exits with a nonzero exit status, just as it + does when it receives a signal. *Note Errors in Recipes: Errors. + +`.IGNORE' + If you specify prerequisites for `.IGNORE', then `make' will + ignore errors in execution of the recipe for those particular + files. The recipe for `.IGNORE' (if any) is ignored. + + If mentioned as a target with no prerequisites, `.IGNORE' says to + ignore errors in execution of recipes for all files. This usage of + `.IGNORE' is supported only for historical compatibility. Since + this affects every recipe in the makefile, it is not very useful; + we recommend you use the more selective ways to ignore errors in + specific recipes. *Note Errors in Recipes: Errors. + +`.LOW_RESOLUTION_TIME' + If you specify prerequisites for `.LOW_RESOLUTION_TIME', `make' + assumes that these files are created by commands that generate low + resolution time stamps. The recipe for the `.LOW_RESOLUTION_TIME' + target are ignored. + + The high resolution file time stamps of many modern file systems + lessen the chance of `make' incorrectly concluding that a file is + up to date. Unfortunately, some hosts do not provide a way to set + a high resolution file time stamp, so commands like `cp -p' that + explicitly set a file's time stamp must discard its subsecond part. + If a file is created by such a command, you should list it as a + prerequisite of `.LOW_RESOLUTION_TIME' so that `make' does not + mistakenly conclude that the file is out of date. For example: + + .LOW_RESOLUTION_TIME: dst + dst: src + cp -p src dst + + Since `cp -p' discards the subsecond part of `src''s time stamp, + `dst' is typically slightly older than `src' even when it is up to + date. The `.LOW_RESOLUTION_TIME' line causes `make' to consider + `dst' to be up to date if its time stamp is at the start of the + same second that `src''s time stamp is in. + + Due to a limitation of the archive format, archive member time + stamps are always low resolution. You need not list archive + members as prerequisites of `.LOW_RESOLUTION_TIME', as `make' does + this automatically. + +`.SILENT' + If you specify prerequisites for `.SILENT', then `make' will not + print the recipe used to remake those particular files before + executing them. The recipe for `.SILENT' is ignored. + + If mentioned as a target with no prerequisites, `.SILENT' says not + to print any recipes before executing them. This usage of + `.SILENT' is supported only for historical compatibility. We + recommend you use the more selective ways to silence specific + recipes. *Note Recipe Echoing: Echoing. If you want to silence + all recipes for a particular run of `make', use the `-s' or + `--silent' option (*note Options Summary::). + +`.EXPORT_ALL_VARIABLES' + Simply by being mentioned as a target, this tells `make' to export + all variables to child processes by default. *Note Communicating + Variables to a Sub-`make': Variables/Recursion. + +`.NOTPARALLEL' + If `.NOTPARALLEL' is mentioned as a target, then this invocation + of `make' will be run serially, even if the `-j' option is given. + Any recursively invoked `make' command will still run recipes in + parallel (unless its makefile also contains this target). Any + prerequisites on this target are ignored. + +`.ONESHELL' + If `.ONESHELL' is mentioned as a target, then when a target is + built all lines of the recipe will be given to a single invocation + of the shell rather than each line being invoked separately (*note + Recipe Execution: Execution.). + +`.POSIX' + If `.POSIX' is mentioned as a target, then the makefile will be + parsed and run in POSIX-conforming mode. This does _not_ mean + that only POSIX-conforming makefiles will be accepted: all advanced + GNU `make' features are still available. Rather, this target + causes `make' to behave as required by POSIX in those areas where + `make''s default behavior differs. + + In particular, if this target is mentioned then recipes will be + invoked as if the shell had been passed the `-e' flag: the first + failing command in a recipe will cause the recipe to fail + immediately. + + Any defined implicit rule suffix also counts as a special target if +it appears as a target, and so does the concatenation of two suffixes, +such as `.c.o'. These targets are suffix rules, an obsolete way of +defining implicit rules (but a way still widely used). In principle, +any target name could be special in this way if you break it in two and +add both pieces to the suffix list. In practice, suffixes normally +begin with `.', so these special target names also begin with `.'. +*Note Old-Fashioned Suffix Rules: Suffix Rules. + + +File: make.info, Node: Multiple Targets, Next: Multiple Rules, Prev: Special Targets, Up: Rules + +4.10 Multiple Targets in a Rule +=============================== + +A rule with multiple targets is equivalent to writing many rules, each +with one target, and all identical aside from that. The same recipe +applies to all the targets, but its effect may vary because you can +substitute the actual target name into the recipe using `$@'. The rule +contributes the same prerequisites to all the targets also. + + This is useful in two cases. + + * You want just prerequisites, no recipe. For example: + + kbd.o command.o files.o: command.h + + gives an additional prerequisite to each of the three object files + mentioned. + + * Similar recipes work for all the targets. The recipes do not need + to be absolutely identical, since the automatic variable `$@' can + be used to substitute the particular target to be remade into the + commands (*note Automatic Variables::). For example: + + bigoutput littleoutput : text.g + generate text.g -$(subst output,,$@) > $@ + + is equivalent to + + bigoutput : text.g + generate text.g -big > bigoutput + littleoutput : text.g + generate text.g -little > littleoutput + + Here we assume the hypothetical program `generate' makes two types + of output, one if given `-big' and one if given `-little'. *Note + Functions for String Substitution and Analysis: Text Functions, + for an explanation of the `subst' function. + + Suppose you would like to vary the prerequisites according to the +target, much as the variable `$@' allows you to vary the recipe. You +cannot do this with multiple targets in an ordinary rule, but you can +do it with a "static pattern rule". *Note Static Pattern Rules: Static +Pattern. + + +File: make.info, Node: Multiple Rules, Next: Static Pattern, Prev: Multiple Targets, Up: Rules + +4.11 Multiple Rules for One Target +================================== + +One file can be the target of several rules. All the prerequisites +mentioned in all the rules are merged into one list of prerequisites for +the target. If the target is older than any prerequisite from any rule, +the recipe is executed. + + There can only be one recipe to be executed for a file. If more than +one rule gives a recipe for the same file, `make' uses the last one +given and prints an error message. (As a special case, if the file's +name begins with a dot, no error message is printed. This odd behavior +is only for compatibility with other implementations of `make'... you +should avoid using it). Occasionally it is useful to have the same +target invoke multiple recipes which are defined in different parts of +your makefile; you can use "double-colon rules" (*note Double-Colon::) +for this. + + An extra rule with just prerequisites can be used to give a few extra +prerequisites to many files at once. For example, makefiles often have +a variable, such as `objects', containing a list of all the compiler +output files in the system being made. An easy way to say that all of +them must be recompiled if `config.h' changes is to write the following: + + objects = foo.o bar.o + foo.o : defs.h + bar.o : defs.h test.h + $(objects) : config.h + + This could be inserted or taken out without changing the rules that +really specify how to make the object files, making it a convenient +form to use if you wish to add the additional prerequisite +intermittently. + + Another wrinkle is that the additional prerequisites could be +specified with a variable that you set with a command line argument to +`make' (*note Overriding Variables: Overriding.). For example, + + extradeps= + $(objects) : $(extradeps) + +means that the command `make extradeps=foo.h' will consider `foo.h' as +a prerequisite of each object file, but plain `make' will not. + + If none of the explicit rules for a target has a recipe, then `make' +searches for an applicable implicit rule to find one *note Using +Implicit Rules: Implicit Rules.). + + +File: make.info, Node: Static Pattern, Next: Double-Colon, Prev: Multiple Rules, Up: Rules + +4.12 Static Pattern Rules +========================= + +"Static pattern rules" are rules which specify multiple targets and +construct the prerequisite names for each target based on the target +name. They are more general than ordinary rules with multiple targets +because the targets do not have to have identical prerequisites. Their +prerequisites must be _analogous_, but not necessarily _identical_. + +* Menu: + +* Static Usage:: The syntax of static pattern rules. +* Static versus Implicit:: When are they better than implicit rules? + + +File: make.info, Node: Static Usage, Next: Static versus Implicit, Prev: Static Pattern, Up: Static Pattern + +4.12.1 Syntax of Static Pattern Rules +------------------------------------- + +Here is the syntax of a static pattern rule: + + TARGETS ...: TARGET-PATTERN: PREREQ-PATTERNS ... + RECIPE + ... + +The TARGETS list specifies the targets that the rule applies to. The +targets can contain wildcard characters, just like the targets of +ordinary rules (*note Using Wildcard Characters in File Names: +Wildcards.). + + The TARGET-PATTERN and PREREQ-PATTERNS say how to compute the +prerequisites of each target. Each target is matched against the +TARGET-PATTERN to extract a part of the target name, called the "stem". +This stem is substituted into each of the PREREQ-PATTERNS to make the +prerequisite names (one from each PREREQ-PATTERN). + + Each pattern normally contains the character `%' just once. When the +TARGET-PATTERN matches a target, the `%' can match any part of the +target name; this part is called the "stem". The rest of the pattern +must match exactly. For example, the target `foo.o' matches the +pattern `%.o', with `foo' as the stem. The targets `foo.c' and +`foo.out' do not match that pattern. + + The prerequisite names for each target are made by substituting the +stem for the `%' in each prerequisite pattern. For example, if one +prerequisite pattern is `%.c', then substitution of the stem `foo' +gives the prerequisite name `foo.c'. It is legitimate to write a +prerequisite pattern that does not contain `%'; then this prerequisite +is the same for all targets. + + `%' characters in pattern rules can be quoted with preceding +backslashes (`\'). Backslashes that would otherwise quote `%' +characters can be quoted with more backslashes. Backslashes that quote +`%' characters or other backslashes are removed from the pattern before +it is compared to file names or has a stem substituted into it. +Backslashes that are not in danger of quoting `%' characters go +unmolested. For example, the pattern `the\%weird\\%pattern\\' has +`the%weird\' preceding the operative `%' character, and `pattern\\' +following it. The final two backslashes are left alone because they +cannot affect any `%' character. + + Here is an example, which compiles each of `foo.o' and `bar.o' from +the corresponding `.c' file: + + objects = foo.o bar.o + + all: $(objects) + + $(objects): %.o: %.c + $(CC) -c $(CFLAGS) $< -o $@ + +Here `$<' is the automatic variable that holds the name of the +prerequisite and `$@' is the automatic variable that holds the name of +the target; see *note Automatic Variables::. + + Each target specified must match the target pattern; a warning is +issued for each target that does not. If you have a list of files, +only some of which will match the pattern, you can use the `filter' +function to remove nonmatching file names (*note Functions for String +Substitution and Analysis: Text Functions.): + + files = foo.elc bar.o lose.o + + $(filter %.o,$(files)): %.o: %.c + $(CC) -c $(CFLAGS) $< -o $@ + $(filter %.elc,$(files)): %.elc: %.el + emacs -f batch-byte-compile $< + +In this example the result of `$(filter %.o,$(files))' is `bar.o +lose.o', and the first static pattern rule causes each of these object +files to be updated by compiling the corresponding C source file. The +result of `$(filter %.elc,$(files))' is `foo.elc', so that file is made +from `foo.el'. + + Another example shows how to use `$*' in static pattern rules: + + bigoutput littleoutput : %output : text.g + generate text.g -$* > $@ + +When the `generate' command is run, `$*' will expand to the stem, +either `big' or `little'. + + +File: make.info, Node: Static versus Implicit, Prev: Static Usage, Up: Static Pattern + +4.12.2 Static Pattern Rules versus Implicit Rules +------------------------------------------------- + +A static pattern rule has much in common with an implicit rule defined +as a pattern rule (*note Defining and Redefining Pattern Rules: Pattern +Rules.). Both have a pattern for the target and patterns for +constructing the names of prerequisites. The difference is in how +`make' decides _when_ the rule applies. + + An implicit rule _can_ apply to any target that matches its pattern, +but it _does_ apply only when the target has no recipe otherwise +specified, and only when the prerequisites can be found. If more than +one implicit rule appears applicable, only one applies; the choice +depends on the order of rules. + + By contrast, a static pattern rule applies to the precise list of +targets that you specify in the rule. It cannot apply to any other +target and it invariably does apply to each of the targets specified. +If two conflicting rules apply, and both have recipes, that's an error. + + The static pattern rule can be better than an implicit rule for these +reasons: + + * You may wish to override the usual implicit rule for a few files + whose names cannot be categorized syntactically but can be given + in an explicit list. + + * If you cannot be sure of the precise contents of the directories + you are using, you may not be sure which other irrelevant files + might lead `make' to use the wrong implicit rule. The choice + might depend on the order in which the implicit rule search is + done. With static pattern rules, there is no uncertainty: each + rule applies to precisely the targets specified. + + +File: make.info, Node: Double-Colon, Next: Automatic Prerequisites, Prev: Static Pattern, Up: Rules + +4.13 Double-Colon Rules +======================= + +"Double-colon" rules are explicit rules written with `::' instead of +`:' after the target names. They are handled differently from ordinary +rules when the same target appears in more than one rule. Pattern +rules with double-colons have an entirely different meaning (*note +Match-Anything Rules::). + + When a target appears in multiple rules, all the rules must be the +same type: all ordinary, or all double-colon. If they are +double-colon, each of them is independent of the others. Each +double-colon rule's recipe is executed if the target is older than any +prerequisites of that rule. If there are no prerequisites for that +rule, its recipe is always executed (even if the target already +exists). This can result in executing none, any, or all of the +double-colon rules. + + Double-colon rules with the same target are in fact completely +separate from one another. Each double-colon rule is processed +individually, just as rules with different targets are processed. + + The double-colon rules for a target are executed in the order they +appear in the makefile. However, the cases where double-colon rules +really make sense are those where the order of executing the recipes +would not matter. + + Double-colon rules are somewhat obscure and not often very useful; +they provide a mechanism for cases in which the method used to update a +target differs depending on which prerequisite files caused the update, +and such cases are rare. + + Each double-colon rule should specify a recipe; if it does not, an +implicit rule will be used if one applies. *Note Using Implicit Rules: +Implicit Rules. + + +File: make.info, Node: Automatic Prerequisites, Prev: Double-Colon, Up: Rules + +4.14 Generating Prerequisites Automatically +=========================================== + +In the makefile for a program, many of the rules you need to write often +say only that some object file depends on some header file. For +example, if `main.c' uses `defs.h' via an `#include', you would write: + + main.o: defs.h + +You need this rule so that `make' knows that it must remake `main.o' +whenever `defs.h' changes. You can see that for a large program you +would have to write dozens of such rules in your makefile. And, you +must always be very careful to update the makefile every time you add +or remove an `#include'. + + To avoid this hassle, most modern C compilers can write these rules +for you, by looking at the `#include' lines in the source files. +Usually this is done with the `-M' option to the compiler. For +example, the command: + + cc -M main.c + +generates the output: + + main.o : main.c defs.h + +Thus you no longer have to write all those rules yourself. The +compiler will do it for you. + + Note that such a prerequisite constitutes mentioning `main.o' in a +makefile, so it can never be considered an intermediate file by implicit +rule search. This means that `make' won't ever remove the file after +using it; *note Chains of Implicit Rules: Chained Rules. + + With old `make' programs, it was traditional practice to use this +compiler feature to generate prerequisites on demand with a command like +`make depend'. That command would create a file `depend' containing +all the automatically-generated prerequisites; then the makefile could +use `include' to read them in (*note Include::). + + In GNU `make', the feature of remaking makefiles makes this practice +obsolete--you need never tell `make' explicitly to regenerate the +prerequisites, because it always regenerates any makefile that is out +of date. *Note Remaking Makefiles::. + + The practice we recommend for automatic prerequisite generation is +to have one makefile corresponding to each source file. For each +source file `NAME.c' there is a makefile `NAME.d' which lists what +files the object file `NAME.o' depends on. That way only the source +files that have changed need to be rescanned to produce the new +prerequisites. + + Here is the pattern rule to generate a file of prerequisites (i.e., +a makefile) called `NAME.d' from a C source file called `NAME.c': + + %.d: %.c + @set -e; rm -f $@; \ + $(CC) -M $(CPPFLAGS) $< > $@.$$$$; \ + sed 's,\($*\)\.o[ :]*,\1.o $@ : ,g' < $@.$$$$ > $@; \ + rm -f $@.$$$$ + +*Note Pattern Rules::, for information on defining pattern rules. The +`-e' flag to the shell causes it to exit immediately if the `$(CC)' +command (or any other command) fails (exits with a nonzero status). + + With the GNU C compiler, you may wish to use the `-MM' flag instead +of `-M'. This omits prerequisites on system header files. *Note +Options Controlling the Preprocessor: (gcc.info)Preprocessor Options, +for details. + + The purpose of the `sed' command is to translate (for example): + + main.o : main.c defs.h + +into: + + main.o main.d : main.c defs.h + +This makes each `.d' file depend on all the source and header files +that the corresponding `.o' file depends on. `make' then knows it must +regenerate the prerequisites whenever any of the source or header files +changes. + + Once you've defined the rule to remake the `.d' files, you then use +the `include' directive to read them all in. *Note Include::. For +example: + + sources = foo.c bar.c + + include $(sources:.c=.d) + +(This example uses a substitution variable reference to translate the +list of source files `foo.c bar.c' into a list of prerequisite +makefiles, `foo.d bar.d'. *Note Substitution Refs::, for full +information on substitution references.) Since the `.d' files are +makefiles like any others, `make' will remake them as necessary with no +further work from you. *Note Remaking Makefiles::. + + Note that the `.d' files contain target definitions; you should be +sure to place the `include' directive _after_ the first, default goal +in your makefiles or run the risk of having a random object file become +the default goal. *Note How Make Works::. + + +File: make.info, Node: Recipes, Next: Using Variables, Prev: Rules, Up: Top + +5 Writing Recipes in Rules +************************** + +The recipe of a rule consists of one or more shell command lines to be +executed, one at a time, in the order they appear. Typically, the +result of executing these commands is that the target of the rule is +brought up to date. + + Users use many different shell programs, but recipes in makefiles are +always interpreted by `/bin/sh' unless the makefile specifies +otherwise. *Note Recipe Execution: Execution. + +* Menu: + +* Recipe Syntax:: Recipe syntax features and pitfalls. +* Echoing:: How to control when recipes are echoed. +* Execution:: How recipes are executed. +* Parallel:: How recipes can be executed in parallel. +* Errors:: What happens after a recipe execution error. +* Interrupts:: What happens when a recipe is interrupted. +* Recursion:: Invoking `make' from makefiles. +* Canned Recipes:: Defining canned recipes. +* Empty Recipes:: Defining useful, do-nothing recipes. + + +File: make.info, Node: Recipe Syntax, Next: Echoing, Prev: Recipes, Up: Recipes + +5.1 Recipe Syntax +================= + +Makefiles have the unusual property that there are really two distinct +syntaxes in one file. Most of the makefile uses `make' syntax (*note +Writing Makefiles: Makefiles.). However, recipes are meant to be +interpreted by the shell and so they are written using shell syntax. +The `make' program does not try to understand shell syntax: it performs +only a very few specific translations on the content of the recipe +before handing it to the shell. + + Each line in the recipe must start with a tab (or the first character +in the value of the `.RECIPEPREFIX' variable; *note Special +Variables::), except that the first recipe line may be attached to the +target-and-prerequisites line with a semicolon in between. _Any_ line +in the makefile that begins with a tab and appears in a "rule context" +(that is, after a rule has been started until another rule or variable +definition) will be considered part of a recipe for that rule. Blank +lines and lines of just comments may appear among the recipe lines; +they are ignored. + + Some consequences of these rules include: + + * A blank line that begins with a tab is not blank: it's an empty + recipe (*note Empty Recipes::). + + * A comment in a recipe is not a `make' comment; it will be passed + to the shell as-is. Whether the shell treats it as a comment or + not depends on your shell. + + * A variable definition in a "rule context" which is indented by a + tab as the first character on the line, will be considered part of + a recipe, not a `make' variable definition, and passed to the + shell. + + * A conditional expression (`ifdef', `ifeq', etc. *note Syntax of + Conditionals: Conditional Syntax.) in a "rule context" which is + indented by a tab as the first character on the line, will be + considered part of a recipe and be passed to the shell. + + +* Menu: + +* Splitting Lines:: Breaking long recipe lines for readability. +* Variables in Recipes:: Using `make' variables in recipes. + + +File: make.info, Node: Splitting Lines, Next: Variables in Recipes, Prev: Recipe Syntax, Up: Recipe Syntax + +5.1.1 Splitting Recipe Lines +---------------------------- + +One of the few ways in which `make' does interpret recipes is checking +for a backslash just before the newline. As in normal makefile syntax, +a single logical recipe line can be split into multiple physical lines +in the makefile by placing a backslash before each newline. A sequence +of lines like this is considered a single recipe line, and one instance +of the shell will be invoked to run it. + + However, in contrast to how they are treated in other places in a +makefile, backslash-newline pairs are _not_ removed from the recipe. +Both the backslash and the newline characters are preserved and passed +to the shell. How the backslash-newline is interpreted depends on your +shell. If the first character of the next line after the +backslash-newline is the recipe prefix character (a tab by default; +*note Special Variables::), then that character (and only that +character) is removed. Whitespace is never added to the recipe. + + For example, the recipe for the all target in this makefile: + + all : + @echo no\ + space + @echo no\ + space + @echo one \ + space + @echo one\ + space + +consists of four separate shell commands where the output is: + + nospace + nospace + one space + one space + + As a more complex example, this makefile: + + all : ; @echo 'hello \ + world' ; echo "hello \ + world" + +will invoke one shell with a command of: + + echo 'hello \ + world' ; echo "hello \ + world" + +which, according to shell quoting rules, will yield the following +output: + + hello \ + world + hello world + +Notice how the backslash/newline pair was removed inside the string +quoted with double quotes (`"..."'), but not from the string quoted +with single quotes (`'...''). This is the way the default shell +(`/bin/sh') handles backslash/newline pairs. If you specify a +different shell in your makefiles it may treat them differently. + + Sometimes you want to split a long line inside of single quotes, but +you don't want the backslash-newline to appear in the quoted content. +This is often the case when passing scripts to languages such as Perl, +where extraneous backslashes inside the script can change its meaning +or even be a syntax error. One simple way of handling this is to place +the quoted string, or even the entire command, into a `make' variable +then use the variable in the recipe. In this situation the newline +quoting rules for makefiles will be used, and the backslash-newline +will be removed. If we rewrite our example above using this method: + + HELLO = 'hello \ + world' + + all : ; @echo $(HELLO) + +we will get output like this: + + hello world + + If you like, you can also use target-specific variables (*note +Target-specific Variable Values: Target-specific.) to obtain a tighter +correspondence between the variable and the recipe that uses it. + + +File: make.info, Node: Variables in Recipes, Prev: Splitting Lines, Up: Recipe Syntax + +5.1.2 Using Variables in Recipes +-------------------------------- + +The other way in which `make' processes recipes is by expanding any +variable references in them (*note Basics of Variable References: +Reference.). This occurs after make has finished reading all the +makefiles and the target is determined to be out of date; so, the +recipes for targets which are not rebuilt are never expanded. + + Variable and function references in recipes have identical syntax and +semantics to references elsewhere in the makefile. They also have the +same quoting rules: if you want a dollar sign to appear in your recipe, +you must double it (`$$'). For shells like the default shell, that use +dollar signs to introduce variables, it's important to keep clear in +your mind whether the variable you want to reference is a `make' +variable (use a single dollar sign) or a shell variable (use two dollar +signs). For example: + + LIST = one two three + all: + for i in $(LIST); do \ + echo $$i; \ + done + +results in the following command being passed to the shell: + + for i in one two three; do \ + echo $i; \ + done + +which generates the expected result: + + one + two + three + + +File: make.info, Node: Echoing, Next: Execution, Prev: Recipe Syntax, Up: Recipes + +5.2 Recipe Echoing +================== + +Normally `make' prints each line of the recipe before it is executed. +We call this "echoing" because it gives the appearance that you are +typing the lines yourself. + + When a line starts with `@', the echoing of that line is suppressed. +The `@' is discarded before the line is passed to the shell. Typically +you would use this for a command whose only effect is to print +something, such as an `echo' command to indicate progress through the +makefile: + + @echo About to make distribution files + + When `make' is given the flag `-n' or `--just-print' it only echoes +most recipes, without executing them. *Note Summary of Options: +Options Summary. In this case even the recipe lines starting with `@' +are printed. This flag is useful for finding out which recipes `make' +thinks are necessary without actually doing them. + + The `-s' or `--silent' flag to `make' prevents all echoing, as if +all recipes started with `@'. A rule in the makefile for the special +target `.SILENT' without prerequisites has the same effect (*note +Special Built-in Target Names: Special Targets.). `.SILENT' is +essentially obsolete since `@' is more flexible. + + +File: make.info, Node: Execution, Next: Parallel, Prev: Echoing, Up: Recipes + +5.3 Recipe Execution +==================== + +When it is time to execute recipes to update a target, they are +executed by invoking a new subshell for each line of the recipe, unless +the `.ONESHELL' special target is in effect (*note Using One Shell: One +Shell.) (In practice, `make' may take shortcuts that do not affect the +results.) + + *Please note:* this implies that setting shell variables and +invoking shell commands such as `cd' that set a context local to each +process will not affect the following lines in the recipe.(1) If you +want to use `cd' to affect the next statement, put both statements in a +single recipe line. Then `make' will invoke one shell to run the +entire line, and the shell will execute the statements in sequence. +For example: + + foo : bar/lose + cd $(@D) && gobble $(@F) > ../$@ + +Here we use the shell AND operator (`&&') so that if the `cd' command +fails, the script will fail without trying to invoke the `gobble' +command in the wrong directory, which could cause problems (in this +case it would certainly cause `../foo' to be truncated, at least). + +* Menu: + +* One Shell:: One shell for all lines in a recipe +* Choosing the Shell:: How `make' chooses the shell used + to run recipes. + + ---------- Footnotes ---------- + + (1) On MS-DOS, the value of current working directory is *global*, so +changing it _will_ affect the following recipe lines on those systems. + + +File: make.info, Node: One Shell, Next: Choosing the Shell, Prev: Execution, Up: Execution + +5.3.1 Using One Shell +--------------------- + +Sometimes you would prefer that all the lines in the recipe be passed +to a single invocation of the shell. There are generally two +situations where this is useful: first, it can improve performance in +makefiles where recipes consist of many command lines, by avoiding +extra processes. Second, you might want newlines to be included in +your recipe command (for example perhaps you are using a very different +interpreter as your `SHELL'). If the `.ONESHELL' special target +appears anywhere in the makefile then _all_ recipe lines for each +target will be provided to a single invocation of the shell. Newlines +between recipe lines will be preserved. For example: + + .ONESHELL: + foo : bar/lose + cd $(@D) + gobble $(@F) > ../$@ + +would now work as expected even though the commands are on different +recipe lines. + + If `.ONESHELL' is provided, then only the first line of the recipe +will be checked for the special prefix characters (`@', `-', and `+'). +Subsequent lines will include the special characters in the recipe line +when the `SHELL' is invoked. If you want your recipe to start with one +of these special characters you'll need to arrange for them to not be +the first characters on the first line, perhaps by adding a comment or +similar. For example, this would be a syntax error in Perl because the +first `@' is removed by make: + + .ONESHELL: + SHELL = /usr/bin/perl + .SHELLFLAGS = -e + show : + @f = qw(a b c); + print "@f\n"; + +However, either of these alternatives would work properly: + + .ONESHELL: + SHELL = /usr/bin/perl + .SHELLFLAGS = -e + show : + # Make sure "@" is not the first character on the first line + @f = qw(a b c); + print "@f\n"; + +or + + .ONESHELL: + SHELL = /usr/bin/perl + .SHELLFLAGS = -e + show : + my @f = qw(a b c); + print "@f\n"; + + As a special feature, if `SHELL' is determined to be a POSIX-style +shell, the special prefix characters in "internal" recipe lines will +_removed_ before the recipe is processed. This feature is intended to +allow existing makefiles to add the `.ONESHELL' special target and +still run properly without extensive modifications. Since the special +prefix characters are not legal at the beginning of a line in a POSIX +shell script this is not a loss in functionality. For example, this +works as expected: + + .ONESHELL: + foo : bar/lose + @cd $(@D) + @gobble $(@F) > ../$@ + + Even with this special feature, however, makefiles with `.ONESHELL' +will behave differently in ways that could be noticeable. For example, +normally if any line in the recipe fails, that causes the rule to fail +and no more recipe lines are processed. Under `.ONESHELL' a failure of +any but the final recipe line will not be noticed by `make'. You can +modify `.SHELLFLAGS' to add the `-e' option to the shell which will +cause any failure anywhere in the command line to cause the shell to +fail, but this could itself cause your recipe to behave differently. +Ultimately you may need to harden your recipe lines to allow them to +work with `.ONESHELL'. + + +File: make.info, Node: Choosing the Shell, Prev: One Shell, Up: Execution + +5.3.2 Choosing the Shell +------------------------ + +The program used as the shell is taken from the variable `SHELL'. If +this variable is not set in your makefile, the program `/bin/sh' is +used as the shell. The argument(s) passed to the shell are taken from +the variable `.SHELLFLAGS'. The default value of `.SHELLFLAGS' is `-c' +normally, or `-ec' in POSIX-conforming mode. + + Unlike most variables, the variable `SHELL' is never set from the +environment. This is because the `SHELL' environment variable is used +to specify your personal choice of shell program for interactive use. +It would be very bad for personal choices like this to affect the +functioning of makefiles. *Note Variables from the Environment: +Environment. + + Furthermore, when you do set `SHELL' in your makefile that value is +_not_ exported in the environment to recipe lines that `make' invokes. +Instead, the value inherited from the user's environment, if any, is +exported. You can override this behavior by explicitly exporting +`SHELL' (*note Communicating Variables to a Sub-`make': +Variables/Recursion.), forcing it to be passed in the environment to +recipe lines. + + However, on MS-DOS and MS-Windows the value of `SHELL' in the +environment *is* used, since on those systems most users do not set +this variable, and therefore it is most likely set specifically to be +used by `make'. On MS-DOS, if the setting of `SHELL' is not suitable +for `make', you can set the variable `MAKESHELL' to the shell that +`make' should use; if set it will be used as the shell instead of the +value of `SHELL'. + +Choosing a Shell in DOS and Windows +................................... + +Choosing a shell in MS-DOS and MS-Windows is much more complex than on +other systems. + + On MS-DOS, if `SHELL' is not set, the value of the variable +`COMSPEC' (which is always set) is used instead. + + The processing of lines that set the variable `SHELL' in Makefiles +is different on MS-DOS. The stock shell, `command.com', is +ridiculously limited in its functionality and many users of `make' tend +to install a replacement shell. Therefore, on MS-DOS, `make' examines +the value of `SHELL', and changes its behavior based on whether it +points to a Unix-style or DOS-style shell. This allows reasonable +functionality even if `SHELL' points to `command.com'. + + If `SHELL' points to a Unix-style shell, `make' on MS-DOS +additionally checks whether that shell can indeed be found; if not, it +ignores the line that sets `SHELL'. In MS-DOS, GNU `make' searches for +the shell in the following places: + + 1. In the precise place pointed to by the value of `SHELL'. For + example, if the makefile specifies `SHELL = /bin/sh', `make' will + look in the directory `/bin' on the current drive. + + 2. In the current directory. + + 3. In each of the directories in the `PATH' variable, in order. + + + In every directory it examines, `make' will first look for the +specific file (`sh' in the example above). If this is not found, it +will also look in that directory for that file with one of the known +extensions which identify executable files. For example `.exe', +`.com', `.bat', `.btm', `.sh', and some others. + + If any of these attempts is successful, the value of `SHELL' will be +set to the full pathname of the shell as found. However, if none of +these is found, the value of `SHELL' will not be changed, and thus the +line that sets it will be effectively ignored. This is so `make' will +only support features specific to a Unix-style shell if such a shell is +actually installed on the system where `make' runs. + + Note that this extended search for the shell is limited to the cases +where `SHELL' is set from the Makefile; if it is set in the environment +or command line, you are expected to set it to the full pathname of the +shell, exactly as things are on Unix. + + The effect of the above DOS-specific processing is that a Makefile +that contains `SHELL = /bin/sh' (as many Unix makefiles do), will work +on MS-DOS unaltered if you have e.g. `sh.exe' installed in some +directory along your `PATH'. + + +File: make.info, Node: Parallel, Next: Errors, Prev: Execution, Up: Recipes + +5.4 Parallel Execution +====================== + +GNU `make' knows how to execute several recipes at once. Normally, +`make' will execute only one recipe at a time, waiting for it to finish +before executing the next. However, the `-j' or `--jobs' option tells +`make' to execute many recipes simultaneously. You can inhibit +parallelism in a particular makefile with the `.NOTPARALLEL' +pseudo-target (*note Special Built-in Target Names: Special Targets.). + + On MS-DOS, the `-j' option has no effect, since that system doesn't +support multi-processing. + + If the `-j' option is followed by an integer, this is the number of +recipes to execute at once; this is called the number of "job slots". +If there is nothing looking like an integer after the `-j' option, +there is no limit on the number of job slots. The default number of job +slots is one, which means serial execution (one thing at a time). + + One unpleasant consequence of running several recipes simultaneously +is that output generated by the recipes appears whenever each recipe +sends it, so messages from different recipes may be interspersed. + + Another problem is that two processes cannot both take input from the +same device; so to make sure that only one recipe tries to take input +from the terminal at once, `make' will invalidate the standard input +streams of all but one running recipe. This means that attempting to +read from standard input will usually be a fatal error (a `Broken pipe' +signal) for most child processes if there are several. + + It is unpredictable which recipe will have a valid standard input +stream (which will come from the terminal, or wherever you redirect the +standard input of `make'). The first recipe run will always get it +first, and the first recipe started after that one finishes will get it +next, and so on. + + We will change how this aspect of `make' works if we find a better +alternative. In the mean time, you should not rely on any recipe using +standard input at all if you are using the parallel execution feature; +but if you are not using this feature, then standard input works +normally in all recipes. + + Finally, handling recursive `make' invocations raises issues. For +more information on this, see *note Communicating Options to a +Sub-`make': Options/Recursion. + + If a recipe fails (is killed by a signal or exits with a nonzero +status), and errors are not ignored for that recipe (*note Errors in +Recipes: Errors.), the remaining recipe lines to remake the same target +will not be run. If a recipe fails and the `-k' or `--keep-going' +option was not given (*note Summary of Options: Options Summary.), +`make' aborts execution. If make terminates for any reason (including +a signal) with child processes running, it waits for them to finish +before actually exiting. + + When the system is heavily loaded, you will probably want to run +fewer jobs than when it is lightly loaded. You can use the `-l' option +to tell `make' to limit the number of jobs to run at once, based on the +load average. The `-l' or `--max-load' option is followed by a +floating-point number. For example, + + -l 2.5 + +will not let `make' start more than one job if the load average is +above 2.5. The `-l' option with no following number removes the load +limit, if one was given with a previous `-l' option. + + More precisely, when `make' goes to start up a job, and it already +has at least one job running, it checks the current load average; if it +is not lower than the limit given with `-l', `make' waits until the load +average goes below that limit, or until all the other jobs finish. + + By default, there is no load limit. + + +File: make.info, Node: Errors, Next: Interrupts, Prev: Parallel, Up: Recipes + +5.5 Errors in Recipes +===================== + +After each shell invocation returns, `make' looks at its exit status. +If the shell completed successfully (the exit status is zero), the next +line in the recipe is executed in a new shell; after the last line is +finished, the rule is finished. + + If there is an error (the exit status is nonzero), `make' gives up on +the current rule, and perhaps on all rules. + + Sometimes the failure of a certain recipe line does not indicate a +problem. For example, you may use the `mkdir' command to ensure that a +directory exists. If the directory already exists, `mkdir' will report +an error, but you probably want `make' to continue regardless. + + To ignore errors in a recipe line, write a `-' at the beginning of +the line's text (after the initial tab). The `-' is discarded before +the line is passed to the shell for execution. + + For example, + + clean: + -rm -f *.o + +This causes `make' to continue even if `rm' is unable to remove a file. + + When you run `make' with the `-i' or `--ignore-errors' flag, errors +are ignored in all recipes of all rules. A rule in the makefile for +the special target `.IGNORE' has the same effect, if there are no +prerequisites. These ways of ignoring errors are obsolete because `-' +is more flexible. + + When errors are to be ignored, because of either a `-' or the `-i' +flag, `make' treats an error return just like success, except that it +prints out a message that tells you the status code the shell exited +with, and says that the error has been ignored. + + When an error happens that `make' has not been told to ignore, it +implies that the current target cannot be correctly remade, and neither +can any other that depends on it either directly or indirectly. No +further recipes will be executed for these targets, since their +preconditions have not been achieved. + + Normally `make' gives up immediately in this circumstance, returning +a nonzero status. However, if the `-k' or `--keep-going' flag is +specified, `make' continues to consider the other prerequisites of the +pending targets, remaking them if necessary, before it gives up and +returns nonzero status. For example, after an error in compiling one +object file, `make -k' will continue compiling other object files even +though it already knows that linking them will be impossible. *Note +Summary of Options: Options Summary. + + The usual behavior assumes that your purpose is to get the specified +targets up to date; once `make' learns that this is impossible, it +might as well report the failure immediately. The `-k' option says +that the real purpose is to test as many of the changes made in the +program as possible, perhaps to find several independent problems so +that you can correct them all before the next attempt to compile. This +is why Emacs' `compile' command passes the `-k' flag by default. + + Usually when a recipe line fails, if it has changed the target file +at all, the file is corrupted and cannot be used--or at least it is not +completely updated. Yet the file's time stamp says that it is now up to +date, so the next time `make' runs, it will not try to update that +file. The situation is just the same as when the shell is killed by a +signal; *note Interrupts::. So generally the right thing to do is to +delete the target file if the recipe fails after beginning to change +the file. `make' will do this if `.DELETE_ON_ERROR' appears as a +target. This is almost always what you want `make' to do, but it is +not historical practice; so for compatibility, you must explicitly +request it. + + +File: make.info, Node: Interrupts, Next: Recursion, Prev: Errors, Up: Recipes + +5.6 Interrupting or Killing `make' +================================== + +If `make' gets a fatal signal while a shell is executing, it may delete +the target file that the recipe was supposed to update. This is done +if the target file's last-modification time has changed since `make' +first checked it. + + The purpose of deleting the target is to make sure that it is remade +from scratch when `make' is next run. Why is this? Suppose you type +`Ctrl-c' while a compiler is running, and it has begun to write an +object file `foo.o'. The `Ctrl-c' kills the compiler, resulting in an +incomplete file whose last-modification time is newer than the source +file `foo.c'. But `make' also receives the `Ctrl-c' signal and deletes +this incomplete file. If `make' did not do this, the next invocation +of `make' would think that `foo.o' did not require updating--resulting +in a strange error message from the linker when it tries to link an +object file half of which is missing. + + You can prevent the deletion of a target file in this way by making +the special target `.PRECIOUS' depend on it. Before remaking a target, +`make' checks to see whether it appears on the prerequisites of +`.PRECIOUS', and thereby decides whether the target should be deleted +if a signal happens. Some reasons why you might do this are that the +target is updated in some atomic fashion, or exists only to record a +modification-time (its contents do not matter), or must exist at all +times to prevent other sorts of trouble. + + +File: make.info, Node: Recursion, Next: Canned Recipes, Prev: Interrupts, Up: Recipes + +5.7 Recursive Use of `make' +=========================== + +Recursive use of `make' means using `make' as a command in a makefile. +This technique is useful when you want separate makefiles for various +subsystems that compose a larger system. For example, suppose you have +a subdirectory `subdir' which has its own makefile, and you would like +the containing directory's makefile to run `make' on the subdirectory. +You can do it by writing this: + + subsystem: + cd subdir && $(MAKE) + +or, equivalently, this (*note Summary of Options: Options Summary.): + + subsystem: + $(MAKE) -C subdir + + You can write recursive `make' commands just by copying this example, +but there are many things to know about how they work and why, and about +how the sub-`make' relates to the top-level `make'. You may also find +it useful to declare targets that invoke recursive `make' commands as +`.PHONY' (for more discussion on when this is useful, see *note Phony +Targets::). + + For your convenience, when GNU `make' starts (after it has processed +any `-C' options) it sets the variable `CURDIR' to the pathname of the +current working directory. This value is never touched by `make' +again: in particular note that if you include files from other +directories the value of `CURDIR' does not change. The value has the +same precedence it would have if it were set in the makefile (by +default, an environment variable `CURDIR' will not override this +value). Note that setting this variable has no impact on the operation +of `make' (it does not cause `make' to change its working directory, +for example). + +* Menu: + +* MAKE Variable:: The special effects of using `$(MAKE)'. +* Variables/Recursion:: How to communicate variables to a sub-`make'. +* Options/Recursion:: How to communicate options to a sub-`make'. +* -w Option:: How the `-w' or `--print-directory' option + helps debug use of recursive `make' commands. + + +File: make.info, Node: MAKE Variable, Next: Variables/Recursion, Prev: Recursion, Up: Recursion + +5.7.1 How the `MAKE' Variable Works +----------------------------------- + +Recursive `make' commands should always use the variable `MAKE', not +the explicit command name `make', as shown here: + + subsystem: + cd subdir && $(MAKE) + + The value of this variable is the file name with which `make' was +invoked. If this file name was `/bin/make', then the recipe executed +is `cd subdir && /bin/make'. If you use a special version of `make' to +run the top-level makefile, the same special version will be executed +for recursive invocations. + + As a special feature, using the variable `MAKE' in the recipe of a +rule alters the effects of the `-t' (`--touch'), `-n' (`--just-print'), +or `-q' (`--question') option. Using the `MAKE' variable has the same +effect as using a `+' character at the beginning of the recipe line. +*Note Instead of Executing the Recipes: Instead of Execution. This +special feature is only enabled if the `MAKE' variable appears directly +in the recipe: it does not apply if the `MAKE' variable is referenced +through expansion of another variable. In the latter case you must use +the `+' token to get these special effects. + + Consider the command `make -t' in the above example. (The `-t' +option marks targets as up to date without actually running any +recipes; see *note Instead of Execution::.) Following the usual +definition of `-t', a `make -t' command in the example would create a +file named `subsystem' and do nothing else. What you really want it to +do is run `cd subdir && make -t'; but that would require executing the +recipe, and `-t' says not to execute recipes. + + The special feature makes this do what you want: whenever a recipe +line of a rule contains the variable `MAKE', the flags `-t', `-n' and +`-q' do not apply to that line. Recipe lines containing `MAKE' are +executed normally despite the presence of a flag that causes most +recipes not to be run. The usual `MAKEFLAGS' mechanism passes the +flags to the sub-`make' (*note Communicating Options to a Sub-`make': +Options/Recursion.), so your request to touch the files, or print the +recipes, is propagated to the subsystem. + + +File: make.info, Node: Variables/Recursion, Next: Options/Recursion, Prev: MAKE Variable, Up: Recursion + +5.7.2 Communicating Variables to a Sub-`make' +--------------------------------------------- + +Variable values of the top-level `make' can be passed to the sub-`make' +through the environment by explicit request. These variables are +defined in the sub-`make' as defaults, but do not override what is +specified in the makefile used by the sub-`make' makefile unless you +use the `-e' switch (*note Summary of Options: Options Summary.). + + To pass down, or "export", a variable, `make' adds the variable and +its value to the environment for running each line of the recipe. The +sub-`make', in turn, uses the environment to initialize its table of +variable values. *Note Variables from the Environment: Environment. + + Except by explicit request, `make' exports a variable only if it is +either defined in the environment initially or set on the command line, +and if its name consists only of letters, numbers, and underscores. +Some shells cannot cope with environment variable names consisting of +characters other than letters, numbers, and underscores. + + The value of the `make' variable `SHELL' is not exported. Instead, +the value of the `SHELL' variable from the invoking environment is +passed to the sub-`make'. You can force `make' to export its value for +`SHELL' by using the `export' directive, described below. *Note +Choosing the Shell::. + + The special variable `MAKEFLAGS' is always exported (unless you +unexport it). `MAKEFILES' is exported if you set it to anything. + + `make' automatically passes down variable values that were defined +on the command line, by putting them in the `MAKEFLAGS' variable. +*Note Options/Recursion::. + + Variables are _not_ normally passed down if they were created by +default by `make' (*note Variables Used by Implicit Rules: Implicit +Variables.). The sub-`make' will define these for itself. + + If you want to export specific variables to a sub-`make', use the +`export' directive, like this: + + export VARIABLE ... + +If you want to _prevent_ a variable from being exported, use the +`unexport' directive, like this: + + unexport VARIABLE ... + +In both of these forms, the arguments to `export' and `unexport' are +expanded, and so could be variables or functions which expand to a +(list of) variable names to be (un)exported. + + As a convenience, you can define a variable and export it at the same +time by doing: + + export VARIABLE = value + +has the same result as: + + VARIABLE = value + export VARIABLE + +and + + export VARIABLE := value + +has the same result as: + + VARIABLE := value + export VARIABLE + + Likewise, + + export VARIABLE += value + +is just like: + + VARIABLE += value + export VARIABLE + +*Note Appending More Text to Variables: Appending. + + You may notice that the `export' and `unexport' directives work in +`make' in the same way they work in the shell, `sh'. + + If you want all variables to be exported by default, you can use +`export' by itself: + + export + +This tells `make' that variables which are not explicitly mentioned in +an `export' or `unexport' directive should be exported. Any variable +given in an `unexport' directive will still _not_ be exported. If you +use `export' by itself to export variables by default, variables whose +names contain characters other than alphanumerics and underscores will +not be exported unless specifically mentioned in an `export' directive. + + The behavior elicited by an `export' directive by itself was the +default in older versions of GNU `make'. If your makefiles depend on +this behavior and you want to be compatible with old versions of +`make', you can write a rule for the special target +`.EXPORT_ALL_VARIABLES' instead of using the `export' directive. This +will be ignored by old `make's, while the `export' directive will cause +a syntax error. + + Likewise, you can use `unexport' by itself to tell `make' _not_ to +export variables by default. Since this is the default behavior, you +would only need to do this if `export' had been used by itself earlier +(in an included makefile, perhaps). You *cannot* use `export' and +`unexport' by themselves to have variables exported for some recipes +and not for others. The last `export' or `unexport' directive that +appears by itself determines the behavior for the entire run of `make'. + + As a special feature, the variable `MAKELEVEL' is changed when it is +passed down from level to level. This variable's value is a string +which is the depth of the level as a decimal number. The value is `0' +for the top-level `make'; `1' for a sub-`make', `2' for a +sub-sub-`make', and so on. The incrementation happens when `make' sets +up the environment for a recipe. + + The main use of `MAKELEVEL' is to test it in a conditional directive +(*note Conditional Parts of Makefiles: Conditionals.); this way you can +write a makefile that behaves one way if run recursively and another +way if run directly by you. + + You can use the variable `MAKEFILES' to cause all sub-`make' +commands to use additional makefiles. The value of `MAKEFILES' is a +whitespace-separated list of file names. This variable, if defined in +the outer-level makefile, is passed down through the environment; then +it serves as a list of extra makefiles for the sub-`make' to read +before the usual or specified ones. *Note The Variable `MAKEFILES': +MAKEFILES Variable. + + +File: make.info, Node: Options/Recursion, Next: -w Option, Prev: Variables/Recursion, Up: Recursion + +5.7.3 Communicating Options to a Sub-`make' +------------------------------------------- + +Flags such as `-s' and `-k' are passed automatically to the sub-`make' +through the variable `MAKEFLAGS'. This variable is set up +automatically by `make' to contain the flag letters that `make' +received. Thus, if you do `make -ks' then `MAKEFLAGS' gets the value +`ks'. + + As a consequence, every sub-`make' gets a value for `MAKEFLAGS' in +its environment. In response, it takes the flags from that value and +processes them as if they had been given as arguments. *Note Summary +of Options: Options Summary. + + Likewise variables defined on the command line are passed to the +sub-`make' through `MAKEFLAGS'. Words in the value of `MAKEFLAGS' that +contain `=', `make' treats as variable definitions just as if they +appeared on the command line. *Note Overriding Variables: Overriding. + + The options `-C', `-f', `-o', and `-W' are not put into `MAKEFLAGS'; +these options are not passed down. + + The `-j' option is a special case (*note Parallel Execution: +Parallel.). If you set it to some numeric value `N' and your operating +system supports it (most any UNIX system will; others typically won't), +the parent `make' and all the sub-`make's will communicate to ensure +that there are only `N' jobs running at the same time between them all. +Note that any job that is marked recursive (*note Instead of Executing +Recipes: Instead of Execution.) doesn't count against the total jobs +(otherwise we could get `N' sub-`make's running and have no slots left +over for any real work!) + + If your operating system doesn't support the above communication, +then `-j 1' is always put into `MAKEFLAGS' instead of the value you +specified. This is because if the `-j' option were passed down to +sub-`make's, you would get many more jobs running in parallel than you +asked for. If you give `-j' with no numeric argument, meaning to run +as many jobs as possible in parallel, this is passed down, since +multiple infinities are no more than one. + + If you do not want to pass the other flags down, you must change the +value of `MAKEFLAGS', like this: + + subsystem: + cd subdir && $(MAKE) MAKEFLAGS= + + The command line variable definitions really appear in the variable +`MAKEOVERRIDES', and `MAKEFLAGS' contains a reference to this variable. +If you do want to pass flags down normally, but don't want to pass down +the command line variable definitions, you can reset `MAKEOVERRIDES' to +empty, like this: + + MAKEOVERRIDES = + +This is not usually useful to do. However, some systems have a small +fixed limit on the size of the environment, and putting so much +information into the value of `MAKEFLAGS' can exceed it. If you see +the error message `Arg list too long', this may be the problem. (For +strict compliance with POSIX.2, changing `MAKEOVERRIDES' does not +affect `MAKEFLAGS' if the special target `.POSIX' appears in the +makefile. You probably do not care about this.) + + A similar variable `MFLAGS' exists also, for historical +compatibility. It has the same value as `MAKEFLAGS' except that it +does not contain the command line variable definitions, and it always +begins with a hyphen unless it is empty (`MAKEFLAGS' begins with a +hyphen only when it begins with an option that has no single-letter +version, such as `--warn-undefined-variables'). `MFLAGS' was +traditionally used explicitly in the recursive `make' command, like +this: + + subsystem: + cd subdir && $(MAKE) $(MFLAGS) + +but now `MAKEFLAGS' makes this usage redundant. If you want your +makefiles to be compatible with old `make' programs, use this +technique; it will work fine with more modern `make' versions too. + + The `MAKEFLAGS' variable can also be useful if you want to have +certain options, such as `-k' (*note Summary of Options: Options +Summary.), set each time you run `make'. You simply put a value for +`MAKEFLAGS' in your environment. You can also set `MAKEFLAGS' in a +makefile, to specify additional flags that should also be in effect for +that makefile. (Note that you cannot use `MFLAGS' this way. That +variable is set only for compatibility; `make' does not interpret a +value you set for it in any way.) + + When `make' interprets the value of `MAKEFLAGS' (either from the +environment or from a makefile), it first prepends a hyphen if the value +does not already begin with one. Then it chops the value into words +separated by blanks, and parses these words as if they were options +given on the command line (except that `-C', `-f', `-h', `-o', `-W', +and their long-named versions are ignored; and there is no error for an +invalid option). + + If you do put `MAKEFLAGS' in your environment, you should be sure not +to include any options that will drastically affect the actions of +`make' and undermine the purpose of makefiles and of `make' itself. +For instance, the `-t', `-n', and `-q' options, if put in one of these +variables, could have disastrous consequences and would certainly have +at least surprising and probably annoying effects. + + +File: make.info, Node: -w Option, Prev: Options/Recursion, Up: Recursion + +5.7.4 The `--print-directory' Option +------------------------------------ + +If you use several levels of recursive `make' invocations, the `-w' or +`--print-directory' option can make the output a lot easier to +understand by showing each directory as `make' starts processing it and +as `make' finishes processing it. For example, if `make -w' is run in +the directory `/u/gnu/make', `make' will print a line of the form: + + make: Entering directory `/u/gnu/make'. + +before doing anything else, and a line of the form: + + make: Leaving directory `/u/gnu/make'. + +when processing is completed. + + Normally, you do not need to specify this option because `make' does +it for you: `-w' is turned on automatically when you use the `-C' +option, and in sub-`make's. `make' will not automatically turn on `-w' +if you also use `-s', which says to be silent, or if you use +`--no-print-directory' to explicitly disable it. + + +File: make.info, Node: Canned Recipes, Next: Empty Recipes, Prev: Recursion, Up: Recipes + +5.8 Defining Canned Recipes +=========================== + +When the same sequence of commands is useful in making various targets, +you can define it as a canned sequence with the `define' directive, and +refer to the canned sequence from the recipes for those targets. The +canned sequence is actually a variable, so the name must not conflict +with other variable names. + + Here is an example of defining a canned recipe: + + define run-yacc = + yacc $(firstword $^) + mv y.tab.c $@ + endef + +Here `run-yacc' is the name of the variable being defined; `endef' +marks the end of the definition; the lines in between are the commands. +The `define' directive does not expand variable references and function +calls in the canned sequence; the `$' characters, parentheses, variable +names, and so on, all become part of the value of the variable you are +defining. *Note Defining Multi-Line Variables: Multi-Line, for a +complete explanation of `define'. + + The first command in this example runs Yacc on the first +prerequisite of whichever rule uses the canned sequence. The output +file from Yacc is always named `y.tab.c'. The second command moves the +output to the rule's target file name. + + To use the canned sequence, substitute the variable into the recipe +of a rule. You can substitute it like any other variable (*note Basics +of Variable References: Reference.). Because variables defined by +`define' are recursively expanded variables, all the variable +references you wrote inside the `define' are expanded now. For example: + + foo.c : foo.y + $(run-yacc) + +`foo.y' will be substituted for the variable `$^' when it occurs in +`run-yacc''s value, and `foo.c' for `$@'. + + This is a realistic example, but this particular one is not needed in +practice because `make' has an implicit rule to figure out these +commands based on the file names involved (*note Using Implicit Rules: +Implicit Rules.). + + In recipe execution, each line of a canned sequence is treated just +as if the line appeared on its own in the rule, preceded by a tab. In +particular, `make' invokes a separate subshell for each line. You can +use the special prefix characters that affect command lines (`@', `-', +and `+') on each line of a canned sequence. *Note Writing Recipes in +Rules: Recipes. For example, using this canned sequence: + + define frobnicate = + @echo "frobnicating target $@" + frob-step-1 $< -o $@-step-1 + frob-step-2 $@-step-1 -o $@ + endef + +`make' will not echo the first line, the `echo' command. But it _will_ +echo the following two recipe lines. + + On the other hand, prefix characters on the recipe line that refers +to a canned sequence apply to every line in the sequence. So the rule: + + frob.out: frob.in + @$(frobnicate) + +does not echo _any_ recipe lines. (*Note Recipe Echoing: Echoing, for +a full explanation of `@'.) + + +File: make.info, Node: Empty Recipes, Prev: Canned Recipes, Up: Recipes + +5.9 Using Empty Recipes +======================= + +It is sometimes useful to define recipes which do nothing. This is done +simply by giving a recipe that consists of nothing but whitespace. For +example: + + target: ; + +defines an empty recipe for `target'. You could also use a line +beginning with a recipe prefix character to define an empty recipe, but +this would be confusing because such a line looks empty. + + You may be wondering why you would want to define a recipe that does +nothing. The only reason this is useful is to prevent a target from +getting implicit recipes (from implicit rules or the `.DEFAULT' special +target; *note Implicit Rules:: and *note Defining Last-Resort Default +Rules: Last Resort.). + + You may be inclined to define empty recipes for targets that are not +actual files, but only exist so that their prerequisites can be remade. +However, this is not the best way to do that, because the prerequisites +may not be remade properly if the target file actually does exist. +*Note Phony Targets: Phony Targets, for a better way to do this. + + +File: make.info, Node: Using Variables, Next: Conditionals, Prev: Recipes, Up: Top + +6 How to Use Variables +********************** + +A "variable" is a name defined in a makefile to represent a string of +text, called the variable's "value". These values are substituted by +explicit request into targets, prerequisites, recipes, and other parts +of the makefile. (In some other versions of `make', variables are +called "macros".) + + Variables and functions in all parts of a makefile are expanded when +read, except for in recipes, the right-hand sides of variable +definitions using `=', and the bodies of variable definitions using the +`define' directive. + + Variables can represent lists of file names, options to pass to +compilers, programs to run, directories to look in for source files, +directories to write output in, or anything else you can imagine. + + A variable name may be any sequence of characters not containing `:', +`#', `=', or leading or trailing whitespace. However, variable names +containing characters other than letters, numbers, and underscores +should be avoided, as they may be given special meanings in the future, +and with some shells they cannot be passed through the environment to a +sub-`make' (*note Communicating Variables to a Sub-`make': +Variables/Recursion.). + + Variable names are case-sensitive. The names `foo', `FOO', and +`Foo' all refer to different variables. + + It is traditional to use upper case letters in variable names, but we +recommend using lower case letters for variable names that serve +internal purposes in the makefile, and reserving upper case for +parameters that control implicit rules or for parameters that the user +should override with command options (*note Overriding Variables: +Overriding.). + + A few variables have names that are a single punctuation character or +just a few characters. These are the "automatic variables", and they +have particular specialized uses. *Note Automatic Variables::. + +* Menu: + +* Reference:: How to use the value of a variable. +* Flavors:: Variables come in two flavors. +* Advanced:: Advanced features for referencing a variable. +* Values:: All the ways variables get their values. +* Setting:: How to set a variable in the makefile. +* Appending:: How to append more text to the old value + of a variable. +* Override Directive:: How to set a variable in the makefile even if + the user has set it with a command argument. +* Multi-Line:: An alternate way to set a variable + to a multi-line string. +* Undefine Directive:: How to undefine a variable so that it appears + as if it was never set. +* Environment:: Variable values can come from the environment. +* Target-specific:: Variable values can be defined on a per-target + basis. +* Pattern-specific:: Target-specific variable values can be applied + to a group of targets that match a pattern. +* Suppressing Inheritance:: Suppress inheritance of variables. +* Special Variables:: Variables with special meaning or behavior. + + +File: make.info, Node: Reference, Next: Flavors, Prev: Using Variables, Up: Using Variables + +6.1 Basics of Variable References +================================= + +To substitute a variable's value, write a dollar sign followed by the +name of the variable in parentheses or braces: either `$(foo)' or +`${foo}' is a valid reference to the variable `foo'. This special +significance of `$' is why you must write `$$' to have the effect of a +single dollar sign in a file name or recipe. + + Variable references can be used in any context: targets, +prerequisites, recipes, most directives, and new variable values. Here +is an example of a common case, where a variable holds the names of all +the object files in a program: + + objects = program.o foo.o utils.o + program : $(objects) + cc -o program $(objects) + + $(objects) : defs.h + + Variable references work by strict textual substitution. Thus, the +rule + + foo = c + prog.o : prog.$(foo) + $(foo)$(foo) -$(foo) prog.$(foo) + +could be used to compile a C program `prog.c'. Since spaces before the +variable value are ignored in variable assignments, the value of `foo' +is precisely `c'. (Don't actually write your makefiles this way!) + + A dollar sign followed by a character other than a dollar sign, +open-parenthesis or open-brace treats that single character as the +variable name. Thus, you could reference the variable `x' with `$x'. +However, this practice is strongly discouraged, except in the case of +the automatic variables (*note Automatic Variables::). + + +File: make.info, Node: Flavors, Next: Advanced, Prev: Reference, Up: Using Variables + +6.2 The Two Flavors of Variables +================================ + +There are two ways that a variable in GNU `make' can have a value; we +call them the two "flavors" of variables. The two flavors are +distinguished in how they are defined and in what they do when expanded. + + The first flavor of variable is a "recursively expanded" variable. +Variables of this sort are defined by lines using `=' (*note Setting +Variables: Setting.) or by the `define' directive (*note Defining +Multi-Line Variables: Multi-Line.). The value you specify is installed +verbatim; if it contains references to other variables, these +references are expanded whenever this variable is substituted (in the +course of expanding some other string). When this happens, it is +called "recursive expansion". + + For example, + + foo = $(bar) + bar = $(ugh) + ugh = Huh? + + all:;echo $(foo) + +will echo `Huh?': `$(foo)' expands to `$(bar)' which expands to +`$(ugh)' which finally expands to `Huh?'. + + This flavor of variable is the only sort supported by other versions +of `make'. It has its advantages and its disadvantages. An advantage +(most would say) is that: + + CFLAGS = $(include_dirs) -O + include_dirs = -Ifoo -Ibar + +will do what was intended: when `CFLAGS' is expanded in a recipe, it +will expand to `-Ifoo -Ibar -O'. A major disadvantage is that you +cannot append something on the end of a variable, as in + + CFLAGS = $(CFLAGS) -O + +because it will cause an infinite loop in the variable expansion. +(Actually `make' detects the infinite loop and reports an error.) + + Another disadvantage is that any functions (*note Functions for +Transforming Text: Functions.) referenced in the definition will be +executed every time the variable is expanded. This makes `make' run +slower; worse, it causes the `wildcard' and `shell' functions to give +unpredictable results because you cannot easily control when they are +called, or even how many times. + + To avoid all the problems and inconveniences of recursively expanded +variables, there is another flavor: simply expanded variables. + + "Simply expanded variables" are defined by lines using `:=' (*note +Setting Variables: Setting.). The value of a simply expanded variable +is scanned once and for all, expanding any references to other +variables and functions, when the variable is defined. The actual +value of the simply expanded variable is the result of expanding the +text that you write. It does not contain any references to other +variables; it contains their values _as of the time this variable was +defined_. Therefore, + + x := foo + y := $(x) bar + x := later + +is equivalent to + + y := foo bar + x := later + + When a simply expanded variable is referenced, its value is +substituted verbatim. + + Here is a somewhat more complicated example, illustrating the use of +`:=' in conjunction with the `shell' function. (*Note The `shell' +Function: Shell Function.) This example also shows use of the variable +`MAKELEVEL', which is changed when it is passed down from level to +level. (*Note Communicating Variables to a Sub-`make': +Variables/Recursion, for information about `MAKELEVEL'.) + + ifeq (0,${MAKELEVEL}) + whoami := $(shell whoami) + host-type := $(shell arch) + MAKE := ${MAKE} host-type=${host-type} whoami=${whoami} + endif + +An advantage of this use of `:=' is that a typical `descend into a +directory' recipe then looks like this: + + ${subdirs}: + ${MAKE} -C $@ all + + Simply expanded variables generally make complicated makefile +programming more predictable because they work like variables in most +programming languages. They allow you to redefine a variable using its +own value (or its value processed in some way by one of the expansion +functions) and to use the expansion functions much more efficiently +(*note Functions for Transforming Text: Functions.). + + You can also use them to introduce controlled leading whitespace into +variable values. Leading whitespace characters are discarded from your +input before substitution of variable references and function calls; +this means you can include leading spaces in a variable value by +protecting them with variable references, like this: + + nullstring := + space := $(nullstring) # end of the line + +Here the value of the variable `space' is precisely one space. The +comment `# end of the line' is included here just for clarity. Since +trailing space characters are _not_ stripped from variable values, just +a space at the end of the line would have the same effect (but be +rather hard to read). If you put whitespace at the end of a variable +value, it is a good idea to put a comment like that at the end of the +line to make your intent clear. Conversely, if you do _not_ want any +whitespace characters at the end of your variable value, you must +remember not to put a random comment on the end of the line after some +whitespace, such as this: + + dir := /foo/bar # directory to put the frobs in + +Here the value of the variable `dir' is `/foo/bar ' (with four +trailing spaces), which was probably not the intention. (Imagine +something like `$(dir)/file' with this definition!) + + There is another assignment operator for variables, `?='. This is +called a conditional variable assignment operator, because it only has +an effect if the variable is not yet defined. This statement: + + FOO ?= bar + +is exactly equivalent to this (*note The `origin' Function: Origin +Function.): + + ifeq ($(origin FOO), undefined) + FOO = bar + endif + + Note that a variable set to an empty value is still defined, so `?=' +will not set that variable. + + +File: make.info, Node: Advanced, Next: Values, Prev: Flavors, Up: Using Variables + +6.3 Advanced Features for Reference to Variables +================================================ + +This section describes some advanced features you can use to reference +variables in more flexible ways. + +* Menu: + +* Substitution Refs:: Referencing a variable with + substitutions on the value. +* Computed Names:: Computing the name of the variable to refer to. + + +File: make.info, Node: Substitution Refs, Next: Computed Names, Prev: Advanced, Up: Advanced + +6.3.1 Substitution References +----------------------------- + +A "substitution reference" substitutes the value of a variable with +alterations that you specify. It has the form `$(VAR:A=B)' (or +`${VAR:A=B}') and its meaning is to take the value of the variable VAR, +replace every A at the end of a word with B in that value, and +substitute the resulting string. + + When we say "at the end of a word", we mean that A must appear +either followed by whitespace or at the end of the value in order to be +replaced; other occurrences of A in the value are unaltered. For +example: + + foo := a.o b.o c.o + bar := $(foo:.o=.c) + +sets `bar' to `a.c b.c c.c'. *Note Setting Variables: Setting. + + A substitution reference is actually an abbreviation for use of the +`patsubst' expansion function (*note Functions for String Substitution +and Analysis: Text Functions.). We provide substitution references as +well as `patsubst' for compatibility with other implementations of +`make'. + + Another type of substitution reference lets you use the full power of +the `patsubst' function. It has the same form `$(VAR:A=B)' described +above, except that now A must contain a single `%' character. This +case is equivalent to `$(patsubst A,B,$(VAR))'. *Note Functions for +String Substitution and Analysis: Text Functions, for a description of +the `patsubst' function. + +For example: + + foo := a.o b.o c.o + bar := $(foo:%.o=%.c) + +sets `bar' to `a.c b.c c.c'. + + +File: make.info, Node: Computed Names, Prev: Substitution Refs, Up: Advanced + +6.3.2 Computed Variable Names +----------------------------- + +Computed variable names are a complicated concept needed only for +sophisticated makefile programming. For most purposes you need not +consider them, except to know that making a variable with a dollar sign +in its name might have strange results. However, if you are the type +that wants to understand everything, or you are actually interested in +what they do, read on. + + Variables may be referenced inside the name of a variable. This is +called a "computed variable name" or a "nested variable reference". +For example, + + x = y + y = z + a := $($(x)) + +defines `a' as `z': the `$(x)' inside `$($(x))' expands to `y', so +`$($(x))' expands to `$(y)' which in turn expands to `z'. Here the +name of the variable to reference is not stated explicitly; it is +computed by expansion of `$(x)'. The reference `$(x)' here is nested +within the outer variable reference. + + The previous example shows two levels of nesting, but any number of +levels is possible. For example, here are three levels: + + x = y + y = z + z = u + a := $($($(x))) + +Here the innermost `$(x)' expands to `y', so `$($(x))' expands to +`$(y)' which in turn expands to `z'; now we have `$(z)', which becomes +`u'. + + References to recursively-expanded variables within a variable name +are reexpanded in the usual fashion. For example: + + x = $(y) + y = z + z = Hello + a := $($(x)) + +defines `a' as `Hello': `$($(x))' becomes `$($(y))' which becomes +`$(z)' which becomes `Hello'. + + Nested variable references can also contain modified references and +function invocations (*note Functions for Transforming Text: +Functions.), just like any other reference. For example, using the +`subst' function (*note Functions for String Substitution and Analysis: +Text Functions.): + + x = variable1 + variable2 := Hello + y = $(subst 1,2,$(x)) + z = y + a := $($($(z))) + +eventually defines `a' as `Hello'. It is doubtful that anyone would +ever want to write a nested reference as convoluted as this one, but it +works: `$($($(z)))' expands to `$($(y))' which becomes `$($(subst +1,2,$(x)))'. This gets the value `variable1' from `x' and changes it +by substitution to `variable2', so that the entire string becomes +`$(variable2)', a simple variable reference whose value is `Hello'. + + A computed variable name need not consist entirely of a single +variable reference. It can contain several variable references, as +well as some invariant text. For example, + + a_dirs := dira dirb + 1_dirs := dir1 dir2 + + a_files := filea fileb + 1_files := file1 file2 + + ifeq "$(use_a)" "yes" + a1 := a + else + a1 := 1 + endif + + ifeq "$(use_dirs)" "yes" + df := dirs + else + df := files + endif + + dirs := $($(a1)_$(df)) + +will give `dirs' the same value as `a_dirs', `1_dirs', `a_files' or +`1_files' depending on the settings of `use_a' and `use_dirs'. + + Computed variable names can also be used in substitution references: + + a_objects := a.o b.o c.o + 1_objects := 1.o 2.o 3.o + + sources := $($(a1)_objects:.o=.c) + +defines `sources' as either `a.c b.c c.c' or `1.c 2.c 3.c', depending +on the value of `a1'. + + The only restriction on this sort of use of nested variable +references is that they cannot specify part of the name of a function +to be called. This is because the test for a recognized function name +is done before the expansion of nested references. For example, + + ifdef do_sort + func := sort + else + func := strip + endif + + bar := a d b g q c + + foo := $($(func) $(bar)) + +attempts to give `foo' the value of the variable `sort a d b g q c' or +`strip a d b g q c', rather than giving `a d b g q c' as the argument +to either the `sort' or the `strip' function. This restriction could +be removed in the future if that change is shown to be a good idea. + + You can also use computed variable names in the left-hand side of a +variable assignment, or in a `define' directive, as in: + + dir = foo + $(dir)_sources := $(wildcard $(dir)/*.c) + define $(dir)_print = + lpr $($(dir)_sources) + endef + +This example defines the variables `dir', `foo_sources', and +`foo_print'. + + Note that "nested variable references" are quite different from +"recursively expanded variables" (*note The Two Flavors of Variables: +Flavors.), though both are used together in complex ways when doing +makefile programming. + + +File: make.info, Node: Values, Next: Setting, Prev: Advanced, Up: Using Variables + +6.4 How Variables Get Their Values +================================== + +Variables can get values in several different ways: + + * You can specify an overriding value when you run `make'. *Note + Overriding Variables: Overriding. + + * You can specify a value in the makefile, either with an assignment + (*note Setting Variables: Setting.) or with a verbatim definition + (*note Defining Multi-Line Variables: Multi-Line.). + + * Variables in the environment become `make' variables. *Note + Variables from the Environment: Environment. + + * Several "automatic" variables are given new values for each rule. + Each of these has a single conventional use. *Note Automatic + Variables::. + + * Several variables have constant initial values. *Note Variables + Used by Implicit Rules: Implicit Variables. + + +File: make.info, Node: Setting, Next: Appending, Prev: Values, Up: Using Variables + +6.5 Setting Variables +===================== + +To set a variable from the makefile, write a line starting with the +variable name followed by `=' or `:='. Whatever follows the `=' or +`:=' on the line becomes the value. For example, + + objects = main.o foo.o bar.o utils.o + +defines a variable named `objects'. Whitespace around the variable +name and immediately after the `=' is ignored. + + Variables defined with `=' are "recursively expanded" variables. +Variables defined with `:=' are "simply expanded" variables; these +definitions can contain variable references which will be expanded +before the definition is made. *Note The Two Flavors of Variables: +Flavors. + + The variable name may contain function and variable references, which +are expanded when the line is read to find the actual variable name to +use. + + There is no limit on the length of the value of a variable except the +amount of swapping space on the computer. When a variable definition is +long, it is a good idea to break it into several lines by inserting +backslash-newline at convenient places in the definition. This will not +affect the functioning of `make', but it will make the makefile easier +to read. + + Most variable names are considered to have the empty string as a +value if you have never set them. Several variables have built-in +initial values that are not empty, but you can set them in the usual +ways (*note Variables Used by Implicit Rules: Implicit Variables.). +Several special variables are set automatically to a new value for each +rule; these are called the "automatic" variables (*note Automatic +Variables::). + + If you'd like a variable to be set to a value only if it's not +already set, then you can use the shorthand operator `?=' instead of +`='. These two settings of the variable `FOO' are identical (*note The +`origin' Function: Origin Function.): + + FOO ?= bar + +and + + ifeq ($(origin FOO), undefined) + FOO = bar + endif + + +File: make.info, Node: Appending, Next: Override Directive, Prev: Setting, Up: Using Variables + +6.6 Appending More Text to Variables +==================================== + +Often it is useful to add more text to the value of a variable already +defined. You do this with a line containing `+=', like this: + + objects += another.o + +This takes the value of the variable `objects', and adds the text +`another.o' to it (preceded by a single space). Thus: + + objects = main.o foo.o bar.o utils.o + objects += another.o + +sets `objects' to `main.o foo.o bar.o utils.o another.o'. + + Using `+=' is similar to: + + objects = main.o foo.o bar.o utils.o + objects := $(objects) another.o + +but differs in ways that become important when you use more complex +values. + + When the variable in question has not been defined before, `+=' acts +just like normal `=': it defines a recursively-expanded variable. +However, when there _is_ a previous definition, exactly what `+=' does +depends on what flavor of variable you defined originally. *Note The +Two Flavors of Variables: Flavors, for an explanation of the two +flavors of variables. + + When you add to a variable's value with `+=', `make' acts +essentially as if you had included the extra text in the initial +definition of the variable. If you defined it first with `:=', making +it a simply-expanded variable, `+=' adds to that simply-expanded +definition, and expands the new text before appending it to the old +value just as `:=' does (see *note Setting Variables: Setting, for a +full explanation of `:='). In fact, + + variable := value + variable += more + +is exactly equivalent to: + + + variable := value + variable := $(variable) more + + On the other hand, when you use `+=' with a variable that you defined +first to be recursively-expanded using plain `=', `make' does something +a bit different. Recall that when you define a recursively-expanded +variable, `make' does not expand the value you set for variable and +function references immediately. Instead it stores the text verbatim, +and saves these variable and function references to be expanded later, +when you refer to the new variable (*note The Two Flavors of Variables: +Flavors.). When you use `+=' on a recursively-expanded variable, it is +this unexpanded text to which `make' appends the new text you specify. + + variable = value + variable += more + +is roughly equivalent to: + + temp = value + variable = $(temp) more + +except that of course it never defines a variable called `temp'. The +importance of this comes when the variable's old value contains +variable references. Take this common example: + + CFLAGS = $(includes) -O + ... + CFLAGS += -pg # enable profiling + +The first line defines the `CFLAGS' variable with a reference to another +variable, `includes'. (`CFLAGS' is used by the rules for C +compilation; *note Catalogue of Implicit Rules: Catalogue of Rules.) +Using `=' for the definition makes `CFLAGS' a recursively-expanded +variable, meaning `$(includes) -O' is _not_ expanded when `make' +processes the definition of `CFLAGS'. Thus, `includes' need not be +defined yet for its value to take effect. It only has to be defined +before any reference to `CFLAGS'. If we tried to append to the value +of `CFLAGS' without using `+=', we might do it like this: + + CFLAGS := $(CFLAGS) -pg # enable profiling + +This is pretty close, but not quite what we want. Using `:=' redefines +`CFLAGS' as a simply-expanded variable; this means `make' expands the +text `$(CFLAGS) -pg' before setting the variable. If `includes' is not +yet defined, we get ` -O -pg', and a later definition of `includes' +will have no effect. Conversely, by using `+=' we set `CFLAGS' to the +_unexpanded_ value `$(includes) -O -pg'. Thus we preserve the +reference to `includes', so if that variable gets defined at any later +point, a reference like `$(CFLAGS)' still uses its value. + + +File: make.info, Node: Override Directive, Next: Multi-Line, Prev: Appending, Up: Using Variables + +6.7 The `override' Directive +============================ + +If a variable has been set with a command argument (*note Overriding +Variables: Overriding.), then ordinary assignments in the makefile are +ignored. If you want to set the variable in the makefile even though +it was set with a command argument, you can use an `override' +directive, which is a line that looks like this: + + override VARIABLE = VALUE + +or + + override VARIABLE := VALUE + + To append more text to a variable defined on the command line, use: + + override VARIABLE += MORE TEXT + +*Note Appending More Text to Variables: Appending. + + Variable assignments marked with the `override' flag have a higher +priority than all other assignments, except another `override'. +Subsequent assignments or appends to this variable which are not marked +`override' will be ignored. + + The `override' directive was not invented for escalation in the war +between makefiles and command arguments. It was invented so you can +alter and add to values that the user specifies with command arguments. + + For example, suppose you always want the `-g' switch when you run the +C compiler, but you would like to allow the user to specify the other +switches with a command argument just as usual. You could use this +`override' directive: + + override CFLAGS += -g + + You can also use `override' directives with `define' directives. +This is done as you might expect: + + override define foo = + bar + endef + +*Note Defining Multi-Line Variables: Multi-Line. + + +File: make.info, Node: Multi-Line, Next: Undefine Directive, Prev: Override Directive, Up: Using Variables + +6.8 Defining Multi-Line Variables +================================= + +Another way to set the value of a variable is to use the `define' +directive. This directive has an unusual syntax which allows newline +characters to be included in the value, which is convenient for +defining both canned sequences of commands (*note Defining Canned +Recipes: Canned Recipes.), and also sections of makefile syntax to use +with `eval' (*note Eval Function::). + + The `define' directive is followed on the same line by the name of +the variable being defined and an (optional) assignment operator, and +nothing more. The value to give the variable appears on the following +lines. The end of the value is marked by a line containing just the +word `endef'. Aside from this difference in syntax, `define' works +just like any other variable definition. The variable name may contain +function and variable references, which are expanded when the directive +is read to find the actual variable name to use. + + You may omit the variable assignment operator if you prefer. If +omitted, `make' assumes it to be `=' and creates a recursively-expanded +variable (*note The Two Flavors of Variables: Flavors.). When using a +`+=' operator, the value is appended to the previous value as with any +other append operation: with a single space separating the old and new +values. + + You may nest `define' directives: `make' will keep track of nested +directives and report an error if they are not all properly closed with +`endef'. Note that lines beginning with the recipe prefix character +are considered part of a recipe, so any `define' or `endef' strings +appearing on such a line will not be considered `make' directives. + + define two-lines = + echo foo + echo $(bar) + endef + + The value in an ordinary assignment cannot contain a newline; but the +newlines that separate the lines of the value in a `define' become part +of the variable's value (except for the final newline which precedes +the `endef' and is not considered part of the value). + + When used in a recipe, the previous example is functionally +equivalent to this: + + two-lines = echo foo; echo $(bar) + +since two commands separated by semicolon behave much like two separate +shell commands. However, note that using two separate lines means +`make' will invoke the shell twice, running an independent subshell for +each line. *Note Recipe Execution: Execution. + + If you want variable definitions made with `define' to take +precedence over command-line variable definitions, you can use the +`override' directive together with `define': + + override define two-lines = + foo + $(bar) + endef + +*Note The `override' Directive: Override Directive. + + +File: make.info, Node: Undefine Directive, Next: Environment, Prev: Multi-Line, Up: Using Variables + +6.9 Undefining Variables +======================== + +If you want to clear a variable, setting its value to empty is usually +sufficient. Expanding such a variable will yield the same result (empty +string) regardless of whether it was set or not. However, if you are +using the `flavor' (*note Flavor Function::) and `origin' (*note Origin +Function::) functions, there is a difference between a variable that +was never set and a variable with an empty value. In such situations +you may want to use the `undefine' directive to make a variable appear +as if it was never set. For example: + + foo := foo + bar = bar + + undefine foo + undefine bar + + $(info $(origin foo)) + $(info $(flavor bar)) + + This example will print "undefined" for both variables. + + If you want to undefine a command-line variable definition, you can +use the `override' directive together with `undefine', similar to how +this is done for variable definitions: + + override undefine CFLAGS + + +File: make.info, Node: Environment, Next: Target-specific, Prev: Undefine Directive, Up: Using Variables + +6.10 Variables from the Environment +=================================== + +Variables in `make' can come from the environment in which `make' is +run. Every environment variable that `make' sees when it starts up is +transformed into a `make' variable with the same name and value. +However, an explicit assignment in the makefile, or with a command +argument, overrides the environment. (If the `-e' flag is specified, +then values from the environment override assignments in the makefile. +*Note Summary of Options: Options Summary. But this is not recommended +practice.) + + Thus, by setting the variable `CFLAGS' in your environment, you can +cause all C compilations in most makefiles to use the compiler switches +you prefer. This is safe for variables with standard or conventional +meanings because you know that no makefile will use them for other +things. (Note this is not totally reliable; some makefiles set +`CFLAGS' explicitly and therefore are not affected by the value in the +environment.) + + When `make' runs a recipe, variables defined in the makefile are +placed into the environment of each shell. This allows you to pass +values to sub-`make' invocations (*note Recursive Use of `make': +Recursion.). By default, only variables that came from the environment +or the command line are passed to recursive invocations. You can use +the `export' directive to pass other variables. *Note Communicating +Variables to a Sub-`make': Variables/Recursion, for full details. + + Other use of variables from the environment is not recommended. It +is not wise for makefiles to depend for their functioning on +environment variables set up outside their control, since this would +cause different users to get different results from the same makefile. +This is against the whole purpose of most makefiles. + + Such problems would be especially likely with the variable `SHELL', +which is normally present in the environment to specify the user's +choice of interactive shell. It would be very undesirable for this +choice to affect `make'; so, `make' handles the `SHELL' environment +variable in a special way; see *note Choosing the Shell::. + + +File: make.info, Node: Target-specific, Next: Pattern-specific, Prev: Environment, Up: Using Variables + +6.11 Target-specific Variable Values +==================================== + +Variable values in `make' are usually global; that is, they are the +same regardless of where they are evaluated (unless they're reset, of +course). One exception to that is automatic variables (*note Automatic +Variables::). + + The other exception is "target-specific variable values". This +feature allows you to define different values for the same variable, +based on the target that `make' is currently building. As with +automatic variables, these values are only available within the context +of a target's recipe (and in other target-specific assignments). + + Set a target-specific variable value like this: + + TARGET ... : VARIABLE-ASSIGNMENT + + Target-specific variable assignments can be prefixed with any or all +of the special keywords `export', `override', or `private'; these apply +their normal behavior to this instance of the variable only. + + Multiple TARGET values create a target-specific variable value for +each member of the target list individually. + + The VARIABLE-ASSIGNMENT can be any valid form of assignment; +recursive (`='), static (`:='), appending (`+='), or conditional +(`?='). All variables that appear within the VARIABLE-ASSIGNMENT are +evaluated within the context of the target: thus, any +previously-defined target-specific variable values will be in effect. +Note that this variable is actually distinct from any "global" value: +the two variables do not have to have the same flavor (recursive vs. +static). + + Target-specific variables have the same priority as any other +makefile variable. Variables provided on the command line (and in the +environment if the `-e' option is in force) will take precedence. +Specifying the `override' directive will allow the target-specific +variable value to be preferred. + + There is one more special feature of target-specific variables: when +you define a target-specific variable that variable value is also in +effect for all prerequisites of this target, and all their +prerequisites, etc. (unless those prerequisites override that variable +with their own target-specific variable value). So, for example, a +statement like this: + + prog : CFLAGS = -g + prog : prog.o foo.o bar.o + +will set `CFLAGS' to `-g' in the recipe for `prog', but it will also +set `CFLAGS' to `-g' in the recipes that create `prog.o', `foo.o', and +`bar.o', and any recipes which create their prerequisites. + + Be aware that a given prerequisite will only be built once per +invocation of make, at most. If the same file is a prerequisite of +multiple targets, and each of those targets has a different value for +the same target-specific variable, then the first target to be built +will cause that prerequisite to be built and the prerequisite will +inherit the target-specific value from the first target. It will +ignore the target-specific values from any other targets. + + +File: make.info, Node: Pattern-specific, Next: Suppressing Inheritance, Prev: Target-specific, Up: Using Variables + +6.12 Pattern-specific Variable Values +===================================== + +In addition to target-specific variable values (*note Target-specific +Variable Values: Target-specific.), GNU `make' supports +pattern-specific variable values. In this form, the variable is +defined for any target that matches the pattern specified. + + Set a pattern-specific variable value like this: + + PATTERN ... : VARIABLE-ASSIGNMENT + where PATTERN is a %-pattern. As with target-specific variable +values, multiple PATTERN values create a pattern-specific variable +value for each pattern individually. The VARIABLE-ASSIGNMENT can be +any valid form of assignment. Any command line variable setting will +take precedence, unless `override' is specified. + + For example: + + %.o : CFLAGS = -O + +will assign `CFLAGS' the value of `-O' for all targets matching the +pattern `%.o'. + + If a target matches more than one pattern, the matching +pattern-specific variables with longer stems are interpreted first. +This results in more specific variables taking precedence over the more +generic ones, for example: + + %.o: %.c + $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@ + + lib/%.o: CFLAGS := -fPIC -g + %.o: CFLAGS := -g + + all: foo.o lib/bar.o + + In this example the first definition of the `CFLAGS' variable will +be used to update `lib/bar.o' even though the second one also applies +to this target. Pattern-specific variables which result in the same +stem length are considered in the order in which they were defined in +the makefile. + + Pattern-specific variables are searched after any target-specific +variables defined explicitly for that target, and before target-specific +variables defined for the parent target. + + +File: make.info, Node: Suppressing Inheritance, Next: Special Variables, Prev: Pattern-specific, Up: Using Variables + +6.13 Suppressing Inheritance +============================ + +As described in previous sections, `make' variables are inherited by +prerequisites. This capability allows you to modify the behavior of a +prerequisite based on which targets caused it to be rebuilt. For +example, you might set a target-specific variable on a `debug' target, +then running `make debug' will cause that variable to be inherited by +all prerequisites of `debug', while just running `make all' (for +example) would not have that assignment. + + Sometimes, however, you may not want a variable to be inherited. For +these situations, `make' provides the `private' modifier. Although +this modifier can be used with any variable assignment, it makes the +most sense with target- and pattern-specific variables. Any variable +marked `private' will be visible to its local target but will not be +inherited by prerequisites of that target. A global variable marked +`private' will be visible in the global scope but will not be inherited +by any target, and hence will not be visible in any recipe. + + As an example, consider this makefile: + EXTRA_CFLAGS = + + prog: private EXTRA_CFLAGS = -L/usr/local/lib + prog: a.o b.o + + Due to the `private' modifier, `a.o' and `b.o' will not inherit the +`EXTRA_CFLAGS' variable assignment from the `progs' target. + + +File: make.info, Node: Special Variables, Prev: Suppressing Inheritance, Up: Using Variables + +6.14 Other Special Variables +============================ + +GNU `make' supports some variables that have special properties. + +`MAKEFILE_LIST' + Contains the name of each makefile that is parsed by `make', in + the order in which it was parsed. The name is appended just + before `make' begins to parse the makefile. Thus, if the first + thing a makefile does is examine the last word in this variable, it + will be the name of the current makefile. Once the current + makefile has used `include', however, the last word will be the + just-included makefile. + + If a makefile named `Makefile' has this content: + + name1 := $(lastword $(MAKEFILE_LIST)) + + include inc.mk + + name2 := $(lastword $(MAKEFILE_LIST)) + + all: + @echo name1 = $(name1) + @echo name2 = $(name2) + + then you would expect to see this output: + + name1 = Makefile + name2 = inc.mk + +`.DEFAULT_GOAL' + Sets the default goal to be used if no targets were specified on + the command line (*note Arguments to Specify the Goals: Goals.). + The `.DEFAULT_GOAL' variable allows you to discover the current + default goal, restart the default goal selection algorithm by + clearing its value, or to explicitly set the default goal. The + following example illustrates these cases: + + # Query the default goal. + ifeq ($(.DEFAULT_GOAL),) + $(warning no default goal is set) + endif + + .PHONY: foo + foo: ; @echo $@ + + $(warning default goal is $(.DEFAULT_GOAL)) + + # Reset the default goal. + .DEFAULT_GOAL := + + .PHONY: bar + bar: ; @echo $@ + + $(warning default goal is $(.DEFAULT_GOAL)) + + # Set our own. + .DEFAULT_GOAL := foo + + This makefile prints: + + no default goal is set + default goal is foo + default goal is bar + foo + + Note that assigning more than one target name to `.DEFAULT_GOAL' is + illegal and will result in an error. + +`MAKE_RESTARTS' + This variable is set only if this instance of `make' has restarted + (*note How Makefiles Are Remade: Remaking Makefiles.): it will + contain the number of times this instance has restarted. Note + this is not the same as recursion (counted by the `MAKELEVEL' + variable). You should not set, modify, or export this variable. + +`.RECIPEPREFIX' + The first character of the value of this variable is used as the + character make assumes is introducing a recipe line. If the + variable is empty (as it is by default) that character is the + standard tab character. For example, this is a valid makefile: + + .RECIPEPREFIX = > + all: + > @echo Hello, world + + The value of `.RECIPEPREFIX' can be changed multiple times; once + set it stays in effect for all rules parsed until it is modified. + +`.VARIABLES' + Expands to a list of the _names_ of all global variables defined + so far. This includes variables which have empty values, as well + as built-in variables (*note Variables Used by Implicit Rules: + Implicit Variables.), but does not include any variables which are + only defined in a target-specific context. Note that any value + you assign to this variable will be ignored; it will always return + its special value. + +`.FEATURES' + Expands to a list of special features supported by this version of + `make'. Possible values include: + + `archives' + Supports `ar' (archive) files using special filename syntax. + *Note Using `make' to Update Archive Files: Archives. + + `check-symlink' + Supports the `-L' (`--check-symlink-times') flag. *Note + Summary of Options: Options Summary. + + `else-if' + Supports "else if" non-nested conditionals. *Note Syntax of + Conditionals: Conditional Syntax. + + `jobserver' + Supports "job server" enhanced parallel builds. *Note + Parallel Execution: Parallel. + + `second-expansion' + Supports secondary expansion of prerequisite lists. + + `order-only' + Supports order-only prerequisites. *Note Types of + Prerequisites: Prerequisite Types. + + `target-specific' + Supports target-specific and pattern-specific variable + assignments. *Note Target-specific Variable Values: + Target-specific. + + +`.INCLUDE_DIRS' + Expands to a list of directories that `make' searches for included + makefiles (*note Including Other Makefiles: Include.). + + + +File: make.info, Node: Conditionals, Next: Functions, Prev: Using Variables, Up: Top + +7 Conditional Parts of Makefiles +******************************** + +A "conditional" directive causes part of a makefile to be obeyed or +ignored depending on the values of variables. Conditionals can compare +the value of one variable to another, or the value of a variable to a +constant string. Conditionals control what `make' actually "sees" in +the makefile, so they _cannot_ be used to control recipes at the time +of execution. + +* Menu: + +* Conditional Example:: Example of a conditional +* Conditional Syntax:: The syntax of conditionals. +* Testing Flags:: Conditionals that test flags. + + +File: make.info, Node: Conditional Example, Next: Conditional Syntax, Prev: Conditionals, Up: Conditionals + +7.1 Example of a Conditional +============================ + +The following example of a conditional tells `make' to use one set of +libraries if the `CC' variable is `gcc', and a different set of +libraries otherwise. It works by controlling which of two recipe lines +will be used for the rule. The result is that `CC=gcc' as an argument +to `make' changes not only which compiler is used but also which +libraries are linked. + + libs_for_gcc = -lgnu + normal_libs = + + foo: $(objects) + ifeq ($(CC),gcc) + $(CC) -o foo $(objects) $(libs_for_gcc) + else + $(CC) -o foo $(objects) $(normal_libs) + endif + + This conditional uses three directives: one `ifeq', one `else' and +one `endif'. + + The `ifeq' directive begins the conditional, and specifies the +condition. It contains two arguments, separated by a comma and +surrounded by parentheses. Variable substitution is performed on both +arguments and then they are compared. The lines of the makefile +following the `ifeq' are obeyed if the two arguments match; otherwise +they are ignored. + + The `else' directive causes the following lines to be obeyed if the +previous conditional failed. In the example above, this means that the +second alternative linking command is used whenever the first +alternative is not used. It is optional to have an `else' in a +conditional. + + The `endif' directive ends the conditional. Every conditional must +end with an `endif'. Unconditional makefile text follows. + + As this example illustrates, conditionals work at the textual level: +the lines of the conditional are treated as part of the makefile, or +ignored, according to the condition. This is why the larger syntactic +units of the makefile, such as rules, may cross the beginning or the +end of the conditional. + + When the variable `CC' has the value `gcc', the above example has +this effect: + + foo: $(objects) + $(CC) -o foo $(objects) $(libs_for_gcc) + +When the variable `CC' has any other value, the effect is this: + + foo: $(objects) + $(CC) -o foo $(objects) $(normal_libs) + + Equivalent results can be obtained in another way by +conditionalizing a variable assignment and then using the variable +unconditionally: + + libs_for_gcc = -lgnu + normal_libs = + + ifeq ($(CC),gcc) + libs=$(libs_for_gcc) + else + libs=$(normal_libs) + endif + + foo: $(objects) + $(CC) -o foo $(objects) $(libs) + + +File: make.info, Node: Conditional Syntax, Next: Testing Flags, Prev: Conditional Example, Up: Conditionals + +7.2 Syntax of Conditionals +========================== + +The syntax of a simple conditional with no `else' is as follows: + + CONDITIONAL-DIRECTIVE + TEXT-IF-TRUE + endif + +The TEXT-IF-TRUE may be any lines of text, to be considered as part of +the makefile if the condition is true. If the condition is false, no +text is used instead. + + The syntax of a complex conditional is as follows: + + CONDITIONAL-DIRECTIVE + TEXT-IF-TRUE + else + TEXT-IF-FALSE + endif + + or: + + CONDITIONAL-DIRECTIVE + TEXT-IF-ONE-IS-TRUE + else CONDITIONAL-DIRECTIVE + TEXT-IF-TRUE + else + TEXT-IF-FALSE + endif + +There can be as many "`else' CONDITIONAL-DIRECTIVE" clauses as +necessary. Once a given condition is true, TEXT-IF-TRUE is used and no +other clause is used; if no condition is true then TEXT-IF-FALSE is +used. The TEXT-IF-TRUE and TEXT-IF-FALSE can be any number of lines of +text. + + The syntax of the CONDITIONAL-DIRECTIVE is the same whether the +conditional is simple or complex; after an `else' or not. There are +four different directives that test different conditions. Here is a +table of them: + +`ifeq (ARG1, ARG2)' +`ifeq 'ARG1' 'ARG2'' +`ifeq "ARG1" "ARG2"' +`ifeq "ARG1" 'ARG2'' +`ifeq 'ARG1' "ARG2"' + Expand all variable references in ARG1 and ARG2 and compare them. + If they are identical, the TEXT-IF-TRUE is effective; otherwise, + the TEXT-IF-FALSE, if any, is effective. + + Often you want to test if a variable has a non-empty value. When + the value results from complex expansions of variables and + functions, expansions you would consider empty may actually + contain whitespace characters and thus are not seen as empty. + However, you can use the `strip' function (*note Text Functions::) + to avoid interpreting whitespace as a non-empty value. For + example: + + ifeq ($(strip $(foo)),) + TEXT-IF-EMPTY + endif + + will evaluate TEXT-IF-EMPTY even if the expansion of `$(foo)' + contains whitespace characters. + +`ifneq (ARG1, ARG2)' +`ifneq 'ARG1' 'ARG2'' +`ifneq "ARG1" "ARG2"' +`ifneq "ARG1" 'ARG2'' +`ifneq 'ARG1' "ARG2"' + Expand all variable references in ARG1 and ARG2 and compare them. + If they are different, the TEXT-IF-TRUE is effective; otherwise, + the TEXT-IF-FALSE, if any, is effective. + +`ifdef VARIABLE-NAME' + The `ifdef' form takes the _name_ of a variable as its argument, + not a reference to a variable. The value of that variable has a + non-empty value, the TEXT-IF-TRUE is effective; otherwise, the + TEXT-IF-FALSE, if any, is effective. Variables that have never + been defined have an empty value. The text VARIABLE-NAME is + expanded, so it could be a variable or function that expands to + the name of a variable. For example: + + bar = true + foo = bar + ifdef $(foo) + frobozz = yes + endif + + The variable reference `$(foo)' is expanded, yielding `bar', which + is considered to be the name of a variable. The variable `bar' is + not expanded, but its value is examined to determine if it is + non-empty. + + Note that `ifdef' only tests whether a variable has a value. It + does not expand the variable to see if that value is nonempty. + Consequently, tests using `ifdef' return true for all definitions + except those like `foo ='. To test for an empty value, use + `ifeq ($(foo),)'. For example, + + bar = + foo = $(bar) + ifdef foo + frobozz = yes + else + frobozz = no + endif + + sets `frobozz' to `yes', while: + + foo = + ifdef foo + frobozz = yes + else + frobozz = no + endif + + sets `frobozz' to `no'. + +`ifndef VARIABLE-NAME' + If the variable VARIABLE-NAME has an empty value, the TEXT-IF-TRUE + is effective; otherwise, the TEXT-IF-FALSE, if any, is effective. + The rules for expansion and testing of VARIABLE-NAME are identical + to the `ifdef' directive. + + Extra spaces are allowed and ignored at the beginning of the +conditional directive line, but a tab is not allowed. (If the line +begins with a tab, it will be considered part of a recipe for a rule.) +Aside from this, extra spaces or tabs may be inserted with no effect +anywhere except within the directive name or within an argument. A +comment starting with `#' may appear at the end of the line. + + The other two directives that play a part in a conditional are `else' +and `endif'. Each of these directives is written as one word, with no +arguments. Extra spaces are allowed and ignored at the beginning of the +line, and spaces or tabs at the end. A comment starting with `#' may +appear at the end of the line. + + Conditionals affect which lines of the makefile `make' uses. If the +condition is true, `make' reads the lines of the TEXT-IF-TRUE as part +of the makefile; if the condition is false, `make' ignores those lines +completely. It follows that syntactic units of the makefile, such as +rules, may safely be split across the beginning or the end of the +conditional. + + `make' evaluates conditionals when it reads a makefile. +Consequently, you cannot use automatic variables in the tests of +conditionals because they are not defined until recipes are run (*note +Automatic Variables::). + + To prevent intolerable confusion, it is not permitted to start a +conditional in one makefile and end it in another. However, you may +write an `include' directive within a conditional, provided you do not +attempt to terminate the conditional inside the included file. + + +File: make.info, Node: Testing Flags, Prev: Conditional Syntax, Up: Conditionals + +7.3 Conditionals that Test Flags +================================ + +You can write a conditional that tests `make' command flags such as +`-t' by using the variable `MAKEFLAGS' together with the `findstring' +function (*note Functions for String Substitution and Analysis: Text +Functions.). This is useful when `touch' is not enough to make a file +appear up to date. + + The `findstring' function determines whether one string appears as a +substring of another. If you want to test for the `-t' flag, use `t' +as the first string and the value of `MAKEFLAGS' as the other. + + For example, here is how to arrange to use `ranlib -t' to finish +marking an archive file up to date: + + archive.a: ... + ifneq (,$(findstring t,$(MAKEFLAGS))) + +touch archive.a + +ranlib -t archive.a + else + ranlib archive.a + endif + +The `+' prefix marks those recipe lines as "recursive" so that they +will be executed despite use of the `-t' flag. *Note Recursive Use of +`make': Recursion. + + +File: make.info, Node: Functions, Next: Running, Prev: Conditionals, Up: Top + +8 Functions for Transforming Text +********************************* + +"Functions" allow you to do text processing in the makefile to compute +the files to operate on or the commands to use in recipes. You use a +function in a "function call", where you give the name of the function +and some text (the "arguments") for the function to operate on. The +result of the function's processing is substituted into the makefile at +the point of the call, just as a variable might be substituted. + +* Menu: + +* Syntax of Functions:: How to write a function call. +* Text Functions:: General-purpose text manipulation functions. +* File Name Functions:: Functions for manipulating file names. +* Conditional Functions:: Functions that implement conditions. +* Foreach Function:: Repeat some text with controlled variation. +* Call Function:: Expand a user-defined function. +* Value Function:: Return the un-expanded value of a variable. +* Eval Function:: Evaluate the arguments as makefile syntax. +* Origin Function:: Find where a variable got its value. +* Flavor Function:: Find out the flavor of a variable. +* Shell Function:: Substitute the output of a shell command. +* Make Control Functions:: Functions that control how make runs. + + +File: make.info, Node: Syntax of Functions, Next: Text Functions, Prev: Functions, Up: Functions + +8.1 Function Call Syntax +======================== + +A function call resembles a variable reference. It looks like this: + + $(FUNCTION ARGUMENTS) + +or like this: + + ${FUNCTION ARGUMENTS} + + Here FUNCTION is a function name; one of a short list of names that +are part of `make'. You can also essentially create your own functions +by using the `call' builtin function. + + The ARGUMENTS are the arguments of the function. They are separated +from the function name by one or more spaces or tabs, and if there is +more than one argument, then they are separated by commas. Such +whitespace and commas are not part of an argument's value. The +delimiters which you use to surround the function call, whether +parentheses or braces, can appear in an argument only in matching pairs; +the other kind of delimiters may appear singly. If the arguments +themselves contain other function calls or variable references, it is +wisest to use the same kind of delimiters for all the references; write +`$(subst a,b,$(x))', not `$(subst a,b,${x})'. This is because it is +clearer, and because only one type of delimiter is matched to find the +end of the reference. + + The text written for each argument is processed by substitution of +variables and function calls to produce the argument value, which is +the text on which the function acts. The substitution is done in the +order in which the arguments appear. + + Commas and unmatched parentheses or braces cannot appear in the text +of an argument as written; leading spaces cannot appear in the text of +the first argument as written. These characters can be put into the +argument value by variable substitution. First define variables +`comma' and `space' whose values are isolated comma and space +characters, then substitute these variables where such characters are +wanted, like this: + + comma:= , + empty:= + space:= $(empty) $(empty) + foo:= a b c + bar:= $(subst $(space),$(comma),$(foo)) + # bar is now `a,b,c'. + +Here the `subst' function replaces each space with a comma, through the +value of `foo', and substitutes the result. + + +File: make.info, Node: Text Functions, Next: File Name Functions, Prev: Syntax of Functions, Up: Functions + +8.2 Functions for String Substitution and Analysis +================================================== + +Here are some functions that operate on strings: + +`$(subst FROM,TO,TEXT)' + Performs a textual replacement on the text TEXT: each occurrence + of FROM is replaced by TO. The result is substituted for the + function call. For example, + + $(subst ee,EE,feet on the street) + + substitutes the string `fEEt on the strEEt'. + +`$(patsubst PATTERN,REPLACEMENT,TEXT)' + Finds whitespace-separated words in TEXT that match PATTERN and + replaces them with REPLACEMENT. Here PATTERN may contain a `%' + which acts as a wildcard, matching any number of any characters + within a word. If REPLACEMENT also contains a `%', the `%' is + replaced by the text that matched the `%' in PATTERN. Only the + first `%' in the PATTERN and REPLACEMENT is treated this way; any + subsequent `%' is unchanged. + + `%' characters in `patsubst' function invocations can be quoted + with preceding backslashes (`\'). Backslashes that would + otherwise quote `%' characters can be quoted with more backslashes. + Backslashes that quote `%' characters or other backslashes are + removed from the pattern before it is compared file names or has a + stem substituted into it. Backslashes that are not in danger of + quoting `%' characters go unmolested. For example, the pattern + `the\%weird\\%pattern\\' has `the%weird\' preceding the operative + `%' character, and `pattern\\' following it. The final two + backslashes are left alone because they cannot affect any `%' + character. + + Whitespace between words is folded into single space characters; + leading and trailing whitespace is discarded. + + For example, + + $(patsubst %.c,%.o,x.c.c bar.c) + + produces the value `x.c.o bar.o'. + + Substitution references (*note Substitution References: + Substitution Refs.) are a simpler way to get the effect of the + `patsubst' function: + + $(VAR:PATTERN=REPLACEMENT) + + is equivalent to + + $(patsubst PATTERN,REPLACEMENT,$(VAR)) + + The second shorthand simplifies one of the most common uses of + `patsubst': replacing the suffix at the end of file names. + + $(VAR:SUFFIX=REPLACEMENT) + + is equivalent to + + $(patsubst %SUFFIX,%REPLACEMENT,$(VAR)) + + For example, you might have a list of object files: + + objects = foo.o bar.o baz.o + + To get the list of corresponding source files, you could simply + write: + + $(objects:.o=.c) + + instead of using the general form: + + $(patsubst %.o,%.c,$(objects)) + +`$(strip STRING)' + Removes leading and trailing whitespace from STRING and replaces + each internal sequence of one or more whitespace characters with a + single space. Thus, `$(strip a b c )' results in `a b c'. + + The function `strip' can be very useful when used in conjunction + with conditionals. When comparing something with the empty string + `' using `ifeq' or `ifneq', you usually want a string of just + whitespace to match the empty string (*note Conditionals::). + + Thus, the following may fail to have the desired results: + + .PHONY: all + ifneq "$(needs_made)" "" + all: $(needs_made) + else + all:;@echo 'Nothing to make!' + endif + + Replacing the variable reference `$(needs_made)' with the function + call `$(strip $(needs_made))' in the `ifneq' directive would make + it more robust. + +`$(findstring FIND,IN)' + Searches IN for an occurrence of FIND. If it occurs, the value is + FIND; otherwise, the value is empty. You can use this function in + a conditional to test for the presence of a specific substring in + a given string. Thus, the two examples, + + $(findstring a,a b c) + $(findstring a,b c) + + produce the values `a' and `' (the empty string), respectively. + *Note Testing Flags::, for a practical application of `findstring'. + +`$(filter PATTERN...,TEXT)' + Returns all whitespace-separated words in TEXT that _do_ match any + of the PATTERN words, removing any words that _do not_ match. The + patterns are written using `%', just like the patterns used in the + `patsubst' function above. + + The `filter' function can be used to separate out different types + of strings (such as file names) in a variable. For example: + + sources := foo.c bar.c baz.s ugh.h + foo: $(sources) + cc $(filter %.c %.s,$(sources)) -o foo + + says that `foo' depends of `foo.c', `bar.c', `baz.s' and `ugh.h' + but only `foo.c', `bar.c' and `baz.s' should be specified in the + command to the compiler. + +`$(filter-out PATTERN...,TEXT)' + Returns all whitespace-separated words in TEXT that _do not_ match + any of the PATTERN words, removing the words that _do_ match one + or more. This is the exact opposite of the `filter' function. + + For example, given: + + objects=main1.o foo.o main2.o bar.o + mains=main1.o main2.o + + the following generates a list which contains all the object files + not in `mains': + + $(filter-out $(mains),$(objects)) + +`$(sort LIST)' + Sorts the words of LIST in lexical order, removing duplicate + words. The output is a list of words separated by single spaces. + Thus, + + $(sort foo bar lose) + + returns the value `bar foo lose'. + + Incidentally, since `sort' removes duplicate words, you can use it + for this purpose even if you don't care about the sort order. + +`$(word N,TEXT)' + Returns the Nth word of TEXT. The legitimate values of N start + from 1. If N is bigger than the number of words in TEXT, the + value is empty. For example, + + $(word 2, foo bar baz) + + returns `bar'. + +`$(wordlist S,E,TEXT)' + Returns the list of words in TEXT starting with word S and ending + with word E (inclusive). The legitimate values of S start from 1; + E may start from 0. If S is bigger than the number of words in + TEXT, the value is empty. If E is bigger than the number of words + in TEXT, words up to the end of TEXT are returned. If S is + greater than E, nothing is returned. For example, + + $(wordlist 2, 3, foo bar baz) + + returns `bar baz'. + +`$(words TEXT)' + Returns the number of words in TEXT. Thus, the last word of TEXT + is `$(word $(words TEXT),TEXT)'. + +`$(firstword NAMES...)' + The argument NAMES is regarded as a series of names, separated by + whitespace. The value is the first name in the series. The rest + of the names are ignored. + + For example, + + $(firstword foo bar) + + produces the result `foo'. Although `$(firstword TEXT)' is the + same as `$(word 1,TEXT)', the `firstword' function is retained for + its simplicity. + +`$(lastword NAMES...)' + The argument NAMES is regarded as a series of names, separated by + whitespace. The value is the last name in the series. + + For example, + + $(lastword foo bar) + + produces the result `bar'. Although `$(lastword TEXT)' is the + same as `$(word $(words TEXT),TEXT)', the `lastword' function was + added for its simplicity and better performance. + + Here is a realistic example of the use of `subst' and `patsubst'. +Suppose that a makefile uses the `VPATH' variable to specify a list of +directories that `make' should search for prerequisite files (*note +`VPATH' Search Path for All Prerequisites: General Search.). This +example shows how to tell the C compiler to search for header files in +the same list of directories. + + The value of `VPATH' is a list of directories separated by colons, +such as `src:../headers'. First, the `subst' function is used to +change the colons to spaces: + + $(subst :, ,$(VPATH)) + +This produces `src ../headers'. Then `patsubst' is used to turn each +directory name into a `-I' flag. These can be added to the value of +the variable `CFLAGS', which is passed automatically to the C compiler, +like this: + + override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH))) + +The effect is to append the text `-Isrc -I../headers' to the previously +given value of `CFLAGS'. The `override' directive is used so that the +new value is assigned even if the previous value of `CFLAGS' was +specified with a command argument (*note The `override' Directive: +Override Directive.). + + +File: make.info, Node: File Name Functions, Next: Conditional Functions, Prev: Text Functions, Up: Functions + +8.3 Functions for File Names +============================ + +Several of the built-in expansion functions relate specifically to +taking apart file names or lists of file names. + + Each of the following functions performs a specific transformation +on a file name. The argument of the function is regarded as a series +of file names, separated by whitespace. (Leading and trailing +whitespace is ignored.) Each file name in the series is transformed in +the same way and the results are concatenated with single spaces +between them. + +`$(dir NAMES...)' + Extracts the directory-part of each file name in NAMES. The + directory-part of the file name is everything up through (and + including) the last slash in it. If the file name contains no + slash, the directory part is the string `./'. For example, + + $(dir src/foo.c hacks) + + produces the result `src/ ./'. + +`$(notdir NAMES...)' + Extracts all but the directory-part of each file name in NAMES. + If the file name contains no slash, it is left unchanged. + Otherwise, everything through the last slash is removed from it. + + A file name that ends with a slash becomes an empty string. This + is unfortunate, because it means that the result does not always + have the same number of whitespace-separated file names as the + argument had; but we do not see any other valid alternative. + + For example, + + $(notdir src/foo.c hacks) + + produces the result `foo.c hacks'. + +`$(suffix NAMES...)' + Extracts the suffix of each file name in NAMES. If the file name + contains a period, the suffix is everything starting with the last + period. Otherwise, the suffix is the empty string. This + frequently means that the result will be empty when NAMES is not, + and if NAMES contains multiple file names, the result may contain + fewer file names. + + For example, + + $(suffix src/foo.c src-1.0/bar.c hacks) + + produces the result `.c .c'. + +`$(basename NAMES...)' + Extracts all but the suffix of each file name in NAMES. If the + file name contains a period, the basename is everything starting + up to (and not including) the last period. Periods in the + directory part are ignored. If there is no period, the basename + is the entire file name. For example, + + $(basename src/foo.c src-1.0/bar hacks) + + produces the result `src/foo src-1.0/bar hacks'. + +`$(addsuffix SUFFIX,NAMES...)' + The argument NAMES is regarded as a series of names, separated by + whitespace; SUFFIX is used as a unit. The value of SUFFIX is + appended to the end of each individual name and the resulting + larger names are concatenated with single spaces between them. + For example, + + $(addsuffix .c,foo bar) + + produces the result `foo.c bar.c'. + +`$(addprefix PREFIX,NAMES...)' + The argument NAMES is regarded as a series of names, separated by + whitespace; PREFIX is used as a unit. The value of PREFIX is + prepended to the front of each individual name and the resulting + larger names are concatenated with single spaces between them. + For example, + + $(addprefix src/,foo bar) + + produces the result `src/foo src/bar'. + +`$(join LIST1,LIST2)' + Concatenates the two arguments word by word: the two first words + (one from each argument) concatenated form the first word of the + result, the two second words form the second word of the result, + and so on. So the Nth word of the result comes from the Nth word + of each argument. If one argument has more words that the other, + the extra words are copied unchanged into the result. + + For example, `$(join a b,.c .o)' produces `a.c b.o'. + + Whitespace between the words in the lists is not preserved; it is + replaced with a single space. + + This function can merge the results of the `dir' and `notdir' + functions, to produce the original list of files which was given + to those two functions. + +`$(wildcard PATTERN)' + The argument PATTERN is a file name pattern, typically containing + wildcard characters (as in shell file name patterns). The result + of `wildcard' is a space-separated list of the names of existing + files that match the pattern. *Note Using Wildcard Characters in + File Names: Wildcards. + +`$(realpath NAMES...)' + For each file name in NAMES return the canonical absolute name. A + canonical name does not contain any `.' or `..' components, nor + any repeated path separators (`/') or symlinks. In case of a + failure the empty string is returned. Consult the `realpath(3)' + documentation for a list of possible failure causes. + +`$(abspath NAMES...)' + For each file name in NAMES return an absolute name that does not + contain any `.' or `..' components, nor any repeated path + separators (`/'). Note that, in contrast to `realpath' function, + `abspath' does not resolve symlinks and does not require the file + names to refer to an existing file or directory. Use the + `wildcard' function to test for existence. + + +File: make.info, Node: Conditional Functions, Next: Foreach Function, Prev: File Name Functions, Up: Functions + +8.4 Functions for Conditionals +============================== + +There are three functions that provide conditional expansion. A key +aspect of these functions is that not all of the arguments are expanded +initially. Only those arguments which need to be expanded, will be +expanded. + +`$(if CONDITION,THEN-PART[,ELSE-PART])' + The `if' function provides support for conditional expansion in a + functional context (as opposed to the GNU `make' makefile + conditionals such as `ifeq' (*note Syntax of Conditionals: + Conditional Syntax.). + + The first argument, CONDITION, first has all preceding and + trailing whitespace stripped, then is expanded. If it expands to + any non-empty string, then the condition is considered to be true. + If it expands to an empty string, the condition is considered to + be false. + + If the condition is true then the second argument, THEN-PART, is + evaluated and this is used as the result of the evaluation of the + entire `if' function. + + If the condition is false then the third argument, ELSE-PART, is + evaluated and this is the result of the `if' function. If there is + no third argument, the `if' function evaluates to nothing (the + empty string). + + Note that only one of the THEN-PART or the ELSE-PART will be + evaluated, never both. Thus, either can contain side-effects + (such as `shell' function calls, etc.) + +`$(or CONDITION1[,CONDITION2[,CONDITION3...]])' + The `or' function provides a "short-circuiting" OR operation. + Each argument is expanded, in order. If an argument expands to a + non-empty string the processing stops and the result of the + expansion is that string. If, after all arguments are expanded, + all of them are false (empty), then the result of the expansion is + the empty string. + +`$(and CONDITION1[,CONDITION2[,CONDITION3...]])' + The `and' function provides a "short-circuiting" AND operation. + Each argument is expanded, in order. If an argument expands to an + empty string the processing stops and the result of the expansion + is the empty string. If all arguments expand to a non-empty + string then the result of the expansion is the expansion of the + last argument. + + + +File: make.info, Node: Foreach Function, Next: Call Function, Prev: Conditional Functions, Up: Functions + +8.5 The `foreach' Function +========================== + +The `foreach' function is very different from other functions. It +causes one piece of text to be used repeatedly, each time with a +different substitution performed on it. It resembles the `for' command +in the shell `sh' and the `foreach' command in the C-shell `csh'. + + The syntax of the `foreach' function is: + + $(foreach VAR,LIST,TEXT) + +The first two arguments, VAR and LIST, are expanded before anything +else is done; note that the last argument, TEXT, is *not* expanded at +the same time. Then for each word of the expanded value of LIST, the +variable named by the expanded value of VAR is set to that word, and +TEXT is expanded. Presumably TEXT contains references to that +variable, so its expansion will be different each time. + + The result is that TEXT is expanded as many times as there are +whitespace-separated words in LIST. The multiple expansions of TEXT +are concatenated, with spaces between them, to make the result of +`foreach'. + + This simple example sets the variable `files' to the list of all +files in the directories in the list `dirs': + + dirs := a b c d + files := $(foreach dir,$(dirs),$(wildcard $(dir)/*)) + + Here TEXT is `$(wildcard $(dir)/*)'. The first repetition finds the +value `a' for `dir', so it produces the same result as `$(wildcard +a/*)'; the second repetition produces the result of `$(wildcard b/*)'; +and the third, that of `$(wildcard c/*)'. + + This example has the same result (except for setting `dirs') as the +following example: + + files := $(wildcard a/* b/* c/* d/*) + + When TEXT is complicated, you can improve readability by giving it a +name, with an additional variable: + + find_files = $(wildcard $(dir)/*) + dirs := a b c d + files := $(foreach dir,$(dirs),$(find_files)) + +Here we use the variable `find_files' this way. We use plain `=' to +define a recursively-expanding variable, so that its value contains an +actual function call to be reexpanded under the control of `foreach'; a +simply-expanded variable would not do, since `wildcard' would be called +only once at the time of defining `find_files'. + + The `foreach' function has no permanent effect on the variable VAR; +its value and flavor after the `foreach' function call are the same as +they were beforehand. The other values which are taken from LIST are +in effect only temporarily, during the execution of `foreach'. The +variable VAR is a simply-expanded variable during the execution of +`foreach'. If VAR was undefined before the `foreach' function call, it +is undefined after the call. *Note The Two Flavors of Variables: +Flavors. + + You must take care when using complex variable expressions that +result in variable names because many strange things are valid variable +names, but are probably not what you intended. For example, + + files := $(foreach Esta escrito en espanol!,b c ch,$(find_files)) + +might be useful if the value of `find_files' references the variable +whose name is `Esta escrito en espanol!' (es un nombre bastante largo, +no?), but it is more likely to be a mistake. + + +File: make.info, Node: Call Function, Next: Value Function, Prev: Foreach Function, Up: Functions + +8.6 The `call' Function +======================= + +The `call' function is unique in that it can be used to create new +parameterized functions. You can write a complex expression as the +value of a variable, then use `call' to expand it with different values. + + The syntax of the `call' function is: + + $(call VARIABLE,PARAM,PARAM,...) + + When `make' expands this function, it assigns each PARAM to +temporary variables `$(1)', `$(2)', etc. The variable `$(0)' will +contain VARIABLE. There is no maximum number of parameter arguments. +There is no minimum, either, but it doesn't make sense to use `call' +with no parameters. + + Then VARIABLE is expanded as a `make' variable in the context of +these temporary assignments. Thus, any reference to `$(1)' in the +value of VARIABLE will resolve to the first PARAM in the invocation of +`call'. + + Note that VARIABLE is the _name_ of a variable, not a _reference_ to +that variable. Therefore you would not normally use a `$' or +parentheses when writing it. (You can, however, use a variable +reference in the name if you want the name not to be a constant.) + + If VARIABLE is the name of a builtin function, the builtin function +is always invoked (even if a `make' variable by that name also exists). + + The `call' function expands the PARAM arguments before assigning +them to temporary variables. This means that VARIABLE values +containing references to builtin functions that have special expansion +rules, like `foreach' or `if', may not work as you expect. + + Some examples may make this clearer. + + This macro simply reverses its arguments: + + reverse = $(2) $(1) + + foo = $(call reverse,a,b) + +Here FOO will contain `b a'. + + This one is slightly more interesting: it defines a macro to search +for the first instance of a program in `PATH': + + pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH))))) + + LS := $(call pathsearch,ls) + +Now the variable LS contains `/bin/ls' or similar. + + The `call' function can be nested. Each recursive invocation gets +its own local values for `$(1)', etc. that mask the values of +higher-level `call'. For example, here is an implementation of a "map" +function: + + map = $(foreach a,$(2),$(call $(1),$(a))) + + Now you can MAP a function that normally takes only one argument, +such as `origin', to multiple values in one step: + + o = $(call map,origin,o map MAKE) + + and end up with O containing something like `file file default'. + + A final caution: be careful when adding whitespace to the arguments +to `call'. As with other functions, any whitespace contained in the +second and subsequent arguments is kept; this can cause strange +effects. It's generally safest to remove all extraneous whitespace when +providing parameters to `call'. + + +File: make.info, Node: Value Function, Next: Eval Function, Prev: Call Function, Up: Functions + +8.7 The `value' Function +======================== + +The `value' function provides a way for you to use the value of a +variable _without_ having it expanded. Please note that this does not +undo expansions which have already occurred; for example if you create +a simply expanded variable its value is expanded during the definition; +in that case the `value' function will return the same result as using +the variable directly. + + The syntax of the `value' function is: + + $(value VARIABLE) + + Note that VARIABLE is the _name_ of a variable; not a _reference_ to +that variable. Therefore you would not normally use a `$' or +parentheses when writing it. (You can, however, use a variable +reference in the name if you want the name not to be a constant.) + + The result of this function is a string containing the value of +VARIABLE, without any expansion occurring. For example, in this +makefile: + + FOO = $PATH + + all: + @echo $(FOO) + @echo $(value FOO) + +The first output line would be `ATH', since the "$P" would be expanded +as a `make' variable, while the second output line would be the current +value of your `$PATH' environment variable, since the `value' function +avoided the expansion. + + The `value' function is most often used in conjunction with the +`eval' function (*note Eval Function::). + + +File: make.info, Node: Eval Function, Next: Origin Function, Prev: Value Function, Up: Functions + +8.8 The `eval' Function +======================= + +The `eval' function is very special: it allows you to define new +makefile constructs that are not constant; which are the result of +evaluating other variables and functions. The argument to the `eval' +function is expanded, then the results of that expansion are parsed as +makefile syntax. The expanded results can define new `make' variables, +targets, implicit or explicit rules, etc. + + The result of the `eval' function is always the empty string; thus, +it can be placed virtually anywhere in a makefile without causing +syntax errors. + + It's important to realize that the `eval' argument is expanded +_twice_; first by the `eval' function, then the results of that +expansion are expanded again when they are parsed as makefile syntax. +This means you may need to provide extra levels of escaping for "$" +characters when using `eval'. The `value' function (*note Value +Function::) can sometimes be useful in these situations, to circumvent +unwanted expansions. + + Here is an example of how `eval' can be used; this example combines +a number of concepts and other functions. Although it might seem +overly complex to use `eval' in this example, rather than just writing +out the rules, consider two things: first, the template definition (in +`PROGRAM_template') could need to be much more complex than it is here; +and second, you might put the complex, "generic" part of this example +into another makefile, then include it in all the individual makefiles. +Now your individual makefiles are quite straightforward. + + PROGRAMS = server client + + server_OBJS = server.o server_priv.o server_access.o + server_LIBS = priv protocol + + client_OBJS = client.o client_api.o client_mem.o + client_LIBS = protocol + + # Everything after this is generic + + .PHONY: all + all: $(PROGRAMS) + + define PROGRAM_template = + $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%) + ALL_OBJS += $$($(1)_OBJS) + endef + + $(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog)))) + + $(PROGRAMS): + $(LINK.o) $^ $(LDLIBS) -o $@ + + clean: + rm -f $(ALL_OBJS) $(PROGRAMS) + + +File: make.info, Node: Origin Function, Next: Flavor Function, Prev: Eval Function, Up: Functions + +8.9 The `origin' Function +========================= + +The `origin' function is unlike most other functions in that it does +not operate on the values of variables; it tells you something _about_ +a variable. Specifically, it tells you where it came from. + + The syntax of the `origin' function is: + + $(origin VARIABLE) + + Note that VARIABLE is the _name_ of a variable to inquire about; not +a _reference_ to that variable. Therefore you would not normally use a +`$' or parentheses when writing it. (You can, however, use a variable +reference in the name if you want the name not to be a constant.) + + The result of this function is a string telling you how the variable +VARIABLE was defined: + +`undefined' + if VARIABLE was never defined. + +`default' + if VARIABLE has a default definition, as is usual with `CC' and so + on. *Note Variables Used by Implicit Rules: Implicit Variables. + Note that if you have redefined a default variable, the `origin' + function will return the origin of the later definition. + +`environment' + if VARIABLE was inherited from the environment provided to `make'. + +`environment override' + if VARIABLE was inherited from the environment provided to `make', + and is overriding a setting for VARIABLE in the makefile as a + result of the `-e' option (*note Summary of Options: Options + Summary.). + +`file' + if VARIABLE was defined in a makefile. + +`command line' + if VARIABLE was defined on the command line. + +`override' + if VARIABLE was defined with an `override' directive in a makefile + (*note The `override' Directive: Override Directive.). + +`automatic' + if VARIABLE is an automatic variable defined for the execution of + the recipe for each rule (*note Automatic Variables::). + + This information is primarily useful (other than for your curiosity) +to determine if you want to believe the value of a variable. For +example, suppose you have a makefile `foo' that includes another +makefile `bar'. You want a variable `bletch' to be defined in `bar' if +you run the command `make -f bar', even if the environment contains a +definition of `bletch'. However, if `foo' defined `bletch' before +including `bar', you do not want to override that definition. This +could be done by using an `override' directive in `foo', giving that +definition precedence over the later definition in `bar'; +unfortunately, the `override' directive would also override any command +line definitions. So, `bar' could include: + + ifdef bletch + ifeq "$(origin bletch)" "environment" + bletch = barf, gag, etc. + endif + endif + +If `bletch' has been defined from the environment, this will redefine +it. + + If you want to override a previous definition of `bletch' if it came +from the environment, even under `-e', you could instead write: + + ifneq "$(findstring environment,$(origin bletch))" "" + bletch = barf, gag, etc. + endif + + Here the redefinition takes place if `$(origin bletch)' returns +either `environment' or `environment override'. *Note Functions for +String Substitution and Analysis: Text Functions. + + +File: make.info, Node: Flavor Function, Next: Shell Function, Prev: Origin Function, Up: Functions + +8.10 The `flavor' Function +========================== + +The `flavor' function is unlike most other functions (and like `origin' +function) in that it does not operate on the values of variables; it +tells you something _about_ a variable. Specifically, it tells you the +flavor of a variable (*note The Two Flavors of Variables: Flavors.). + + The syntax of the `flavor' function is: + + $(flavor VARIABLE) + + Note that VARIABLE is the _name_ of a variable to inquire about; not +a _reference_ to that variable. Therefore you would not normally use a +`$' or parentheses when writing it. (You can, however, use a variable +reference in the name if you want the name not to be a constant.) + + The result of this function is a string that identifies the flavor +of the variable VARIABLE: + +`undefined' + if VARIABLE was never defined. + +`recursive' + if VARIABLE is a recursively expanded variable. + +`simple' + if VARIABLE is a simply expanded variable. + + + +File: make.info, Node: Shell Function, Next: Make Control Functions, Prev: Flavor Function, Up: Functions + +8.11 The `shell' Function +========================= + +The `shell' function is unlike any other function other than the +`wildcard' function (*note The Function `wildcard': Wildcard Function.) +in that it communicates with the world outside of `make'. + + The `shell' function performs the same function that backquotes +(``') perform in most shells: it does "command expansion". This means +that it takes as an argument a shell command and evaluates to the +output of the command. The only processing `make' does on the result +is to convert each newline (or carriage-return / newline pair) to a +single space. If there is a trailing (carriage-return and) newline it +will simply be removed. + + The commands run by calls to the `shell' function are run when the +function calls are expanded (*note How `make' Reads a Makefile: Reading +Makefiles.). Because this function involves spawning a new shell, you +should carefully consider the performance implications of using the +`shell' function within recursively expanded variables vs. simply +expanded variables (*note The Two Flavors of Variables: Flavors.). + + Here are some examples of the use of the `shell' function: + + contents := $(shell cat foo) + +sets `contents' to the contents of the file `foo', with a space (rather +than a newline) separating each line. + + files := $(shell echo *.c) + +sets `files' to the expansion of `*.c'. Unless `make' is using a very +strange shell, this has the same result as `$(wildcard *.c)' (as long +as at least one `.c' file exists). + + +File: make.info, Node: Make Control Functions, Prev: Shell Function, Up: Functions + +8.12 Functions That Control Make +================================ + +These functions control the way make runs. Generally, they are used to +provide information to the user of the makefile or to cause make to stop +if some sort of environmental error is detected. + +`$(error TEXT...)' + Generates a fatal error where the message is TEXT. Note that the + error is generated whenever this function is evaluated. So, if + you put it inside a recipe or on the right side of a recursive + variable assignment, it won't be evaluated until later. The TEXT + will be expanded before the error is generated. + + For example, + + ifdef ERROR1 + $(error error is $(ERROR1)) + endif + + will generate a fatal error during the read of the makefile if the + `make' variable `ERROR1' is defined. Or, + + ERR = $(error found an error!) + + .PHONY: err + err: ; $(ERR) + + will generate a fatal error while `make' is running, if the `err' + target is invoked. + +`$(warning TEXT...)' + This function works similarly to the `error' function, above, + except that `make' doesn't exit. Instead, TEXT is expanded and + the resulting message is displayed, but processing of the makefile + continues. + + The result of the expansion of this function is the empty string. + +`$(info TEXT...)' + This function does nothing more than print its (expanded) + argument(s) to standard output. No makefile name or line number + is added. The result of the expansion of this function is the + empty string. + + +File: make.info, Node: Running, Next: Implicit Rules, Prev: Functions, Up: Top + +9 How to Run `make' +******************* + +A makefile that says how to recompile a program can be used in more +than one way. The simplest use is to recompile every file that is out +of date. Usually, makefiles are written so that if you run `make' with +no arguments, it does just that. + + But you might want to update only some of the files; you might want +to use a different compiler or different compiler options; you might +want just to find out which files are out of date without changing them. + + By giving arguments when you run `make', you can do any of these +things and many others. + + The exit status of `make' is always one of three values: +`0' + The exit status is zero if `make' is successful. + +`2' + The exit status is two if `make' encounters any errors. It will + print messages describing the particular errors. + +`1' + The exit status is one if you use the `-q' flag and `make' + determines that some target is not already up to date. *Note + Instead of Executing Recipes: Instead of Execution. + +* Menu: + +* Makefile Arguments:: How to specify which makefile to use. +* Goals:: How to use goal arguments to specify which + parts of the makefile to use. +* Instead of Execution:: How to use mode flags to specify what + kind of thing to do with the recipes + in the makefile other than simply + execute them. +* Avoiding Compilation:: How to avoid recompiling certain files. +* Overriding:: How to override a variable to specify + an alternate compiler and other things. +* Testing:: How to proceed past some errors, to + test compilation. +* Options Summary:: Summary of Options + + +File: make.info, Node: Makefile Arguments, Next: Goals, Prev: Running, Up: Running + +9.1 Arguments to Specify the Makefile +===================================== + +The way to specify the name of the makefile is with the `-f' or +`--file' option (`--makefile' also works). For example, `-f altmake' +says to use the file `altmake' as the makefile. + + If you use the `-f' flag several times and follow each `-f' with an +argument, all the specified files are used jointly as makefiles. + + If you do not use the `-f' or `--file' flag, the default is to try +`GNUmakefile', `makefile', and `Makefile', in that order, and use the +first of these three which exists or can be made (*note Writing +Makefiles: Makefiles.). + + +File: make.info, Node: Goals, Next: Instead of Execution, Prev: Makefile Arguments, Up: Running + +9.2 Arguments to Specify the Goals +================================== + +The "goals" are the targets that `make' should strive ultimately to +update. Other targets are updated as well if they appear as +prerequisites of goals, or prerequisites of prerequisites of goals, etc. + + By default, the goal is the first target in the makefile (not +counting targets that start with a period). Therefore, makefiles are +usually written so that the first target is for compiling the entire +program or programs they describe. If the first rule in the makefile +has several targets, only the first target in the rule becomes the +default goal, not the whole list. You can manage the selection of the +default goal from within your makefile using the `.DEFAULT_GOAL' +variable (*note Other Special Variables: Special Variables.). + + You can also specify a different goal or goals with command line +arguments to `make'. Use the name of the goal as an argument. If you +specify several goals, `make' processes each of them in turn, in the +order you name them. + + Any target in the makefile may be specified as a goal (unless it +starts with `-' or contains an `=', in which case it will be parsed as +a switch or variable definition, respectively). Even targets not in +the makefile may be specified, if `make' can find implicit rules that +say how to make them. + + `Make' will set the special variable `MAKECMDGOALS' to the list of +goals you specified on the command line. If no goals were given on the +command line, this variable is empty. Note that this variable should +be used only in special circumstances. + + An example of appropriate use is to avoid including `.d' files +during `clean' rules (*note Automatic Prerequisites::), so `make' won't +create them only to immediately remove them again: + + sources = foo.c bar.c + + ifneq ($(MAKECMDGOALS),clean) + include $(sources:.c=.d) + endif + + One use of specifying a goal is if you want to compile only a part of +the program, or only one of several programs. Specify as a goal each +file that you wish to remake. For example, consider a directory +containing several programs, with a makefile that starts like this: + + .PHONY: all + all: size nm ld ar as + + If you are working on the program `size', you might want to say +`make size' so that only the files of that program are recompiled. + + Another use of specifying a goal is to make files that are not +normally made. For example, there may be a file of debugging output, +or a version of the program that is compiled specially for testing, +which has a rule in the makefile but is not a prerequisite of the +default goal. + + Another use of specifying a goal is to run the recipe associated with +a phony target (*note Phony Targets::) or empty target (*note Empty +Target Files to Record Events: Empty Targets.). Many makefiles contain +a phony target named `clean' which deletes everything except source +files. Naturally, this is done only if you request it explicitly with +`make clean'. Following is a list of typical phony and empty target +names. *Note Standard Targets::, for a detailed list of all the +standard target names which GNU software packages use. + +`all' + Make all the top-level targets the makefile knows about. + +`clean' + Delete all files that are normally created by running `make'. + +`mostlyclean' + Like `clean', but may refrain from deleting a few files that people + normally don't want to recompile. For example, the `mostlyclean' + target for GCC does not delete `libgcc.a', because recompiling it + is rarely necessary and takes a lot of time. + +`distclean' +`realclean' +`clobber' + Any of these targets might be defined to delete _more_ files than + `clean' does. For example, this would delete configuration files + or links that you would normally create as preparation for + compilation, even if the makefile itself cannot create these files. + +`install' + Copy the executable file into a directory that users typically + search for commands; copy any auxiliary files that the executable + uses into the directories where it will look for them. + +`print' + Print listings of the source files that have changed. + +`tar' + Create a tar file of the source files. + +`shar' + Create a shell archive (shar file) of the source files. + +`dist' + Create a distribution file of the source files. This might be a + tar file, or a shar file, or a compressed version of one of the + above, or even more than one of the above. + +`TAGS' + Update a tags table for this program. + +`check' +`test' + Perform self tests on the program this makefile builds. + + +File: make.info, Node: Instead of Execution, Next: Avoiding Compilation, Prev: Goals, Up: Running + +9.3 Instead of Executing Recipes +================================ + +The makefile tells `make' how to tell whether a target is up to date, +and how to update each target. But updating the targets is not always +what you want. Certain options specify other activities for `make'. + +`-n' +`--just-print' +`--dry-run' +`--recon' + "No-op". The activity is to print what recipe would be used to + make the targets up to date, but not actually execute it. Some + recipes are still executed, even with this flag (*note How the + `MAKE' Variable Works: MAKE Variable.). + +`-t' +`--touch' + "Touch". The activity is to mark the targets as up to date without + actually changing them. In other words, `make' pretends to compile + the targets but does not really change their contents. + +`-q' +`--question' + "Question". The activity is to find out silently whether the + targets are up to date already; but execute no recipe in either + case. In other words, neither compilation nor output will occur. + +`-W FILE' +`--what-if=FILE' +`--assume-new=FILE' +`--new-file=FILE' + "What if". Each `-W' flag is followed by a file name. The given + files' modification times are recorded by `make' as being the + present time, although the actual modification times remain the + same. You can use the `-W' flag in conjunction with the `-n' flag + to see what would happen if you were to modify specific files. + + With the `-n' flag, `make' prints the recipe that it would normally +execute but usually does not execute it. + + With the `-t' flag, `make' ignores the recipes in the rules and uses +(in effect) the command `touch' for each target that needs to be +remade. The `touch' command is also printed, unless `-s' or `.SILENT' +is used. For speed, `make' does not actually invoke the program +`touch'. It does the work directly. + + With the `-q' flag, `make' prints nothing and executes no recipes, +but the exit status code it returns is zero if and only if the targets +to be considered are already up to date. If the exit status is one, +then some updating needs to be done. If `make' encounters an error, +the exit status is two, so you can distinguish an error from a target +that is not up to date. + + It is an error to use more than one of these three flags in the same +invocation of `make'. + + The `-n', `-t', and `-q' options do not affect recipe lines that +begin with `+' characters or contain the strings `$(MAKE)' or +`${MAKE}'. Note that only the line containing the `+' character or the +strings `$(MAKE)' or `${MAKE}' is run regardless of these options. +Other lines in the same rule are not run unless they too begin with `+' +or contain `$(MAKE)' or `${MAKE}' (*Note How the `MAKE' Variable Works: +MAKE Variable.) + + The `-t' flag prevents phony targets (*note Phony Targets::) from +being updated, unless there are recipe lines beginning with `+' or +containing `$(MAKE)' or `${MAKE}'. + + The `-W' flag provides two features: + + * If you also use the `-n' or `-q' flag, you can see what `make' + would do if you were to modify some files. + + * Without the `-n' or `-q' flag, when `make' is actually executing + recipes, the `-W' flag can direct `make' to act as if some files + had been modified, without actually running the recipes for those + files. + + Note that the options `-p' and `-v' allow you to obtain other +information about `make' or about the makefiles in use (*note Summary +of Options: Options Summary.). + + +File: make.info, Node: Avoiding Compilation, Next: Overriding, Prev: Instead of Execution, Up: Running + +9.4 Avoiding Recompilation of Some Files +======================================== + +Sometimes you may have changed a source file but you do not want to +recompile all the files that depend on it. For example, suppose you add +a macro or a declaration to a header file that many other files depend +on. Being conservative, `make' assumes that any change in the header +file requires recompilation of all dependent files, but you know that +they do not need to be recompiled and you would rather not waste the +time waiting for them to compile. + + If you anticipate the problem before changing the header file, you +can use the `-t' flag. This flag tells `make' not to run the recipes +in the rules, but rather to mark the target up to date by changing its +last-modification date. You would follow this procedure: + + 1. Use the command `make' to recompile the source files that really + need recompilation, ensuring that the object files are up-to-date + before you begin. + + 2. Make the changes in the header files. + + 3. Use the command `make -t' to mark all the object files as up to + date. The next time you run `make', the changes in the header + files will not cause any recompilation. + + If you have already changed the header file at a time when some files +do need recompilation, it is too late to do this. Instead, you can use +the `-o FILE' flag, which marks a specified file as "old" (*note +Summary of Options: Options Summary.). This means that the file itself +will not be remade, and nothing else will be remade on its account. +Follow this procedure: + + 1. Recompile the source files that need compilation for reasons + independent of the particular header file, with `make -o + HEADERFILE'. If several header files are involved, use a separate + `-o' option for each header file. + + 2. Touch all the object files with `make -t'. + + +File: make.info, Node: Overriding, Next: Testing, Prev: Avoiding Compilation, Up: Running + +9.5 Overriding Variables +======================== + +An argument that contains `=' specifies the value of a variable: `V=X' +sets the value of the variable V to X. If you specify a value in this +way, all ordinary assignments of the same variable in the makefile are +ignored; we say they have been "overridden" by the command line +argument. + + The most common way to use this facility is to pass extra flags to +compilers. For example, in a properly written makefile, the variable +`CFLAGS' is included in each recipe that runs the C compiler, so a file +`foo.c' would be compiled something like this: + + cc -c $(CFLAGS) foo.c + + Thus, whatever value you set for `CFLAGS' affects each compilation +that occurs. The makefile probably specifies the usual value for +`CFLAGS', like this: + + CFLAGS=-g + + Each time you run `make', you can override this value if you wish. +For example, if you say `make CFLAGS='-g -O'', each C compilation will +be done with `cc -c -g -O'. (This also illustrates how you can use +quoting in the shell to enclose spaces and other special characters in +the value of a variable when you override it.) + + The variable `CFLAGS' is only one of many standard variables that +exist just so that you can change them this way. *Note Variables Used +by Implicit Rules: Implicit Variables, for a complete list. + + You can also program the makefile to look at additional variables of +your own, giving the user the ability to control other aspects of how +the makefile works by changing the variables. + + When you override a variable with a command line argument, you can +define either a recursively-expanded variable or a simply-expanded +variable. The examples shown above make a recursively-expanded +variable; to make a simply-expanded variable, write `:=' instead of +`='. But, unless you want to include a variable reference or function +call in the _value_ that you specify, it makes no difference which kind +of variable you create. + + There is one way that the makefile can change a variable that you +have overridden. This is to use the `override' directive, which is a +line that looks like this: `override VARIABLE = VALUE' (*note The +`override' Directive: Override Directive.). + + +File: make.info, Node: Testing, Next: Options Summary, Prev: Overriding, Up: Running + +9.6 Testing the Compilation of a Program +======================================== + +Normally, when an error happens in executing a shell command, `make' +gives up immediately, returning a nonzero status. No further recipes +are executed for any target. The error implies that the goal cannot be +correctly remade, and `make' reports this as soon as it knows. + + When you are compiling a program that you have just changed, this is +not what you want. Instead, you would rather that `make' try compiling +every file that can be tried, to show you as many compilation errors as +possible. + + On these occasions, you should use the `-k' or `--keep-going' flag. +This tells `make' to continue to consider the other prerequisites of +the pending targets, remaking them if necessary, before it gives up and +returns nonzero status. For example, after an error in compiling one +object file, `make -k' will continue compiling other object files even +though it already knows that linking them will be impossible. In +addition to continuing after failed shell commands, `make -k' will +continue as much as possible after discovering that it does not know +how to make a target or prerequisite file. This will always cause an +error message, but without `-k', it is a fatal error (*note Summary of +Options: Options Summary.). + + The usual behavior of `make' assumes that your purpose is to get the +goals up to date; once `make' learns that this is impossible, it might +as well report the failure immediately. The `-k' flag says that the +real purpose is to test as much as possible of the changes made in the +program, perhaps to find several independent problems so that you can +correct them all before the next attempt to compile. This is why Emacs' +`M-x compile' command passes the `-k' flag by default. + + +File: make.info, Node: Options Summary, Prev: Testing, Up: Running + +9.7 Summary of Options +====================== + +Here is a table of all the options `make' understands: + +`-b' +`-m' + These options are ignored for compatibility with other versions of + `make'. + +`-B' +`--always-make' + Consider all targets out-of-date. GNU `make' proceeds to consider + targets and their prerequisites using the normal algorithms; + however, all targets so considered are always remade regardless of + the status of their prerequisites. To avoid infinite recursion, if + `MAKE_RESTARTS' (*note Other Special Variables: Special + Variables.) is set to a number greater than 0 this option is + disabled when considering whether to remake makefiles (*note How + Makefiles Are Remade: Remaking Makefiles.). + +`-C DIR' +`--directory=DIR' + Change to directory DIR before reading the makefiles. If multiple + `-C' options are specified, each is interpreted relative to the + previous one: `-C / -C etc' is equivalent to `-C /etc'. This is + typically used with recursive invocations of `make' (*note + Recursive Use of `make': Recursion.). + +`-d' + Print debugging information in addition to normal processing. The + debugging information says which files are being considered for + remaking, which file-times are being compared and with what + results, which files actually need to be remade, which implicit + rules are considered and which are applied--everything interesting + about how `make' decides what to do. The `-d' option is + equivalent to `--debug=a' (see below). + +`--debug[=OPTIONS]' + Print debugging information in addition to normal processing. + Various levels and types of output can be chosen. With no + arguments, print the "basic" level of debugging. Possible + arguments are below; only the first character is considered, and + values must be comma- or space-separated. + + `a (all)' + All types of debugging output are enabled. This is + equivalent to using `-d'. + + `b (basic)' + Basic debugging prints each target that was found to be + out-of-date, and whether the build was successful or not. + + `v (verbose)' + A level above `basic'; includes messages about which + makefiles were parsed, prerequisites that did not need to be + rebuilt, etc. This option also enables `basic' messages. + + `i (implicit)' + Prints messages describing the implicit rule searches for + each target. This option also enables `basic' messages. + + `j (jobs)' + Prints messages giving details on the invocation of specific + subcommands. + + `m (makefile)' + By default, the above messages are not enabled while trying + to remake the makefiles. This option enables messages while + rebuilding makefiles, too. Note that the `all' option does + enable this option. This option also enables `basic' + messages. + +`-e' +`--environment-overrides' + Give variables taken from the environment precedence over + variables from makefiles. *Note Variables from the Environment: + Environment. + +`--eval=STRING' + Evaluate STRING as makefile syntax. This is a command-line + version of the `eval' function (*note Eval Function::). The + evaluation is performed after the default rules and variables have + been defined, but before any makefiles are read. + +`-f FILE' +`--file=FILE' +`--makefile=FILE' + Read the file named FILE as a makefile. *Note Writing Makefiles: + Makefiles. + +`-h' +`--help' + Remind you of the options that `make' understands and then exit. + +`-i' +`--ignore-errors' + Ignore all errors in recipes executed to remake files. *Note + Errors in Recipes: Errors. + +`-I DIR' +`--include-dir=DIR' + Specifies a directory DIR to search for included makefiles. *Note + Including Other Makefiles: Include. If several `-I' options are + used to specify several directories, the directories are searched + in the order specified. + +`-j [JOBS]' +`--jobs[=JOBS]' + Specifies the number of recipes (jobs) to run simultaneously. + With no argument, `make' runs as many recipes simultaneously as + possible. If there is more than one `-j' option, the last one is + effective. *Note Parallel Execution: Parallel, for more + information on how recipes are run. Note that this option is + ignored on MS-DOS. + +`-k' +`--keep-going' + Continue as much as possible after an error. While the target that + failed, and those that depend on it, cannot be remade, the other + prerequisites of these targets can be processed all the same. + *Note Testing the Compilation of a Program: Testing. + +`-l [LOAD]' +`--load-average[=LOAD]' +`--max-load[=LOAD]' + Specifies that no new recipes should be started if there are other + recipes running and the load average is at least LOAD (a + floating-point number). With no argument, removes a previous load + limit. *Note Parallel Execution: Parallel. + +`-L' +`--check-symlink-times' + On systems that support symbolic links, this option causes `make' + to consider the timestamps on any symbolic links in addition to the + timestamp on the file referenced by those links. When this option + is provided, the most recent timestamp among the file and the + symbolic links is taken as the modification time for this target + file. + +`-n' +`--just-print' +`--dry-run' +`--recon' + Print the recipe that would be executed, but do not execute it + (except in certain circumstances). *Note Instead of Executing + Recipes: Instead of Execution. + +`-o FILE' +`--old-file=FILE' +`--assume-old=FILE' + Do not remake the file FILE even if it is older than its + prerequisites, and do not remake anything on account of changes in + FILE. Essentially the file is treated as very old and its rules + are ignored. *Note Avoiding Recompilation of Some Files: Avoiding + Compilation. + +`-p' +`--print-data-base' + Print the data base (rules and variable values) that results from + reading the makefiles; then execute as usual or as otherwise + specified. This also prints the version information given by the + `-v' switch (see below). To print the data base without trying to + remake any files, use `make -qp'. To print the data base of + predefined rules and variables, use `make -p -f /dev/null'. The + data base output contains filename and linenumber information for + recipe and variable definitions, so it can be a useful debugging + tool in complex environments. + +`-q' +`--question' + "Question mode". Do not run any recipes, or print anything; just + return an exit status that is zero if the specified targets are + already up to date, one if any remaking is required, or two if an + error is encountered. *Note Instead of Executing Recipes: Instead + of Execution. + +`-r' +`--no-builtin-rules' + Eliminate use of the built-in implicit rules (*note Using Implicit + Rules: Implicit Rules.). You can still define your own by writing + pattern rules (*note Defining and Redefining Pattern Rules: + Pattern Rules.). The `-r' option also clears out the default list + of suffixes for suffix rules (*note Old-Fashioned Suffix Rules: + Suffix Rules.). But you can still define your own suffixes with a + rule for `.SUFFIXES', and then define your own suffix rules. Note + that only _rules_ are affected by the `-r' option; default + variables remain in effect (*note Variables Used by Implicit + Rules: Implicit Variables.); see the `-R' option below. + +`-R' +`--no-builtin-variables' + Eliminate use of the built-in rule-specific variables (*note + Variables Used by Implicit Rules: Implicit Variables.). You can + still define your own, of course. The `-R' option also + automatically enables the `-r' option (see above), since it + doesn't make sense to have implicit rules without any definitions + for the variables that they use. + +`-s' +`--silent' +`--quiet' + Silent operation; do not print the recipes as they are executed. + *Note Recipe Echoing: Echoing. + +`-S' +`--no-keep-going' +`--stop' + Cancel the effect of the `-k' option. This is never necessary + except in a recursive `make' where `-k' might be inherited from + the top-level `make' via `MAKEFLAGS' (*note Recursive Use of + `make': Recursion.) or if you set `-k' in `MAKEFLAGS' in your + environment. + +`-t' +`--touch' + Touch files (mark them up to date without really changing them) + instead of running their recipes. This is used to pretend that the + recipes were done, in order to fool future invocations of `make'. + *Note Instead of Executing Recipes: Instead of Execution. + +`-v' +`--version' + Print the version of the `make' program plus a copyright, a list + of authors, and a notice that there is no warranty; then exit. + +`-w' +`--print-directory' + Print a message containing the working directory both before and + after executing the makefile. This may be useful for tracking + down errors from complicated nests of recursive `make' commands. + *Note Recursive Use of `make': Recursion. (In practice, you + rarely need to specify this option since `make' does it for you; + see *note The `--print-directory' Option: -w Option.) + +`--no-print-directory' + Disable printing of the working directory under `-w'. This option + is useful when `-w' is turned on automatically, but you do not + want to see the extra messages. *Note The `--print-directory' + Option: -w Option. + +`-W FILE' +`--what-if=FILE' +`--new-file=FILE' +`--assume-new=FILE' + Pretend that the target FILE has just been modified. When used + with the `-n' flag, this shows you what would happen if you were + to modify that file. Without `-n', it is almost the same as + running a `touch' command on the given file before running `make', + except that the modification time is changed only in the + imagination of `make'. *Note Instead of Executing Recipes: + Instead of Execution. + +`--warn-undefined-variables' + Issue a warning message whenever `make' sees a reference to an + undefined variable. This can be helpful when you are trying to + debug makefiles which use variables in complex ways. + + +File: make.info, Node: Implicit Rules, Next: Archives, Prev: Running, Up: Top + +10 Using Implicit Rules +*********************** + +Certain standard ways of remaking target files are used very often. For +example, one customary way to make an object file is from a C source +file using the C compiler, `cc'. + + "Implicit rules" tell `make' how to use customary techniques so that +you do not have to specify them in detail when you want to use them. +For example, there is an implicit rule for C compilation. File names +determine which implicit rules are run. For example, C compilation +typically takes a `.c' file and makes a `.o' file. So `make' applies +the implicit rule for C compilation when it sees this combination of +file name endings. + + A chain of implicit rules can apply in sequence; for example, `make' +will remake a `.o' file from a `.y' file by way of a `.c' file. + + The built-in implicit rules use several variables in their recipes so +that, by changing the values of the variables, you can change the way +the implicit rule works. For example, the variable `CFLAGS' controls +the flags given to the C compiler by the implicit rule for C +compilation. + + You can define your own implicit rules by writing "pattern rules". + + "Suffix rules" are a more limited way to define implicit rules. +Pattern rules are more general and clearer, but suffix rules are +retained for compatibility. + +* Menu: + +* Using Implicit:: How to use an existing implicit rule + to get the recipes for updating a file. +* Catalogue of Rules:: A list of built-in implicit rules. +* Implicit Variables:: How to change what predefined rules do. +* Chained Rules:: How to use a chain of implicit rules. +* Pattern Rules:: How to define new implicit rules. +* Last Resort:: How to define recipes for rules which + cannot find any. +* Suffix Rules:: The old-fashioned style of implicit rule. +* Implicit Rule Search:: The precise algorithm for applying + implicit rules. + + +File: make.info, Node: Using Implicit, Next: Catalogue of Rules, Prev: Implicit Rules, Up: Implicit Rules + +10.1 Using Implicit Rules +========================= + +To allow `make' to find a customary method for updating a target file, +all you have to do is refrain from specifying recipes yourself. Either +write a rule with no recipe, or don't write a rule at all. Then `make' +will figure out which implicit rule to use based on which kind of +source file exists or can be made. + + For example, suppose the makefile looks like this: + + foo : foo.o bar.o + cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) + +Because you mention `foo.o' but do not give a rule for it, `make' will +automatically look for an implicit rule that tells how to update it. +This happens whether or not the file `foo.o' currently exists. + + If an implicit rule is found, it can supply both a recipe and one or +more prerequisites (the source files). You would want to write a rule +for `foo.o' with no recipe if you need to specify additional +prerequisites, such as header files, that the implicit rule cannot +supply. + + Each implicit rule has a target pattern and prerequisite patterns. +There may be many implicit rules with the same target pattern. For +example, numerous rules make `.o' files: one, from a `.c' file with the +C compiler; another, from a `.p' file with the Pascal compiler; and so +on. The rule that actually applies is the one whose prerequisites +exist or can be made. So, if you have a file `foo.c', `make' will run +the C compiler; otherwise, if you have a file `foo.p', `make' will run +the Pascal compiler; and so on. + + Of course, when you write the makefile, you know which implicit rule +you want `make' to use, and you know it will choose that one because you +know which possible prerequisite files are supposed to exist. *Note +Catalogue of Implicit Rules: Catalogue of Rules, for a catalogue of all +the predefined implicit rules. + + Above, we said an implicit rule applies if the required +prerequisites "exist or can be made". A file "can be made" if it is +mentioned explicitly in the makefile as a target or a prerequisite, or +if an implicit rule can be recursively found for how to make it. When +an implicit prerequisite is the result of another implicit rule, we say +that "chaining" is occurring. *Note Chains of Implicit Rules: Chained +Rules. + + In general, `make' searches for an implicit rule for each target, and +for each double-colon rule, that has no recipe. A file that is +mentioned only as a prerequisite is considered a target whose rule +specifies nothing, so implicit rule search happens for it. *Note +Implicit Rule Search Algorithm: Implicit Rule Search, for the details +of how the search is done. + + Note that explicit prerequisites do not influence implicit rule +search. For example, consider this explicit rule: + + foo.o: foo.p + +The prerequisite on `foo.p' does not necessarily mean that `make' will +remake `foo.o' according to the implicit rule to make an object file, a +`.o' file, from a Pascal source file, a `.p' file. For example, if +`foo.c' also exists, the implicit rule to make an object file from a C +source file is used instead, because it appears before the Pascal rule +in the list of predefined implicit rules (*note Catalogue of Implicit +Rules: Catalogue of Rules.). + + If you do not want an implicit rule to be used for a target that has +no recipe, you can give that target an empty recipe by writing a +semicolon (*note Defining Empty Recipes: Empty Recipes.). + diff --git a/doc/make.info-2 b/doc/make.info-2 new file mode 100644 index 0000000..cd95ff0 --- /dev/null +++ b/doc/make.info-2 @@ -0,0 +1,5053 @@ +This is make.info, produced by makeinfo version 4.13 from make.texi. + +This file documents the GNU `make' utility, which determines +automatically which pieces of a large program need to be recompiled, +and issues the commands to recompile them. + + This is Edition 0.71, last updated 19 July 2010, of `The GNU Make +Manual', for GNU `make' version 3.82. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover Texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Make: (make). Remake files automatically. +END-INFO-DIR-ENTRY + + +File: make.info, Node: Catalogue of Rules, Next: Implicit Variables, Prev: Using Implicit, Up: Implicit Rules + +10.2 Catalogue of Implicit Rules +================================ + +Here is a catalogue of predefined implicit rules which are always +available unless the makefile explicitly overrides or cancels them. +*Note Canceling Implicit Rules: Canceling Rules, for information on +canceling or overriding an implicit rule. The `-r' or +`--no-builtin-rules' option cancels all predefined rules. + + This manual only documents the default rules available on POSIX-based +operating systems. Other operating systems, such as VMS, Windows, +OS/2, etc. may have different sets of default rules. To see the full +list of default rules and variables available in your version of GNU +`make', run `make -p' in a directory with no makefile. + + Not all of these rules will always be defined, even when the `-r' +option is not given. Many of the predefined implicit rules are +implemented in `make' as suffix rules, so which ones will be defined +depends on the "suffix list" (the list of prerequisites of the special +target `.SUFFIXES'). The default suffix list is: `.out', `.a', `.ln', +`.o', `.c', `.cc', `.C', `.cpp', `.p', `.f', `.F', `.m', `.r', `.y', +`.l', `.ym', `.lm', `.s', `.S', `.mod', `.sym', `.def', `.h', `.info', +`.dvi', `.tex', `.texinfo', `.texi', `.txinfo', `.w', `.ch' `.web', +`.sh', `.elc', `.el'. All of the implicit rules described below whose +prerequisites have one of these suffixes are actually suffix rules. If +you modify the suffix list, the only predefined suffix rules in effect +will be those named by one or two of the suffixes that are on the list +you specify; rules whose suffixes fail to be on the list are disabled. +*Note Old-Fashioned Suffix Rules: Suffix Rules, for full details on +suffix rules. + +Compiling C programs + `N.o' is made automatically from `N.c' with a recipe of the form + `$(CC) $(CPPFLAGS) $(CFLAGS) -c'. + +Compiling C++ programs + `N.o' is made automatically from `N.cc', `N.cpp', or `N.C' with a + recipe of the form `$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c'. We + encourage you to use the suffix `.cc' for C++ source files instead + of `.C'. + +Compiling Pascal programs + `N.o' is made automatically from `N.p' with the recipe `$(PC) + $(PFLAGS) -c'. + +Compiling Fortran and Ratfor programs + `N.o' is made automatically from `N.r', `N.F' or `N.f' by running + the Fortran compiler. The precise recipe used is as follows: + + `.f' + `$(FC) $(FFLAGS) -c'. + + `.F' + `$(FC) $(FFLAGS) $(CPPFLAGS) -c'. + + `.r' + `$(FC) $(FFLAGS) $(RFLAGS) -c'. + +Preprocessing Fortran and Ratfor programs + `N.f' is made automatically from `N.r' or `N.F'. This rule runs + just the preprocessor to convert a Ratfor or preprocessable + Fortran program into a strict Fortran program. The precise recipe + used is as follows: + + `.F' + `$(FC) $(CPPFLAGS) $(FFLAGS) -F'. + + `.r' + `$(FC) $(FFLAGS) $(RFLAGS) -F'. + +Compiling Modula-2 programs + `N.sym' is made from `N.def' with a recipe of the form `$(M2C) + $(M2FLAGS) $(DEFFLAGS)'. `N.o' is made from `N.mod'; the form is: + `$(M2C) $(M2FLAGS) $(MODFLAGS)'. + +Assembling and preprocessing assembler programs + `N.o' is made automatically from `N.s' by running the assembler, + `as'. The precise recipe is `$(AS) $(ASFLAGS)'. + + `N.s' is made automatically from `N.S' by running the C + preprocessor, `cpp'. The precise recipe is `$(CPP) $(CPPFLAGS)'. + +Linking a single object file + `N' is made automatically from `N.o' by running the linker + (usually called `ld') via the C compiler. The precise recipe used + is `$(CC) $(LDFLAGS) N.o $(LOADLIBES) $(LDLIBS)'. + + This rule does the right thing for a simple program with only one + source file. It will also do the right thing if there are multiple + object files (presumably coming from various other source files), + one of which has a name matching that of the executable file. + Thus, + + x: y.o z.o + + when `x.c', `y.c' and `z.c' all exist will execute: + + cc -c x.c -o x.o + cc -c y.c -o y.o + cc -c z.c -o z.o + cc x.o y.o z.o -o x + rm -f x.o + rm -f y.o + rm -f z.o + + In more complicated cases, such as when there is no object file + whose name derives from the executable file name, you must write + an explicit recipe for linking. + + Each kind of file automatically made into `.o' object files will + be automatically linked by using the compiler (`$(CC)', `$(FC)' or + `$(PC)'; the C compiler `$(CC)' is used to assemble `.s' files) + without the `-c' option. This could be done by using the `.o' + object files as intermediates, but it is faster to do the + compiling and linking in one step, so that's how it's done. + +Yacc for C programs + `N.c' is made automatically from `N.y' by running Yacc with the + recipe `$(YACC) $(YFLAGS)'. + +Lex for C programs + `N.c' is made automatically from `N.l' by running Lex. The actual + recipe is `$(LEX) $(LFLAGS)'. + +Lex for Ratfor programs + `N.r' is made automatically from `N.l' by running Lex. The actual + recipe is `$(LEX) $(LFLAGS)'. + + The convention of using the same suffix `.l' for all Lex files + regardless of whether they produce C code or Ratfor code makes it + impossible for `make' to determine automatically which of the two + languages you are using in any particular case. If `make' is + called upon to remake an object file from a `.l' file, it must + guess which compiler to use. It will guess the C compiler, because + that is more common. If you are using Ratfor, make sure `make' + knows this by mentioning `N.r' in the makefile. Or, if you are + using Ratfor exclusively, with no C files, remove `.c' from the + list of implicit rule suffixes with: + + .SUFFIXES: + .SUFFIXES: .o .r .f .l ... + +Making Lint Libraries from C, Yacc, or Lex programs + `N.ln' is made from `N.c' by running `lint'. The precise recipe + is `$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i'. The same recipe is used + on the C code produced from `N.y' or `N.l'. + +TeX and Web + `N.dvi' is made from `N.tex' with the recipe `$(TEX)'. `N.tex' is + made from `N.web' with `$(WEAVE)', or from `N.w' (and from `N.ch' + if it exists or can be made) with `$(CWEAVE)'. `N.p' is made from + `N.web' with `$(TANGLE)' and `N.c' is made from `N.w' (and from + `N.ch' if it exists or can be made) with `$(CTANGLE)'. + +Texinfo and Info + `N.dvi' is made from `N.texinfo', `N.texi', or `N.txinfo', with + the recipe `$(TEXI2DVI) $(TEXI2DVI_FLAGS)'. `N.info' is made from + `N.texinfo', `N.texi', or `N.txinfo', with the recipe + `$(MAKEINFO) $(MAKEINFO_FLAGS)'. + +RCS + Any file `N' is extracted if necessary from an RCS file named + either `N,v' or `RCS/N,v'. The precise recipe used is + `$(CO) $(COFLAGS)'. `N' will not be extracted from RCS if it + already exists, even if the RCS file is newer. The rules for RCS + are terminal (*note Match-Anything Pattern Rules: Match-Anything + Rules.), so RCS files cannot be generated from another source; + they must actually exist. + +SCCS + Any file `N' is extracted if necessary from an SCCS file named + either `s.N' or `SCCS/s.N'. The precise recipe used is + `$(GET) $(GFLAGS)'. The rules for SCCS are terminal (*note + Match-Anything Pattern Rules: Match-Anything Rules.), so SCCS + files cannot be generated from another source; they must actually + exist. + + For the benefit of SCCS, a file `N' is copied from `N.sh' and made + executable (by everyone). This is for shell scripts that are + checked into SCCS. Since RCS preserves the execution permission + of a file, you do not need to use this feature with RCS. + + We recommend that you avoid using of SCCS. RCS is widely held to + be superior, and is also free. By choosing free software in place + of comparable (or inferior) proprietary software, you support the + free software movement. + + Usually, you want to change only the variables listed in the table +above, which are documented in the following section. + + However, the recipes in built-in implicit rules actually use +variables such as `COMPILE.c', `LINK.p', and `PREPROCESS.S', whose +values contain the recipes listed above. + + `make' follows the convention that the rule to compile a `.X' source +file uses the variable `COMPILE.X'. Similarly, the rule to produce an +executable from a `.X' file uses `LINK.X'; and the rule to preprocess a +`.X' file uses `PREPROCESS.X'. + + Every rule that produces an object file uses the variable +`OUTPUT_OPTION'. `make' defines this variable either to contain `-o +$@', or to be empty, depending on a compile-time option. You need the +`-o' option to ensure that the output goes into the right file when the +source file is in a different directory, as when using `VPATH' (*note +Directory Search::). However, compilers on some systems do not accept +a `-o' switch for object files. If you use such a system, and use +`VPATH', some compilations will put their output in the wrong place. A +possible workaround for this problem is to give `OUTPUT_OPTION' the +value `; mv $*.o $@'. + + +File: make.info, Node: Implicit Variables, Next: Chained Rules, Prev: Catalogue of Rules, Up: Implicit Rules + +10.3 Variables Used by Implicit Rules +===================================== + +The recipes in built-in implicit rules make liberal use of certain +predefined variables. You can alter the values of these variables in +the makefile, with arguments to `make', or in the environment to alter +how the implicit rules work without redefining the rules themselves. +You can cancel all variables used by implicit rules with the `-R' or +`--no-builtin-variables' option. + + For example, the recipe used to compile a C source file actually says +`$(CC) -c $(CFLAGS) $(CPPFLAGS)'. The default values of the variables +used are `cc' and nothing, resulting in the command `cc -c'. By +redefining `CC' to `ncc', you could cause `ncc' to be used for all C +compilations performed by the implicit rule. By redefining `CFLAGS' to +be `-g', you could pass the `-g' option to each compilation. _All_ +implicit rules that do C compilation use `$(CC)' to get the program +name for the compiler and _all_ include `$(CFLAGS)' among the arguments +given to the compiler. + + The variables used in implicit rules fall into two classes: those +that are names of programs (like `CC') and those that contain arguments +for the programs (like `CFLAGS'). (The "name of a program" may also +contain some command arguments, but it must start with an actual +executable program name.) If a variable value contains more than one +argument, separate them with spaces. + + The following tables describe of some of the more commonly-used +predefined variables. This list is not exhaustive, and the default +values shown here may not be what `make' selects for your environment. +To see the complete list of predefined variables for your instance of +GNU `make' you can run `make -p' in a directory with no makefiles. + + Here is a table of some of the more common variables used as names of +programs in built-in rules: makefiles. + +`AR' + Archive-maintaining program; default `ar'. + +`AS' + Program for compiling assembly files; default `as'. + +`CC' + Program for compiling C programs; default `cc'. + +`CXX' + Program for compiling C++ programs; default `g++'. + +`CPP' + Program for running the C preprocessor, with results to standard + output; default `$(CC) -E'. + +`FC' + Program for compiling or preprocessing Fortran and Ratfor programs; + default `f77'. + +`M2C' + Program to use to compile Modula-2 source code; default `m2c'. + +`PC' + Program for compiling Pascal programs; default `pc'. + +`CO' + Program for extracting a file from RCS; default `co'. + +`GET' + Program for extracting a file from SCCS; default `get'. + +`LEX' + Program to use to turn Lex grammars into source code; default + `lex'. + +`YACC' + Program to use to turn Yacc grammars into source code; default + `yacc'. + +`LINT' + Program to use to run lint on source code; default `lint'. + +`MAKEINFO' + Program to convert a Texinfo source file into an Info file; default + `makeinfo'. + +`TEX' + Program to make TeX DVI files from TeX source; default `tex'. + +`TEXI2DVI' + Program to make TeX DVI files from Texinfo source; default + `texi2dvi'. + +`WEAVE' + Program to translate Web into TeX; default `weave'. + +`CWEAVE' + Program to translate C Web into TeX; default `cweave'. + +`TANGLE' + Program to translate Web into Pascal; default `tangle'. + +`CTANGLE' + Program to translate C Web into C; default `ctangle'. + +`RM' + Command to remove a file; default `rm -f'. + + Here is a table of variables whose values are additional arguments +for the programs above. The default values for all of these is the +empty string, unless otherwise noted. + +`ARFLAGS' + Flags to give the archive-maintaining program; default `rv'. + +`ASFLAGS' + Extra flags to give to the assembler (when explicitly invoked on a + `.s' or `.S' file). + +`CFLAGS' + Extra flags to give to the C compiler. + +`CXXFLAGS' + Extra flags to give to the C++ compiler. + +`COFLAGS' + Extra flags to give to the RCS `co' program. + +`CPPFLAGS' + Extra flags to give to the C preprocessor and programs that use it + (the C and Fortran compilers). + +`FFLAGS' + Extra flags to give to the Fortran compiler. + +`GFLAGS' + Extra flags to give to the SCCS `get' program. + +`LDFLAGS' + Extra flags to give to compilers when they are supposed to invoke + the linker, `ld'. + +`LFLAGS' + Extra flags to give to Lex. + +`YFLAGS' + Extra flags to give to Yacc. + +`PFLAGS' + Extra flags to give to the Pascal compiler. + +`RFLAGS' + Extra flags to give to the Fortran compiler for Ratfor programs. + +`LINTFLAGS' + Extra flags to give to lint. + + +File: make.info, Node: Chained Rules, Next: Pattern Rules, Prev: Implicit Variables, Up: Implicit Rules + +10.4 Chains of Implicit Rules +============================= + +Sometimes a file can be made by a sequence of implicit rules. For +example, a file `N.o' could be made from `N.y' by running first Yacc +and then `cc'. Such a sequence is called a "chain". + + If the file `N.c' exists, or is mentioned in the makefile, no +special searching is required: `make' finds that the object file can be +made by C compilation from `N.c'; later on, when considering how to +make `N.c', the rule for running Yacc is used. Ultimately both `N.c' +and `N.o' are updated. + + However, even if `N.c' does not exist and is not mentioned, `make' +knows how to envision it as the missing link between `N.o' and `N.y'! +In this case, `N.c' is called an "intermediate file". Once `make' has +decided to use the intermediate file, it is entered in the data base as +if it had been mentioned in the makefile, along with the implicit rule +that says how to create it. + + Intermediate files are remade using their rules just like all other +files. But intermediate files are treated differently in two ways. + + The first difference is what happens if the intermediate file does +not exist. If an ordinary file B does not exist, and `make' considers +a target that depends on B, it invariably creates B and then updates +the target from B. But if B is an intermediate file, then `make' can +leave well enough alone. It won't bother updating B, or the ultimate +target, unless some prerequisite of B is newer than that target or +there is some other reason to update that target. + + The second difference is that if `make' _does_ create B in order to +update something else, it deletes B later on after it is no longer +needed. Therefore, an intermediate file which did not exist before +`make' also does not exist after `make'. `make' reports the deletion +to you by printing a `rm -f' command showing which file it is deleting. + + Ordinarily, a file cannot be intermediate if it is mentioned in the +makefile as a target or prerequisite. However, you can explicitly mark +a file as intermediate by listing it as a prerequisite of the special +target `.INTERMEDIATE'. This takes effect even if the file is mentioned +explicitly in some other way. + + You can prevent automatic deletion of an intermediate file by +marking it as a "secondary" file. To do this, list it as a +prerequisite of the special target `.SECONDARY'. When a file is +secondary, `make' will not create the file merely because it does not +already exist, but `make' does not automatically delete the file. +Marking a file as secondary also marks it as intermediate. + + You can list the target pattern of an implicit rule (such as `%.o') +as a prerequisite of the special target `.PRECIOUS' to preserve +intermediate files made by implicit rules whose target patterns match +that file's name; see *note Interrupts::. + + A chain can involve more than two implicit rules. For example, it is +possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc +and `cc'. Then both `foo.y' and `foo.c' are intermediate files that +are deleted at the end. + + No single implicit rule can appear more than once in a chain. This +means that `make' will not even consider such a ridiculous thing as +making `foo' from `foo.o.o' by running the linker twice. This +constraint has the added benefit of preventing any infinite loop in the +search for an implicit rule chain. + + There are some special implicit rules to optimize certain cases that +would otherwise be handled by rule chains. For example, making `foo' +from `foo.c' could be handled by compiling and linking with separate +chained rules, using `foo.o' as an intermediate file. But what +actually happens is that a special rule for this case does the +compilation and linking with a single `cc' command. The optimized rule +is used in preference to the step-by-step chain because it comes +earlier in the ordering of rules. + + +File: make.info, Node: Pattern Rules, Next: Last Resort, Prev: Chained Rules, Up: Implicit Rules + +10.5 Defining and Redefining Pattern Rules +========================================== + +You define an implicit rule by writing a "pattern rule". A pattern +rule looks like an ordinary rule, except that its target contains the +character `%' (exactly one of them). The target is considered a +pattern for matching file names; the `%' can match any nonempty +substring, while other characters match only themselves. The +prerequisites likewise use `%' to show how their names relate to the +target name. + + Thus, a pattern rule `%.o : %.c' says how to make any file `STEM.o' +from another file `STEM.c'. + + Note that expansion using `%' in pattern rules occurs *after* any +variable or function expansions, which take place when the makefile is +read. *Note How to Use Variables: Using Variables, and *note Functions +for Transforming Text: Functions. + +* Menu: + +* Pattern Intro:: An introduction to pattern rules. +* Pattern Examples:: Examples of pattern rules. +* Automatic Variables:: How to use automatic variables in the + recipes of implicit rules. +* Pattern Match:: How patterns match. +* Match-Anything Rules:: Precautions you should take prior to + defining rules that can match any + target file whatever. +* Canceling Rules:: How to override or cancel built-in rules. + + +File: make.info, Node: Pattern Intro, Next: Pattern Examples, Prev: Pattern Rules, Up: Pattern Rules + +10.5.1 Introduction to Pattern Rules +------------------------------------ + +A pattern rule contains the character `%' (exactly one of them) in the +target; otherwise, it looks exactly like an ordinary rule. The target +is a pattern for matching file names; the `%' matches any nonempty +substring, while other characters match only themselves. + + For example, `%.c' as a pattern matches any file name that ends in +`.c'. `s.%.c' as a pattern matches any file name that starts with +`s.', ends in `.c' and is at least five characters long. (There must +be at least one character to match the `%'.) The substring that the +`%' matches is called the "stem". + + `%' in a prerequisite of a pattern rule stands for the same stem +that was matched by the `%' in the target. In order for the pattern +rule to apply, its target pattern must match the file name under +consideration and all of its prerequisites (after pattern substitution) +must name files that exist or can be made. These files become +prerequisites of the target. + + Thus, a rule of the form + + %.o : %.c ; RECIPE... + +specifies how to make a file `N.o', with another file `N.c' as its +prerequisite, provided that `N.c' exists or can be made. + + There may also be prerequisites that do not use `%'; such a +prerequisite attaches to every file made by this pattern rule. These +unvarying prerequisites are useful occasionally. + + A pattern rule need not have any prerequisites that contain `%', or +in fact any prerequisites at all. Such a rule is effectively a general +wildcard. It provides a way to make any file that matches the target +pattern. *Note Last Resort::. + + More than one pattern rule may match a target. In this case `make' +will choose the "best fit" rule. *Note How Patterns Match: Pattern +Match. + + Pattern rules may have more than one target. Unlike normal rules, +this does not act as many different rules with the same prerequisites +and recipe. If a pattern rule has multiple targets, `make' knows that +the rule's recipe is responsible for making all of the targets. The +recipe is executed only once to make all the targets. When searching +for a pattern rule to match a target, the target patterns of a rule +other than the one that matches the target in need of a rule are +incidental: `make' worries only about giving a recipe and prerequisites +to the file presently in question. However, when this file's recipe is +run, the other targets are marked as having been updated themselves. + + +File: make.info, Node: Pattern Examples, Next: Automatic Variables, Prev: Pattern Intro, Up: Pattern Rules + +10.5.2 Pattern Rule Examples +---------------------------- + +Here are some examples of pattern rules actually predefined in `make'. +First, the rule that compiles `.c' files into `.o' files: + + %.o : %.c + $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@ + +defines a rule that can make any file `X.o' from `X.c'. The recipe +uses the automatic variables `$@' and `$<' to substitute the names of +the target file and the source file in each case where the rule applies +(*note Automatic Variables::). + + Here is a second built-in rule: + + % :: RCS/%,v + $(CO) $(COFLAGS) $< + +defines a rule that can make any file `X' whatsoever from a +corresponding file `X,v' in the subdirectory `RCS'. Since the target +is `%', this rule will apply to any file whatever, provided the +appropriate prerequisite file exists. The double colon makes the rule +"terminal", which means that its prerequisite may not be an intermediate +file (*note Match-Anything Pattern Rules: Match-Anything Rules.). + + This pattern rule has two targets: + + %.tab.c %.tab.h: %.y + bison -d $< + +This tells `make' that the recipe `bison -d X.y' will make both +`X.tab.c' and `X.tab.h'. If the file `foo' depends on the files +`parse.tab.o' and `scan.o' and the file `scan.o' depends on the file +`parse.tab.h', when `parse.y' is changed, the recipe `bison -d parse.y' +will be executed only once, and the prerequisites of both `parse.tab.o' +and `scan.o' will be satisfied. (Presumably the file `parse.tab.o' +will be recompiled from `parse.tab.c' and the file `scan.o' from +`scan.c', while `foo' is linked from `parse.tab.o', `scan.o', and its +other prerequisites, and it will execute happily ever after.) + + +File: make.info, Node: Automatic Variables, Next: Pattern Match, Prev: Pattern Examples, Up: Pattern Rules + +10.5.3 Automatic Variables +-------------------------- + +Suppose you are writing a pattern rule to compile a `.c' file into a +`.o' file: how do you write the `cc' command so that it operates on the +right source file name? You cannot write the name in the recipe, +because the name is different each time the implicit rule is applied. + + What you do is use a special feature of `make', the "automatic +variables". These variables have values computed afresh for each rule +that is executed, based on the target and prerequisites of the rule. +In this example, you would use `$@' for the object file name and `$<' +for the source file name. + + It's very important that you recognize the limited scope in which +automatic variable values are available: they only have values within +the recipe. In particular, you cannot use them anywhere within the +target list of a rule; they have no value there and will expand to the +empty string. Also, they cannot be accessed directly within the +prerequisite list of a rule. A common mistake is attempting to use +`$@' within the prerequisites list; this will not work. However, there +is a special feature of GNU `make', secondary expansion (*note +Secondary Expansion::), which will allow automatic variable values to +be used in prerequisite lists. + + Here is a table of automatic variables: + +`$@' + The file name of the target of the rule. If the target is an + archive member, then `$@' is the name of the archive file. In a + pattern rule that has multiple targets (*note Introduction to + Pattern Rules: Pattern Intro.), `$@' is the name of whichever + target caused the rule's recipe to be run. + +`$%' + The target member name, when the target is an archive member. + *Note Archives::. For example, if the target is `foo.a(bar.o)' + then `$%' is `bar.o' and `$@' is `foo.a'. `$%' is empty when the + target is not an archive member. + +`$<' + The name of the first prerequisite. If the target got its recipe + from an implicit rule, this will be the first prerequisite added + by the implicit rule (*note Implicit Rules::). + +`$?' + The names of all the prerequisites that are newer than the target, + with spaces between them. For prerequisites which are archive + members, only the named member is used (*note Archives::). + +`$^' + The names of all the prerequisites, with spaces between them. For + prerequisites which are archive members, only the named member is + used (*note Archives::). A target has only one prerequisite on + each other file it depends on, no matter how many times each file + is listed as a prerequisite. So if you list a prerequisite more + than once for a target, the value of `$^' contains just one copy + of the name. This list does *not* contain any of the order-only + prerequisites; for those see the `$|' variable, below. + +`$+' + This is like `$^', but prerequisites listed more than once are + duplicated in the order they were listed in the makefile. This is + primarily useful for use in linking commands where it is + meaningful to repeat library file names in a particular order. + +`$|' + The names of all the order-only prerequisites, with spaces between + them. + +`$*' + The stem with which an implicit rule matches (*note How Patterns + Match: Pattern Match.). If the target is `dir/a.foo.b' and the + target pattern is `a.%.b' then the stem is `dir/foo'. The stem is + useful for constructing names of related files. + + In a static pattern rule, the stem is part of the file name that + matched the `%' in the target pattern. + + In an explicit rule, there is no stem; so `$*' cannot be determined + in that way. Instead, if the target name ends with a recognized + suffix (*note Old-Fashioned Suffix Rules: Suffix Rules.), `$*' is + set to the target name minus the suffix. For example, if the + target name is `foo.c', then `$*' is set to `foo', since `.c' is a + suffix. GNU `make' does this bizarre thing only for compatibility + with other implementations of `make'. You should generally avoid + using `$*' except in implicit rules or static pattern rules. + + If the target name in an explicit rule does not end with a + recognized suffix, `$*' is set to the empty string for that rule. + + `$?' is useful even in explicit rules when you wish to operate on +only the prerequisites that have changed. For example, suppose that an +archive named `lib' is supposed to contain copies of several object +files. This rule copies just the changed object files into the archive: + + lib: foo.o bar.o lose.o win.o + ar r lib $? + + Of the variables listed above, four have values that are single file +names, and three have values that are lists of file names. These seven +have variants that get just the file's directory name or just the file +name within the directory. The variant variables' names are formed by +appending `D' or `F', respectively. These variants are semi-obsolete +in GNU `make' since the functions `dir' and `notdir' can be used to get +a similar effect (*note Functions for File Names: File Name +Functions.). Note, however, that the `D' variants all omit the +trailing slash which always appears in the output of the `dir' +function. Here is a table of the variants: + +`$(@D)' + The directory part of the file name of the target, with the + trailing slash removed. If the value of `$@' is `dir/foo.o' then + `$(@D)' is `dir'. This value is `.' if `$@' does not contain a + slash. + +`$(@F)' + The file-within-directory part of the file name of the target. If + the value of `$@' is `dir/foo.o' then `$(@F)' is `foo.o'. `$(@F)' + is equivalent to `$(notdir $@)'. + +`$(*D)' +`$(*F)' + The directory part and the file-within-directory part of the stem; + `dir' and `foo' in this example. + +`$(%D)' +`$(%F)' + The directory part and the file-within-directory part of the target + archive member name. This makes sense only for archive member + targets of the form `ARCHIVE(MEMBER)' and is useful only when + MEMBER may contain a directory name. (*Note Archive Members as + Targets: Archive Members.) + +`$(<D)' +`$(<F)' + The directory part and the file-within-directory part of the first + prerequisite. + +`$(^D)' +`$(^F)' + Lists of the directory parts and the file-within-directory parts + of all prerequisites. + +`$(+D)' +`$(+F)' + Lists of the directory parts and the file-within-directory parts + of all prerequisites, including multiple instances of duplicated + prerequisites. + +`$(?D)' +`$(?F)' + Lists of the directory parts and the file-within-directory parts of + all prerequisites that are newer than the target. + + Note that we use a special stylistic convention when we talk about +these automatic variables; we write "the value of `$<'", rather than +"the variable `<'" as we would write for ordinary variables such as +`objects' and `CFLAGS'. We think this convention looks more natural in +this special case. Please do not assume it has a deep significance; +`$<' refers to the variable named `<' just as `$(CFLAGS)' refers to the +variable named `CFLAGS'. You could just as well use `$(<)' in place of +`$<'. + + +File: make.info, Node: Pattern Match, Next: Match-Anything Rules, Prev: Automatic Variables, Up: Pattern Rules + +10.5.4 How Patterns Match +------------------------- + +A target pattern is composed of a `%' between a prefix and a suffix, +either or both of which may be empty. The pattern matches a file name +only if the file name starts with the prefix and ends with the suffix, +without overlap. The text between the prefix and the suffix is called +the "stem". Thus, when the pattern `%.o' matches the file name +`test.o', the stem is `test'. The pattern rule prerequisites are +turned into actual file names by substituting the stem for the character +`%'. Thus, if in the same example one of the prerequisites is written +as `%.c', it expands to `test.c'. + + When the target pattern does not contain a slash (and it usually does +not), directory names in the file names are removed from the file name +before it is compared with the target prefix and suffix. After the +comparison of the file name to the target pattern, the directory names, +along with the slash that ends them, are added on to the prerequisite +file names generated from the pattern rule's prerequisite patterns and +the file name. The directories are ignored only for the purpose of +finding an implicit rule to use, not in the application of that rule. +Thus, `e%t' matches the file name `src/eat', with `src/a' as the stem. +When prerequisites are turned into file names, the directories from the +stem are added at the front, while the rest of the stem is substituted +for the `%'. The stem `src/a' with a prerequisite pattern `c%r' gives +the file name `src/car'. + + A pattern rule can be used to build a given file only if there is a +target pattern that matches the file name, _and_ all prerequisites in +that rule either exist or can be built. The rules you write take +precedence over those that are built in. Note however, that a rule +whose prerequisites actually exist or are mentioned always takes +priority over a rule with prerequisites that must be made by chaining +other implicit rules. + + It is possible that more than one pattern rule will meet these +criteria. In that case, `make' will choose the rule with the shortest +stem (that is, the pattern that matches most specifically). If more +than one pattern rule has the shortest stem, `make' will choose the +first one found in the makefile. + + This algorithm results in more specific rules being preferred over +more generic ones; for example: + + %.o: %.c + $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@ + + %.o : %.f + $(COMPILE.F) $(OUTPUT_OPTION) $< + + lib/%.o: lib/%.c + $(CC) -fPIC -c $(CFLAGS) $(CPPFLAGS) $< -o $@ + + Given these rules and asked to build `bar.o' where both `bar.c' and +`bar.f' exist, `make' will choose the first rule and compile `bar.c' +into `bar.o'. In the same situation where `bar.c' does not exist, then +`make' will choose the second rule and compile `bar.f' into `bar.o'. + + If `make' is asked to build `lib/bar.o' and both `lib/bar.c' and +`lib/bar.f' exist, then the third rule will be chosen since the stem +for this rule (`bar') is shorter than the stem for the first rule +(`lib/bar'). If `lib/bar.c' does not exist then the third rule is not +eligible and the second rule will be used, even though the stem is +longer. + + +File: make.info, Node: Match-Anything Rules, Next: Canceling Rules, Prev: Pattern Match, Up: Pattern Rules + +10.5.5 Match-Anything Pattern Rules +----------------------------------- + +When a pattern rule's target is just `%', it matches any file name +whatever. We call these rules "match-anything" rules. They are very +useful, but it can take a lot of time for `make' to think about them, +because it must consider every such rule for each file name listed +either as a target or as a prerequisite. + + Suppose the makefile mentions `foo.c'. For this target, `make' +would have to consider making it by linking an object file `foo.c.o', +or by C compilation-and-linking in one step from `foo.c.c', or by +Pascal compilation-and-linking from `foo.c.p', and many other +possibilities. + + We know these possibilities are ridiculous since `foo.c' is a C +source file, not an executable. If `make' did consider these +possibilities, it would ultimately reject them, because files such as +`foo.c.o' and `foo.c.p' would not exist. But these possibilities are so +numerous that `make' would run very slowly if it had to consider them. + + To gain speed, we have put various constraints on the way `make' +considers match-anything rules. There are two different constraints +that can be applied, and each time you define a match-anything rule you +must choose one or the other for that rule. + + One choice is to mark the match-anything rule as "terminal" by +defining it with a double colon. When a rule is terminal, it does not +apply unless its prerequisites actually exist. Prerequisites that +could be made with other implicit rules are not good enough. In other +words, no further chaining is allowed beyond a terminal rule. + + For example, the built-in implicit rules for extracting sources from +RCS and SCCS files are terminal; as a result, if the file `foo.c,v' does +not exist, `make' will not even consider trying to make it as an +intermediate file from `foo.c,v.o' or from `RCS/SCCS/s.foo.c,v'. RCS +and SCCS files are generally ultimate source files, which should not be +remade from any other files; therefore, `make' can save time by not +looking for ways to remake them. + + If you do not mark the match-anything rule as terminal, then it is +nonterminal. A nonterminal match-anything rule cannot apply to a file +name that indicates a specific type of data. A file name indicates a +specific type of data if some non-match-anything implicit rule target +matches it. + + For example, the file name `foo.c' matches the target for the pattern +rule `%.c : %.y' (the rule to run Yacc). Regardless of whether this +rule is actually applicable (which happens only if there is a file +`foo.y'), the fact that its target matches is enough to prevent +consideration of any nonterminal match-anything rules for the file +`foo.c'. Thus, `make' will not even consider trying to make `foo.c' as +an executable file from `foo.c.o', `foo.c.c', `foo.c.p', etc. + + The motivation for this constraint is that nonterminal match-anything +rules are used for making files containing specific types of data (such +as executable files) and a file name with a recognized suffix indicates +some other specific type of data (such as a C source file). + + Special built-in dummy pattern rules are provided solely to recognize +certain file names so that nonterminal match-anything rules will not be +considered. These dummy rules have no prerequisites and no recipes, and +they are ignored for all other purposes. For example, the built-in +implicit rule + + %.p : + +exists to make sure that Pascal source files such as `foo.p' match a +specific target pattern and thereby prevent time from being wasted +looking for `foo.p.o' or `foo.p.c'. + + Dummy pattern rules such as the one for `%.p' are made for every +suffix listed as valid for use in suffix rules (*note Old-Fashioned +Suffix Rules: Suffix Rules.). + + +File: make.info, Node: Canceling Rules, Prev: Match-Anything Rules, Up: Pattern Rules + +10.5.6 Canceling Implicit Rules +------------------------------- + +You can override a built-in implicit rule (or one you have defined +yourself) by defining a new pattern rule with the same target and +prerequisites, but a different recipe. When the new rule is defined, +the built-in one is replaced. The new rule's position in the sequence +of implicit rules is determined by where you write the new rule. + + You can cancel a built-in implicit rule by defining a pattern rule +with the same target and prerequisites, but no recipe. For example, +the following would cancel the rule that runs the assembler: + + %.o : %.s + + +File: make.info, Node: Last Resort, Next: Suffix Rules, Prev: Pattern Rules, Up: Implicit Rules + +10.6 Defining Last-Resort Default Rules +======================================= + +You can define a last-resort implicit rule by writing a terminal +match-anything pattern rule with no prerequisites (*note Match-Anything +Rules::). This is just like any other pattern rule; the only thing +special about it is that it will match any target. So such a rule's +recipe is used for all targets and prerequisites that have no recipe of +their own and for which no other implicit rule applies. + + For example, when testing a makefile, you might not care if the +source files contain real data, only that they exist. Then you might +do this: + + %:: + touch $@ + +to cause all the source files needed (as prerequisites) to be created +automatically. + + You can instead define a recipe to be used for targets for which +there are no rules at all, even ones which don't specify recipes. You +do this by writing a rule for the target `.DEFAULT'. Such a rule's +recipe is used for all prerequisites which do not appear as targets in +any explicit rule, and for which no implicit rule applies. Naturally, +there is no `.DEFAULT' rule unless you write one. + + If you use `.DEFAULT' with no recipe or prerequisites: + + .DEFAULT: + +the recipe previously stored for `.DEFAULT' is cleared. Then `make' +acts as if you had never defined `.DEFAULT' at all. + + If you do not want a target to get the recipe from a match-anything +pattern rule or `.DEFAULT', but you also do not want any recipe to be +run for the target, you can give it an empty recipe (*note Defining +Empty Recipes: Empty Recipes.). + + You can use a last-resort rule to override part of another makefile. +*Note Overriding Part of Another Makefile: Overriding Makefiles. + + +File: make.info, Node: Suffix Rules, Next: Implicit Rule Search, Prev: Last Resort, Up: Implicit Rules + +10.7 Old-Fashioned Suffix Rules +=============================== + +"Suffix rules" are the old-fashioned way of defining implicit rules for +`make'. Suffix rules are obsolete because pattern rules are more +general and clearer. They are supported in GNU `make' for +compatibility with old makefiles. They come in two kinds: +"double-suffix" and "single-suffix". + + A double-suffix rule is defined by a pair of suffixes: the target +suffix and the source suffix. It matches any file whose name ends with +the target suffix. The corresponding implicit prerequisite is made by +replacing the target suffix with the source suffix in the file name. A +two-suffix rule whose target and source suffixes are `.o' and `.c' is +equivalent to the pattern rule `%.o : %.c'. + + A single-suffix rule is defined by a single suffix, which is the +source suffix. It matches any file name, and the corresponding implicit +prerequisite name is made by appending the source suffix. A +single-suffix rule whose source suffix is `.c' is equivalent to the +pattern rule `% : %.c'. + + Suffix rule definitions are recognized by comparing each rule's +target against a defined list of known suffixes. When `make' sees a +rule whose target is a known suffix, this rule is considered a +single-suffix rule. When `make' sees a rule whose target is two known +suffixes concatenated, this rule is taken as a double-suffix rule. + + For example, `.c' and `.o' are both on the default list of known +suffixes. Therefore, if you define a rule whose target is `.c.o', +`make' takes it to be a double-suffix rule with source suffix `.c' and +target suffix `.o'. Here is the old-fashioned way to define the rule +for compiling a C source file: + + .c.o: + $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $< + + Suffix rules cannot have any prerequisites of their own. If they +have any, they are treated as normal files with funny names, not as +suffix rules. Thus, the rule: + + .c.o: foo.h + $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $< + +tells how to make the file `.c.o' from the prerequisite file `foo.h', +and is not at all like the pattern rule: + + %.o: %.c foo.h + $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $< + +which tells how to make `.o' files from `.c' files, and makes all `.o' +files using this pattern rule also depend on `foo.h'. + + Suffix rules with no recipe are also meaningless. They do not remove +previous rules as do pattern rules with no recipe (*note Canceling +Implicit Rules: Canceling Rules.). They simply enter the suffix or +pair of suffixes concatenated as a target in the data base. + + The known suffixes are simply the names of the prerequisites of the +special target `.SUFFIXES'. You can add your own suffixes by writing a +rule for `.SUFFIXES' that adds more prerequisites, as in: + + .SUFFIXES: .hack .win + +which adds `.hack' and `.win' to the end of the list of suffixes. + + If you wish to eliminate the default known suffixes instead of just +adding to them, write a rule for `.SUFFIXES' with no prerequisites. By +special dispensation, this eliminates all existing prerequisites of +`.SUFFIXES'. You can then write another rule to add the suffixes you +want. For example, + + .SUFFIXES: # Delete the default suffixes + .SUFFIXES: .c .o .h # Define our suffix list + + The `-r' or `--no-builtin-rules' flag causes the default list of +suffixes to be empty. + + The variable `SUFFIXES' is defined to the default list of suffixes +before `make' reads any makefiles. You can change the list of suffixes +with a rule for the special target `.SUFFIXES', but that does not alter +this variable. + + +File: make.info, Node: Implicit Rule Search, Prev: Suffix Rules, Up: Implicit Rules + +10.8 Implicit Rule Search Algorithm +=================================== + +Here is the procedure `make' uses for searching for an implicit rule +for a target T. This procedure is followed for each double-colon rule +with no recipe, for each target of ordinary rules none of which have a +recipe, and for each prerequisite that is not the target of any rule. +It is also followed recursively for prerequisites that come from +implicit rules, in the search for a chain of rules. + + Suffix rules are not mentioned in this algorithm because suffix +rules are converted to equivalent pattern rules once the makefiles have +been read in. + + For an archive member target of the form `ARCHIVE(MEMBER)', the +following algorithm is run twice, first using the entire target name T, +and second using `(MEMBER)' as the target T if the first run found no +rule. + + 1. Split T into a directory part, called D, and the rest, called N. + For example, if T is `src/foo.o', then D is `src/' and N is + `foo.o'. + + 2. Make a list of all the pattern rules one of whose targets matches + T or N. If the target pattern contains a slash, it is matched + against T; otherwise, against N. + + 3. If any rule in that list is _not_ a match-anything rule, then + remove all nonterminal match-anything rules from the list. + + 4. Remove from the list all rules with no recipe. + + 5. For each pattern rule in the list: + + a. Find the stem S, which is the nonempty part of T or N matched + by the `%' in the target pattern. + + b. Compute the prerequisite names by substituting S for `%'; if + the target pattern does not contain a slash, append D to the + front of each prerequisite name. + + c. Test whether all the prerequisites exist or ought to exist. + (If a file name is mentioned in the makefile as a target or + as an explicit prerequisite, then we say it ought to exist.) + + If all prerequisites exist or ought to exist, or there are no + prerequisites, then this rule applies. + + 6. If no pattern rule has been found so far, try harder. For each + pattern rule in the list: + + a. If the rule is terminal, ignore it and go on to the next rule. + + b. Compute the prerequisite names as before. + + c. Test whether all the prerequisites exist or ought to exist. + + d. For each prerequisite that does not exist, follow this + algorithm recursively to see if the prerequisite can be made + by an implicit rule. + + e. If all prerequisites exist, ought to exist, or can be made by + implicit rules, then this rule applies. + + 7. If no implicit rule applies, the rule for `.DEFAULT', if any, + applies. In that case, give T the same recipe that `.DEFAULT' + has. Otherwise, there is no recipe for T. + + Once a rule that applies has been found, for each target pattern of +the rule other than the one that matched T or N, the `%' in the pattern +is replaced with S and the resultant file name is stored until the +recipe to remake the target file T is executed. After the recipe is +executed, each of these stored file names are entered into the data +base and marked as having been updated and having the same update +status as the file T. + + When the recipe of a pattern rule is executed for T, the automatic +variables are set corresponding to the target and prerequisites. *Note +Automatic Variables::. + + +File: make.info, Node: Archives, Next: Features, Prev: Implicit Rules, Up: Top + +11 Using `make' to Update Archive Files +*************************************** + +"Archive files" are files containing named subfiles called "members"; +they are maintained with the program `ar' and their main use is as +subroutine libraries for linking. + +* Menu: + +* Archive Members:: Archive members as targets. +* Archive Update:: The implicit rule for archive member targets. +* Archive Pitfalls:: Dangers to watch out for when using archives. +* Archive Suffix Rules:: You can write a special kind of suffix rule + for updating archives. + + +File: make.info, Node: Archive Members, Next: Archive Update, Prev: Archives, Up: Archives + +11.1 Archive Members as Targets +=============================== + +An individual member of an archive file can be used as a target or +prerequisite in `make'. You specify the member named MEMBER in archive +file ARCHIVE as follows: + + ARCHIVE(MEMBER) + +This construct is available only in targets and prerequisites, not in +recipes! Most programs that you might use in recipes do not support +this syntax and cannot act directly on archive members. Only `ar' and +other programs specifically designed to operate on archives can do so. +Therefore, valid recipes to update an archive member target probably +must use `ar'. For example, this rule says to create a member `hack.o' +in archive `foolib' by copying the file `hack.o': + + foolib(hack.o) : hack.o + ar cr foolib hack.o + + In fact, nearly all archive member targets are updated in just this +way and there is an implicit rule to do it for you. *Please note:* The +`c' flag to `ar' is required if the archive file does not already exist. + + To specify several members in the same archive, you can write all the +member names together between the parentheses. For example: + + foolib(hack.o kludge.o) + +is equivalent to: + + foolib(hack.o) foolib(kludge.o) + + You can also use shell-style wildcards in an archive member +reference. *Note Using Wildcard Characters in File Names: Wildcards. +For example, `foolib(*.o)' expands to all existing members of the +`foolib' archive whose names end in `.o'; perhaps `foolib(hack.o) +foolib(kludge.o)'. + + +File: make.info, Node: Archive Update, Next: Archive Pitfalls, Prev: Archive Members, Up: Archives + +11.2 Implicit Rule for Archive Member Targets +============================================= + +Recall that a target that looks like `A(M)' stands for the member named +M in the archive file A. + + When `make' looks for an implicit rule for such a target, as a +special feature it considers implicit rules that match `(M)', as well as +those that match the actual target `A(M)'. + + This causes one special rule whose target is `(%)' to match. This +rule updates the target `A(M)' by copying the file M into the archive. +For example, it will update the archive member target `foo.a(bar.o)' by +copying the _file_ `bar.o' into the archive `foo.a' as a _member_ named +`bar.o'. + + When this rule is chained with others, the result is very powerful. +Thus, `make "foo.a(bar.o)"' (the quotes are needed to protect the `(' +and `)' from being interpreted specially by the shell) in the presence +of a file `bar.c' is enough to cause the following recipe to be run, +even without a makefile: + + cc -c bar.c -o bar.o + ar r foo.a bar.o + rm -f bar.o + +Here `make' has envisioned the file `bar.o' as an intermediate file. +*Note Chains of Implicit Rules: Chained Rules. + + Implicit rules such as this one are written using the automatic +variable `$%'. *Note Automatic Variables::. + + An archive member name in an archive cannot contain a directory +name, but it may be useful in a makefile to pretend that it does. If +you write an archive member target `foo.a(dir/file.o)', `make' will +perform automatic updating with this recipe: + + ar r foo.a dir/file.o + +which has the effect of copying the file `dir/file.o' into a member +named `file.o'. In connection with such usage, the automatic variables +`%D' and `%F' may be useful. + +* Menu: + +* Archive Symbols:: How to update archive symbol directories. + + +File: make.info, Node: Archive Symbols, Prev: Archive Update, Up: Archive Update + +11.2.1 Updating Archive Symbol Directories +------------------------------------------ + +An archive file that is used as a library usually contains a special +member named `__.SYMDEF' that contains a directory of the external +symbol names defined by all the other members. After you update any +other members, you need to update `__.SYMDEF' so that it will summarize +the other members properly. This is done by running the `ranlib' +program: + + ranlib ARCHIVEFILE + + Normally you would put this command in the rule for the archive file, +and make all the members of the archive file prerequisites of that rule. +For example, + + libfoo.a: libfoo.a(x.o) libfoo.a(y.o) ... + ranlib libfoo.a + +The effect of this is to update archive members `x.o', `y.o', etc., and +then update the symbol directory member `__.SYMDEF' by running +`ranlib'. The rules for updating the members are not shown here; most +likely you can omit them and use the implicit rule which copies files +into the archive, as described in the preceding section. + + This is not necessary when using the GNU `ar' program, which updates +the `__.SYMDEF' member automatically. + + +File: make.info, Node: Archive Pitfalls, Next: Archive Suffix Rules, Prev: Archive Update, Up: Archives + +11.3 Dangers When Using Archives +================================ + +It is important to be careful when using parallel execution (the `-j' +switch; *note Parallel Execution: Parallel.) and archives. If multiple +`ar' commands run at the same time on the same archive file, they will +not know about each other and can corrupt the file. + + Possibly a future version of `make' will provide a mechanism to +circumvent this problem by serializing all recipes that operate on the +same archive file. But for the time being, you must either write your +makefiles to avoid this problem in some other way, or not use `-j'. + + +File: make.info, Node: Archive Suffix Rules, Prev: Archive Pitfalls, Up: Archives + +11.4 Suffix Rules for Archive Files +=================================== + +You can write a special kind of suffix rule for dealing with archive +files. *Note Suffix Rules::, for a full explanation of suffix rules. +Archive suffix rules are obsolete in GNU `make', because pattern rules +for archives are a more general mechanism (*note Archive Update::). +But they are retained for compatibility with other `make's. + + To write a suffix rule for archives, you simply write a suffix rule +using the target suffix `.a' (the usual suffix for archive files). For +example, here is the old-fashioned suffix rule to update a library +archive from C source files: + + .c.a: + $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o + $(AR) r $@ $*.o + $(RM) $*.o + +This works just as if you had written the pattern rule: + + (%.o): %.c + $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o + $(AR) r $@ $*.o + $(RM) $*.o + + In fact, this is just what `make' does when it sees a suffix rule +with `.a' as the target suffix. Any double-suffix rule `.X.a' is +converted to a pattern rule with the target pattern `(%.o)' and a +prerequisite pattern of `%.X'. + + Since you might want to use `.a' as the suffix for some other kind +of file, `make' also converts archive suffix rules to pattern rules in +the normal way (*note Suffix Rules::). Thus a double-suffix rule +`.X.a' produces two pattern rules: `(%.o): %.X' and `%.a: %.X'. + + +File: make.info, Node: Features, Next: Missing, Prev: Archives, Up: Top + +12 Features of GNU `make' +************************* + +Here is a summary of the features of GNU `make', for comparison with +and credit to other versions of `make'. We consider the features of +`make' in 4.2 BSD systems as a baseline. If you are concerned with +writing portable makefiles, you should not use the features of `make' +listed here, nor the ones in *note Missing::. + + Many features come from the version of `make' in System V. + + * The `VPATH' variable and its special meaning. *Note Searching + Directories for Prerequisites: Directory Search. This feature + exists in System V `make', but is undocumented. It is documented + in 4.3 BSD `make' (which says it mimics System V's `VPATH' + feature). + + * Included makefiles. *Note Including Other Makefiles: Include. + Allowing multiple files to be included with a single directive is + a GNU extension. + + * Variables are read from and communicated via the environment. + *Note Variables from the Environment: Environment. + + * Options passed through the variable `MAKEFLAGS' to recursive + invocations of `make'. *Note Communicating Options to a + Sub-`make': Options/Recursion. + + * The automatic variable `$%' is set to the member name in an + archive reference. *Note Automatic Variables::. + + * The automatic variables `$@', `$*', `$<', `$%', and `$?' have + corresponding forms like `$(@F)' and `$(@D)'. We have generalized + this to `$^' as an obvious extension. *Note Automatic Variables::. + + * Substitution variable references. *Note Basics of Variable + References: Reference. + + * The command line options `-b' and `-m', accepted and ignored. In + System V `make', these options actually do something. + + * Execution of recursive commands to run `make' via the variable + `MAKE' even if `-n', `-q' or `-t' is specified. *Note Recursive + Use of `make': Recursion. + + * Support for suffix `.a' in suffix rules. *Note Archive Suffix + Rules::. This feature is obsolete in GNU `make', because the + general feature of rule chaining (*note Chains of Implicit Rules: + Chained Rules.) allows one pattern rule for installing members in + an archive (*note Archive Update::) to be sufficient. + + * The arrangement of lines and backslash-newline combinations in + recipes is retained when the recipes are printed, so they appear as + they do in the makefile, except for the stripping of initial + whitespace. + + The following features were inspired by various other versions of +`make'. In some cases it is unclear exactly which versions inspired +which others. + + * Pattern rules using `%'. This has been implemented in several + versions of `make'. We're not sure who invented it first, but + it's been spread around a bit. *Note Defining and Redefining + Pattern Rules: Pattern Rules. + + * Rule chaining and implicit intermediate files. This was + implemented by Stu Feldman in his version of `make' for AT&T + Eighth Edition Research Unix, and later by Andrew Hume of AT&T + Bell Labs in his `mk' program (where he terms it "transitive + closure"). We do not really know if we got this from either of + them or thought it up ourselves at the same time. *Note Chains of + Implicit Rules: Chained Rules. + + * The automatic variable `$^' containing a list of all prerequisites + of the current target. We did not invent this, but we have no + idea who did. *Note Automatic Variables::. The automatic variable + `$+' is a simple extension of `$^'. + + * The "what if" flag (`-W' in GNU `make') was (as far as we know) + invented by Andrew Hume in `mk'. *Note Instead of Executing + Recipes: Instead of Execution. + + * The concept of doing several things at once (parallelism) exists in + many incarnations of `make' and similar programs, though not in the + System V or BSD implementations. *Note Recipe Execution: + Execution. + + * Modified variable references using pattern substitution come from + SunOS 4. *Note Basics of Variable References: Reference. This + functionality was provided in GNU `make' by the `patsubst' + function before the alternate syntax was implemented for + compatibility with SunOS 4. It is not altogether clear who + inspired whom, since GNU `make' had `patsubst' before SunOS 4 was + released. + + * The special significance of `+' characters preceding recipe lines + (*note Instead of Executing Recipes: Instead of Execution.) is + mandated by `IEEE Standard 1003.2-1992' (POSIX.2). + + * The `+=' syntax to append to the value of a variable comes from + SunOS 4 `make'. *Note Appending More Text to Variables: Appending. + + * The syntax `ARCHIVE(MEM1 MEM2...)' to list multiple members in a + single archive file comes from SunOS 4 `make'. *Note Archive + Members::. + + * The `-include' directive to include makefiles with no error for a + nonexistent file comes from SunOS 4 `make'. (But note that SunOS 4 + `make' does not allow multiple makefiles to be specified in one + `-include' directive.) The same feature appears with the name + `sinclude' in SGI `make' and perhaps others. + + The remaining features are inventions new in GNU `make': + + * Use the `-v' or `--version' option to print version and copyright + information. + + * Use the `-h' or `--help' option to summarize the options to `make'. + + * Simply-expanded variables. *Note The Two Flavors of Variables: + Flavors. + + * Pass command line variable assignments automatically through the + variable `MAKE' to recursive `make' invocations. *Note Recursive + Use of `make': Recursion. + + * Use the `-C' or `--directory' command option to change directory. + *Note Summary of Options: Options Summary. + + * Make verbatim variable definitions with `define'. *Note Defining + Multi-Line Variables: Multi-Line. + + * Declare phony targets with the special target `.PHONY'. + + Andrew Hume of AT&T Bell Labs implemented a similar feature with a + different syntax in his `mk' program. This seems to be a case of + parallel discovery. *Note Phony Targets: Phony Targets. + + * Manipulate text by calling functions. *Note Functions for + Transforming Text: Functions. + + * Use the `-o' or `--old-file' option to pretend a file's + modification-time is old. *Note Avoiding Recompilation of Some + Files: Avoiding Compilation. + + * Conditional execution. + + This feature has been implemented numerous times in various + versions of `make'; it seems a natural extension derived from the + features of the C preprocessor and similar macro languages and is + not a revolutionary concept. *Note Conditional Parts of + Makefiles: Conditionals. + + * Specify a search path for included makefiles. *Note Including + Other Makefiles: Include. + + * Specify extra makefiles to read with an environment variable. + *Note The Variable `MAKEFILES': MAKEFILES Variable. + + * Strip leading sequences of `./' from file names, so that `./FILE' + and `FILE' are considered to be the same file. + + * Use a special search method for library prerequisites written in + the form `-lNAME'. *Note Directory Search for Link Libraries: + Libraries/Search. + + * Allow suffixes for suffix rules (*note Old-Fashioned Suffix Rules: + Suffix Rules.) to contain any characters. In other versions of + `make', they must begin with `.' and not contain any `/' + characters. + + * Keep track of the current level of `make' recursion using the + variable `MAKELEVEL'. *Note Recursive Use of `make': Recursion. + + * Provide any goals given on the command line in the variable + `MAKECMDGOALS'. *Note Arguments to Specify the Goals: Goals. + + * Specify static pattern rules. *Note Static Pattern Rules: Static + Pattern. + + * Provide selective `vpath' search. *Note Searching Directories for + Prerequisites: Directory Search. + + * Provide computed variable references. *Note Basics of Variable + References: Reference. + + * Update makefiles. *Note How Makefiles Are Remade: Remaking + Makefiles. System V `make' has a very, very limited form of this + functionality in that it will check out SCCS files for makefiles. + + * Various new built-in implicit rules. *Note Catalogue of Implicit + Rules: Catalogue of Rules. + + * The built-in variable `MAKE_VERSION' gives the version number of + `make'. + + +File: make.info, Node: Missing, Next: Makefile Conventions, Prev: Features, Up: Top + +13 Incompatibilities and Missing Features +***************************************** + +The `make' programs in various other systems support a few features +that are not implemented in GNU `make'. The POSIX.2 standard (`IEEE +Standard 1003.2-1992') which specifies `make' does not require any of +these features. + + * A target of the form `FILE((ENTRY))' stands for a member of + archive file FILE. The member is chosen, not by name, but by + being an object file which defines the linker symbol ENTRY. + + This feature was not put into GNU `make' because of the + nonmodularity of putting knowledge into `make' of the internal + format of archive file symbol tables. *Note Updating Archive + Symbol Directories: Archive Symbols. + + * Suffixes (used in suffix rules) that end with the character `~' + have a special meaning to System V `make'; they refer to the SCCS + file that corresponds to the file one would get without the `~'. + For example, the suffix rule `.c~.o' would make the file `N.o' from + the SCCS file `s.N.c'. For complete coverage, a whole series of + such suffix rules is required. *Note Old-Fashioned Suffix Rules: + Suffix Rules. + + In GNU `make', this entire series of cases is handled by two + pattern rules for extraction from SCCS, in combination with the + general feature of rule chaining. *Note Chains of Implicit Rules: + Chained Rules. + + * In System V and 4.3 BSD `make', files found by `VPATH' search + (*note Searching Directories for Prerequisites: Directory Search.) + have their names changed inside recipes. We feel it is much + cleaner to always use automatic variables and thus make this + feature obsolete. + + * In some Unix `make's, the automatic variable `$*' appearing in the + prerequisites of a rule has the amazingly strange "feature" of + expanding to the full name of the _target of that rule_. We cannot + imagine what went on in the minds of Unix `make' developers to do + this; it is utterly inconsistent with the normal definition of + `$*'. + + * In some Unix `make's, implicit rule search (*note Using Implicit + Rules: Implicit Rules.) is apparently done for _all_ targets, not + just those without recipes. This means you can do: + + foo.o: + cc -c foo.c + + and Unix `make' will intuit that `foo.o' depends on `foo.c'. + + We feel that such usage is broken. The prerequisite properties of + `make' are well-defined (for GNU `make', at least), and doing such + a thing simply does not fit the model. + + * GNU `make' does not include any built-in implicit rules for + compiling or preprocessing EFL programs. If we hear of anyone who + is using EFL, we will gladly add them. + + * It appears that in SVR4 `make', a suffix rule can be specified + with no recipe, and it is treated as if it had an empty recipe + (*note Empty Recipes::). For example: + + .c.a: + + will override the built-in `.c.a' suffix rule. + + We feel that it is cleaner for a rule without a recipe to always + simply add to the prerequisite list for the target. The above + example can be easily rewritten to get the desired behavior in GNU + `make': + + .c.a: ; + + * Some versions of `make' invoke the shell with the `-e' flag, + except under `-k' (*note Testing the Compilation of a Program: + Testing.). The `-e' flag tells the shell to exit as soon as any + program it runs returns a nonzero status. We feel it is cleaner to + write each line of the recipe to stand on its own and not require + this special treatment. + + +File: make.info, Node: Makefile Conventions, Next: Quick Reference, Prev: Missing, Up: Top + +14 Makefile Conventions +*********************** + +This node describes conventions for writing the Makefiles for GNU +programs. Using Automake will help you write a Makefile that follows +these conventions. For more information on portable Makefiles, see +POSIX and *note Portable Make Programming: (autoconf)Portable Make. + +* Menu: + +* Makefile Basics:: General conventions for Makefiles. +* Utilities in Makefiles:: Utilities to be used in Makefiles. +* Command Variables:: Variables for specifying commands. +* DESTDIR:: Supporting staged installs. +* 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. + + +File: make.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions + +14.1 General Conventions for Makefiles +====================================== + +Every Makefile should contain this line: + + SHELL = /bin/sh + +to avoid trouble on systems where the `SHELL' variable might be +inherited from the environment. (This is never a problem with GNU +`make'.) + + Different `make' programs have incompatible suffix lists and +implicit rules, and this sometimes creates confusion or misbehavior. So +it is a good idea to set the suffix list explicitly using only the +suffixes you need in the particular Makefile, like this: + + .SUFFIXES: + .SUFFIXES: .c .o + +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + + Don't assume that `.' is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses `./' if the program is built as +part of the make or `$(srcdir)/' if the file is an unchanging part of +the source code. Without one of these prefixes, the current search +path is used. + + The distinction between `./' (the "build directory") and +`$(srcdir)/' (the "source directory") is important because users can +build in a separate directory using the `--srcdir' option to +`configure'. A rule of the form: + + foo.1 : foo.man sedscript + sed -f sedscript foo.man > foo.1 + +will fail when the build directory is not the source directory, because +`foo.man' and `sedscript' are in the source directory. + + When using GNU `make', relying on `VPATH' to find the source file +will work in the case where there is a single dependency file, since +the `make' automatic variable `$<' will represent the source file +wherever it is. (Many versions of `make' set `$<' only in implicit +rules.) A Makefile target like + + foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o + +should instead be written as + + foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@ + +in order to allow `VPATH' to work correctly. When the target has +multiple dependencies, using an explicit `$(srcdir)' is the easiest way +to make the rule work well. For example, the target above for `foo.1' +is best written as: + + foo.1 : foo.man sedscript + sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@ + + 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 `make'. + + +File: make.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions + +14.2 Utilities in Makefiles +=========================== + +Write the Makefile commands (and any shell scripts, such as +`configure') to run under `sh' (both the traditional Bourne shell and +the POSIX shell), not `csh'. Don't use any special features of `ksh' +or `bash', or POSIX features not widely supported in traditional Bourne +`sh'. + + The `configure' script and the Makefile rules for building and +installation should not use any utilities directly except these: + + 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 + + Compression programs such as `gzip' can be used in the `dist' rule. + + Generally, stick to the widely-supported (usually POSIX-specified) +options and features of these programs. For example, don't use `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 *note Portable Shell Programming: +(autoconf)Portable Shell. + + It is a good idea to avoid creating symbolic links in makefiles, +since a 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 `make' variables +so that the user can substitute alternatives. Here are some of the +programs we mean: + + ar bison cc flex install ld ldconfig lex + make makeinfo ranlib texi2dvi yacc + + Use the following `make' variables to run those programs: + + $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) + $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) + + When you use `ranlib' or `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 `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: + + chgrp chmod chown mknod + + It is ok to use other utilities in Makefile portions (or scripts) +intended only for particular systems where you know those utilities +exist. + + +File: make.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions + +14.3 Variables for Specifying Commands +====================================== + +Makefiles should provide variables for overriding certain commands, +options, and so on. + + In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named `BISON' whose default +value is set with `BISON = bison', and refer to it with `$(BISON)' +whenever you need to use Bison. + + File management utilities such as `ln', `rm', `mv', and so on, need +not be referred to through variables in this way, since users don't +need to replace them with other programs. + + Each program-name variable should come with an options variable that +is used to supply options to the program. Append `FLAGS' to the +program-name variable name to get the options variable name--for +example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler, +`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule, +but we keep them because they are standard.) Use `CPPFLAGS' in any +compilation command that runs the preprocessor, and use `LDFLAGS' in +any compilation command that does linking as well as in any direct use +of `ld'. + + If there are C compiler options that _must_ be used for proper +compilation of certain files, do not include them in `CFLAGS'. Users +expect to be able to specify `CFLAGS' freely themselves. Instead, +arrange to pass the necessary options to the C compiler independently +of `CFLAGS', by writing them explicitly in the compilation commands or +by defining an implicit rule, like this: + + CFLAGS = -g + ALL_CFLAGS = -I. $(CFLAGS) + .c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< + + Do include the `-g' option in `CFLAGS', because that is not +_required_ for proper compilation. You can consider it a default that +is only recommended. If the package is set up so that it is compiled +with GCC by default, then you might as well include `-O' in the default +value of `CFLAGS' as well. + + Put `CFLAGS' last in the compilation command, after other variables +containing compiler options, so the user can use `CFLAGS' to override +the others. + + `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 `INSTALL', which is the +basic command for installing a file into the system. + + Every Makefile should also define the variables `INSTALL_PROGRAM' +and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be +`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m +644'.) Then it should use those variables as the commands for actual +installation, for executables and non-executables respectively. +Minimal use of these variables is as follows: + + $(INSTALL_PROGRAM) foo $(bindir)/foo + $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a + + However, it is preferable to support a `DESTDIR' prefix on the +target files, as explained in the next section. + + It is acceptable, but not required, to install multiple files in one +command, with the final argument being a directory, as in: + + $(INSTALL_PROGRAM) foo bar baz $(bindir) + + +File: make.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions + +14.4 `DESTDIR': Support for Staged Installs +=========================================== + +`DESTDIR' is a variable prepended to each installed target file, like +this: + + $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo + $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a + + The `DESTDIR' variable is specified by the user on the `make' +command line as an absolute file name. For example: + + make DESTDIR=/tmp/stage install + +`DESTDIR' should be supported only in the `install*' and `uninstall*' +targets, as those are the only targets where it is useful. + + If your installation step would normally install +`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an +installation invoked as in the example above would install +`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a' +instead. + + Prepending the variable `DESTDIR' to each target in this way +provides for "staged installs", where the installed files are not +placed directly into their expected location but are instead copied +into a temporary location (`DESTDIR'). However, installed files +maintain their relative directory structure and any embedded file names +will not be modified. + + You should not set the value of `DESTDIR' in your `Makefile' at all; +then the files are installed into their expected locations by default. +Also, specifying `DESTDIR' should not change the operation of the +software in any way, so its value should not be included in any file +contents. + + `DESTDIR' support is commonly used in package creation. It is also +helpful to users who want to understand what a given package will +install where, and to allow users who don't normally have permissions +to install into protected areas to build and install before gaining +those permissions. Finally, it can be useful with tools such as +`stow', where code is installed in one place but made to appear to be +installed somewhere else using symbolic links or special mount +operations. So, we strongly recommend GNU packages support `DESTDIR', +though it is not an absolute requirement. + + +File: make.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions + +14.5 Variables for Installation Directories +=========================================== + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables and the values they should have in GNU packages are described +below. They are based on a standard file system layout; variants of it +are used in GNU/Linux and other modern operating systems. + + Installers are expected to override these values when calling `make' +(e.g., `make prefix=/usr install' or `configure' (e.g., `configure +--prefix=/usr'). GNU packages should not try to guess which value +should be appropriate for these variables on the system they are being +installed onto: use the default settings specified here so that all GNU +packages behave identically, allowing the installer to achieve any +desired layout. + + 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 +directories. + +`prefix' + A prefix used in constructing the default values of the variables + listed below. The default value of `prefix' should be + `/usr/local'. When building the complete GNU system, the prefix + will be empty and `/usr' will be a symbolic link to `/'. (If you + are using Autoconf, write it as `@prefix@'.) + + Running `make install' with a different value of `prefix' from the + one used to build the program should _not_ recompile the program. + +`exec_prefix' + A prefix used in constructing the default values of some of the + variables listed below. The default value of `exec_prefix' should + be `$(prefix)'. (If you are using Autoconf, write it as + `@exec_prefix@'.) + + Generally, `$(exec_prefix)' is used for directories that contain + machine-specific files (such as executables and subroutine + libraries), while `$(prefix)' is used directly for other + directories. + + Running `make install' with a different value of `exec_prefix' + from the one used to build the program should _not_ recompile the + program. + + Executable programs are installed in one of the following +directories. + +`bindir' + The directory for installing executable programs that users can + run. This should normally be `/usr/local/bin', but write it as + `$(exec_prefix)/bin'. (If you are using Autoconf, write it as + `@bindir@'.) + +`sbindir' + The directory for installing executable programs that can be run + from the shell, but are only generally useful to system + administrators. This should normally be `/usr/local/sbin', but + write it as `$(exec_prefix)/sbin'. (If you are using Autoconf, + write it as `@sbindir@'.) + +`libexecdir' + The directory for installing executable programs to be run by other + programs rather than by users. This directory should normally be + `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'. + (If you are using Autoconf, write it as `@libexecdir@'.) + + The definition of `libexecdir' is the same for all packages, so + you should install your data in a subdirectory thereof. Most + packages install their data under `$(libexecdir)/PACKAGE-NAME/', + possibly within additional subdirectories thereof, such as + `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'. + + Data files used by the program during its execution are divided into +categories in two ways. + + * Some files are normally modified by programs; others are never + normally modified (though users may edit some of these). + + * Some files are architecture-independent and can be shared by all + machines at a site; some are architecture-dependent and can be + shared only by machines of the same kind and operating system; + others may never be shared between two machines. + + This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + + Here are the variables Makefiles should use to specify directories +to put these various kinds of files in: + +`datarootdir' + The root of the directory tree for read-only + architecture-independent data files. This should normally be + `/usr/local/share', but write it as `$(prefix)/share'. (If you + are using Autoconf, write it as `@datarootdir@'.) `datadir''s + default value is based on this variable; so are `infodir', + `mandir', and others. + +`datadir' + The directory for installing idiosyncratic read-only + architecture-independent data files for this program. This is + usually the same place as `datarootdir', but we use the two + separate variables so that you can move these program-specific + files without altering the location for Info files, man pages, etc. + + This should normally be `/usr/local/share', but write it as + `$(datarootdir)'. (If you are using Autoconf, write it as + `@datadir@'.) + + The definition of `datadir' is the same for all packages, so you + should install your data in a subdirectory thereof. Most packages + install their data under `$(datadir)/PACKAGE-NAME/'. + +`sysconfdir' + The directory for installing read-only data files that pertain to a + single machine-that is to say, files for configuring a host. + Mailer and network configuration files, `/etc/passwd', and so + forth belong here. All the files in this directory should be + ordinary ASCII text files. This directory should normally be + `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are + using Autoconf, write it as `@sysconfdir@'.) + + Do not install executables here in this directory (they probably + belong in `$(libexecdir)' or `$(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 `$(localstatedir)'. + +`sharedstatedir' + The directory for installing architecture-independent data files + which the programs modify while they run. This should normally be + `/usr/local/com', but write it as `$(prefix)/com'. (If you are + using Autoconf, write it as `@sharedstatedir@'.) + +`localstatedir' + The directory for installing data files which the programs modify + while they run, and that pertain to one specific machine. Users + should never need to modify files in this directory to configure + the package's operation; put such configuration information in + separate files that go in `$(datadir)' or `$(sysconfdir)'. + `$(localstatedir)' should normally be `/usr/local/var', but write + it as `$(prefix)/var'. (If you are using Autoconf, write it as + `@localstatedir@'.) + + These variables specify the directory for installing certain specific +types of files, if your program has them. Every GNU package should +have Info files, so every program needs `infodir', but not all need +`libdir' or `lispdir'. + +`includedir' + The directory for installing header files to be included by user + programs with the C `#include' preprocessor directive. This + should normally be `/usr/local/include', but write it as + `$(prefix)/include'. (If you are using Autoconf, write it as + `@includedir@'.) + + Most compilers other than GCC do not look for header files in + directory `/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 are intended to work with other compilers. + They should install their header files in two places, one + specified by `includedir' and one specified by `oldincludedir'. + +`oldincludedir' + The directory for installing `#include' header files for use with + compilers other than GCC. This should normally be `/usr/include'. + (If you are using Autoconf, you can write it as `@oldincludedir@'.) + + The Makefile commands should check whether the value of + `oldincludedir' is empty. If it is, they should not try to use + it; they should cancel the second installation of the header files. + + A package should not replace an existing header in this directory + unless the header came from the same package. Thus, if your Foo + package provides a header file `foo.h', then it should install the + header file in the `oldincludedir' directory if either (1) there + is no `foo.h' there or (2) the `foo.h' that exists came from the + Foo package. + + To tell whether `foo.h' came from the Foo package, put a magic + string in the file--part of a comment--and `grep' for that string. + +`docdir' + The directory for installing documentation files (other than Info) + for this package. By default, it should be + `/usr/local/share/doc/YOURPKG', but it should be written as + `$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write + it as `@docdir@'.) The YOURPKG subdirectory, which may include a + version number, prevents collisions among files with common names, + such as `README'. + +`infodir' + The directory for installing the Info files for this package. By + default, it should be `/usr/local/share/info', but it should be + written as `$(datarootdir)/info'. (If you are using Autoconf, + write it as `@infodir@'.) `infodir' is separate from `docdir' for + compatibility with existing practice. + +`htmldir' +`dvidir' +`pdfdir' +`psdir' + Directories for installing documentation files in the particular + format. They should all be set to `$(docdir)' by default. (If + you are using Autoconf, write them as `@htmldir@', `@dvidir@', + etc.) Packages which supply several translations of their + documentation should install them in `$(htmldir)/'LL, + `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as + `en' or `pt_BR'. + +`libdir' + The directory for object files and libraries of object code. Do + not install executables here, they probably ought to go in + `$(libexecdir)' instead. The value of `libdir' should normally be + `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you + are using Autoconf, write it as `@libdir@'.) + +`lispdir' + The directory for installing any Emacs Lisp files in this package. + By default, it should be `/usr/local/share/emacs/site-lisp', but it + should be written as `$(datarootdir)/emacs/site-lisp'. + + If you are using Autoconf, write the default as `@lispdir@'. In + order to make `@lispdir@' work, you need the following lines in + your `configure.in' file: + + lispdir='${datarootdir}/emacs/site-lisp' + AC_SUBST(lispdir) + +`localedir' + The directory for installing locale-specific message catalogs for + this package. By default, it should be `/usr/local/share/locale', + but it should be written as `$(datarootdir)/locale'. (If you are + using Autoconf, write it as `@localedir@'.) This directory + usually has a subdirectory per locale. + + Unix-style man pages are installed in one of the following: + +`mandir' + The top-level directory for installing the man pages (if any) for + this package. It will normally be `/usr/local/share/man', but you + should write it as `$(datarootdir)/man'. (If you are using + Autoconf, write it as `@mandir@'.) + +`man1dir' + The directory for installing section 1 man pages. Write it as + `$(mandir)/man1'. + +`man2dir' + The directory for installing section 2 man pages. Write it as + `$(mandir)/man2' + +`...' + *Don't make the primary documentation for any GNU software be a + man page. Write a manual in Texinfo instead. Man pages are just + for the sake of people running GNU software on Unix, which is a + secondary application only.* + +`manext' + The file name extension for the installed man page. This should + contain a period followed by the appropriate digit; it should + normally be `.1'. + +`man1ext' + The file name extension for installed section 1 man pages. + +`man2ext' + The file name extension for installed section 2 man pages. + +`...' + Use these names instead of `manext' if the package needs to + install man pages in more than one section of the manual. + + And finally, you should set the following variable: + +`srcdir' + The directory for the sources being compiled. The value of this + variable is normally inserted by the `configure' shell script. + (If you are using Autoconf, use `srcdir = @srcdir@'.) + + For example: + + # Common prefix for installation directories. + # NOTE: This directory must exist when you start the install. + prefix = /usr/local + datarootdir = $(prefix)/share + datadir = $(datarootdir) + exec_prefix = $(prefix) + # Where to put the executable for the command `gcc'. + bindir = $(exec_prefix)/bin + # Where to put the directories used by the compiler. + libexecdir = $(exec_prefix)/libexec + # Where to put the Info files. + infodir = $(datarootdir)/info + + If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the `install' rule to create these subdirectories. + + Do not expect the user to include the subdirectory name in the value +of any of the variables listed above. The idea of having a uniform set +of variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + + At times, not all of these variables may be implemented in the +current release of Autoconf and/or Automake; but as of Autoconf 2.60, we +believe all of them are. When any are missing, the descriptions here +serve as specifications for what Autoconf will implement. As a +programmer, you can either use a development version of Autoconf or +avoid using these variables until a stable release is made which +supports them. + + +File: make.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions + +14.6 Standard Targets for Users +=============================== + +All GNU programs should have the following targets in their Makefiles: + +`all' + Compile the entire program. This should be the default target. + This target need not rebuild any documentation files; Info files + should normally be included in the distribution, and DVI (and other + documentation format) files should be made only when explicitly + asked for. + + By default, the Make rules should compile and link with `-g', so + that executable programs have debugging symbols. Users who don't + mind being helpless can strip the executables later if they wish. + +`install' + Compile the program and copy the executables, libraries, and so on + to the file names where they should reside for actual use. If + there is a simple test to verify that a program is properly + installed, this target should run that test. + + Do not strip executables when installing them. Devil-may-care + users can use the `install-strip' target to do that. + + If possible, write the `install' target rule so that it does not + modify anything in the directory where the program was built, + provided `make all' has just been done. This is convenient for + building the program under one user name and installing it under + another. + + The commands should create all the directories in which files are + to be installed, if they don't already exist. This includes the + directories specified as the values of the variables `prefix' and + `exec_prefix', as well as all subdirectories that are needed. One + way to do this is by means of an `installdirs' target as described + below. + + Use `-' before any command for installing a man page, so that + `make' will ignore any errors. This is in case there are systems + that don't have the Unix man page documentation system installed. + + The way to install Info files is to copy them into `$(infodir)' + with `$(INSTALL_DATA)' (*note Command Variables::), and then run + the `install-info' program if it is present. `install-info' is a + program that edits the Info `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 that also tries to + handle some additional situations, such as `install-info' not + being present. + + 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. + # 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"; \ + else true; fi + + When writing the `install' target, you must classify all the + commands into three categories: normal ones, "pre-installation" + commands and "post-installation" commands. *Note Install Command + Categories::. + +`install-html' +`install-dvi' +`install-pdf' +`install-ps' + These targets install documentation in formats other than Info; + they're intended to be called explicitly by the person installing + the package, if that format is desired. GNU prefers Info files, + so these must be installed by the `install' target. + + When you have many documentation files to install, we recommend + that you avoid collisions and clutter by arranging for these + targets to install in subdirectories of the appropriate + installation directory, such as `htmldir'. As one example, if + your package has multiple manuals, and you wish to install HTML + documentation with many files (such as the "split" mode output by + `makeinfo --html'), you'll certainly want to use subdirectories, + or two nodes with the same name in different manuals will + overwrite each other. + + Please make these `install-FORMAT' targets invoke the commands for + the FORMAT target, for example, by making FORMAT a dependency. + +`uninstall' + Delete all the installed files--the copies that the `install' and + `install-*' targets create. + + 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. *Note Install Command + Categories::. + +`install-strip' + Like `install', but strip the executable files while installing + them. In simple cases, this target can use the `install' target in + a simple way: + + install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install + + But if the package installs scripts as well as real executables, + the `install-strip' target can't just refer to the `install' + target; it has to strip the executables but not the scripts. + + `install-strip' should not strip the executables in the build + directory which are being copied for installation. It should only + strip the copies that are installed. + + Normally we do not recommend stripping an executable unless you + are sure the program has no bugs. However, it can be reasonable + to install a stripped executable for actual execution while saving + the unstripped executable elsewhere in case there is a bug. + +`clean' + Delete all files in the current directory that are normally + created by building the program. Also delete files in other + directories if they are created by this makefile. However, don't + delete the files that record the configuration. Also preserve + files that could be made by building, but normally aren't because + the distribution comes with them. There is no need to delete + parent directories that were created with `mkdir -p', since they + could have existed anyway. + + Delete `.dvi' files here if they are not part of the distribution. + +`distclean' + Delete all files in the current directory (or created by this + makefile) that are created by configuring or building the program. + If you have unpacked the source and built the program without + creating any other files, `make distclean' should leave only the + files that were in the distribution. However, there is no need to + delete parent directories that were created with `mkdir -p', since + they could have existed anyway. + +`mostlyclean' + Like `clean', but may refrain from deleting a few files that people + normally don't want to recompile. For example, the `mostlyclean' + target for GCC does not delete `libgcc.a', because recompiling it + is rarely necessary and takes a lot of time. + +`maintainer-clean' + Delete almost everything that can be reconstructed with this + Makefile. This typically includes everything deleted by + `distclean', plus more: C source files produced by Bison, tags + tables, Info files, and so on. + + The reason we say "almost everything" is that running the command + `make maintainer-clean' should not delete `configure' even if + `configure' can be remade using a rule in the Makefile. More + generally, `make maintainer-clean' should not delete anything that + needs to exist in order to run `configure' and then begin to build + the program. Also, there is no need to delete parent directories + that were created with `mkdir -p', since they could have existed + anyway. These are the only exceptions; `maintainer-clean' should + delete everything else that can be rebuilt. + + The `maintainer-clean' target is intended to be used by a + maintainer of the package, not by ordinary users. You may need + special tools to reconstruct some of the files that `make + maintainer-clean' deletes. Since these files are normally + included in the distribution, we don't take care to make them easy + to reconstruct. If you find you need to unpack the full + distribution again, don't blame us. + + To help make users aware of this, the commands for the special + `maintainer-clean' target should start with these two: + + @echo 'This command is intended for maintainers to use; it' + @echo 'deletes files that may need special tools to rebuild.' + +`TAGS' + Update a tags table for this program. + +`info' + Generate any Info files needed. The best way to write the rules + is as follows: + + info: foo.info + + foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi + + You must define the variable `MAKEINFO' in the Makefile. It should + run the `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. + +`dvi' +`html' +`pdf' +`ps' + Generate documentation files in the given format. These targets + should always exist, but any or all can be a no-op if the given + output format cannot be generated. These targets should not be + dependencies of the `all' target; the user must manually invoke + them. + + Here's an example rule for generating DVI files from Texinfo: + + dvi: foo.dvi + + foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi + + You must define the variable `TEXI2DVI' in the Makefile. It should + run the program `texi2dvi', which is part of the Texinfo + distribution.(1) Alternatively, write just the dependencies, and + allow GNU `make' to provide the command. + + Here's another example, this one for generating HTML from Texinfo: + + html: foo.html + + foo.html: foo.texi chap1.texi chap2.texi + $(TEXI2HTML) $(srcdir)/foo.texi + + Again, you would define the variable `TEXI2HTML' in the Makefile; + for example, it might run `makeinfo --no-split --html' (`makeinfo' + is part of the Texinfo distribution). + +`dist' + Create a distribution tar file for this program. The tar file + should be set up so that the file names in the tar file start with + a subdirectory name which is the name of the package it is a + distribution for. This name can include the version number. + + For example, the distribution tar file of GCC version 1.40 unpacks + into a subdirectory named `gcc-1.40'. + + The easiest way to do this is to create a subdirectory + appropriately named, use `ln' or `cp' to install the proper files + in it, and then `tar' that subdirectory. + + Compress the tar file with `gzip'. For example, the actual + distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'. + It is ok to support other free compression formats as well. + + The `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 distribution. *Note Making Releases: (standards)Releases. + +`check' + Perform self-tests (if any). The user must build the program + before running the tests, but need not install the program; you + should write the self-tests so that they work when the program is + built but not installed. + + The following targets are suggested as conventional names, for +programs in which they are useful. + +`installcheck' + Perform installation tests (if any). The user must build and + install the program before running the tests. You should not + assume that `$(bindir)' is in the search path. + +`installdirs' + It's useful to add a target named `installdirs' to create the + directories where files are installed, and their parent + directories. There is a script called `mkinstalldirs' which is + convenient for this; you can find it in the Gnulib package. You + can use a rule like this: + + # Make sure all installation directories (e.g. $(bindir)) + # actually exist by making them if necessary. + installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) + + or, if you wish to support `DESTDIR' (strongly encouraged), + + # Make sure all installation directories (e.g. $(bindir)) + # actually exist by making them if necessary. + installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs \ + $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ + $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ + $(DESTDIR)$(mandir) + + This rule should not modify the directories where compilation is + done. It should do nothing but create installation directories. + + ---------- Footnotes ---------- + + (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is +not distributed with Texinfo. + + +File: make.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions + +14.7 Install Command Categories +=============================== + +When writing the `install' target, you must classify all the commands +into three categories: normal ones, "pre-installation" commands and +"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 +`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 `install' rule into these three +categories, insert "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 +_should not_ define them in the makefile). + + Here are the three possible category lines, each with a comment that +explains what it means: + + $(PRE_INSTALL) # Pre-install commands follow. + $(POST_INSTALL) # Post-install commands follow. + $(NORMAL_INSTALL) # Normal commands follow. + + If you don't use a category line at the beginning of the `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 `uninstall': + + $(PRE_UNINSTALL) # Pre-uninstall commands follow. + $(POST_UNINSTALL) # Post-uninstall commands follow. + $(NORMAL_UNINSTALL) # Normal commands follow. + + Typically, a pre-uninstall command would be used for deleting entries +from the Info directory. + + If the `install' or `uninstall' target has any dependencies which +act as subroutines of installation, then you should start _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: + + [ 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 + + 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 (the `-s' option to `make' is +needed to silence messages about entering subdirectories): + + make -s -n install -o all \ + PRE_INSTALL=pre-install \ + POST_INSTALL=post-install \ + NORMAL_INSTALL=normal-install \ + | gawk -f pre-install.awk + +where the file `pre-install.awk' could contain this: + + $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0} + on {print $0} + $0 ~ /^pre-install[ \t]*$/ {on = 1} + + +File: make.info, Node: Quick Reference, Next: Error Messages, Prev: Makefile Conventions, Up: Top + +Appendix A Quick Reference +************************** + +This appendix summarizes the directives, text manipulation functions, +and special variables which GNU `make' understands. *Note Special +Targets::, *note Catalogue of Implicit Rules: Catalogue of Rules, and +*note Summary of Options: Options Summary, for other summaries. + + Here is a summary of the directives GNU `make' recognizes: + +`define VARIABLE' +`define VARIABLE =' +`define VARIABLE :=' +`define VARIABLE +=' +`define VARIABLE ?=' +`endef' + Define multi-line variables. + *Note Multi-Line::. + +`undefine VARIABLE' + Undefining variables. + *Note Undefine Directive::. + +`ifdef VARIABLE' +`ifndef VARIABLE' +`ifeq (A,B)' +`ifeq "A" "B"' +`ifeq 'A' 'B'' +`ifneq (A,B)' +`ifneq "A" "B"' +`ifneq 'A' 'B'' +`else' +`endif' + Conditionally evaluate part of the makefile. + *Note Conditionals::. + +`include FILE' +`-include FILE' +`sinclude FILE' + Include another makefile. + *Note Including Other Makefiles: Include. + +`override VARIABLE-ASSIGNMENT' + Define a variable, overriding any previous definition, even one + from the command line. + *Note The `override' Directive: Override Directive. + +`export' + Tell `make' to export all variables to child processes by default. + *Note Communicating Variables to a Sub-`make': Variables/Recursion. + +`export VARIABLE' +`export VARIABLE-ASSIGNMENT' +`unexport VARIABLE' + Tell `make' whether or not to export a particular variable to child + processes. + *Note Communicating Variables to a Sub-`make': Variables/Recursion. + +`private VARIABLE-ASSIGNMENT' + Do not allow this variable assignment to be inherited by + prerequisites. + *Note Suppressing Inheritance::. + +`vpath PATTERN PATH' + Specify a search path for files matching a `%' pattern. + *Note The `vpath' Directive: Selective Search. + +`vpath PATTERN' + Remove all search paths previously specified for PATTERN. + +`vpath' + Remove all search paths previously specified in any `vpath' + directive. + + Here is a summary of the built-in functions (*note Functions::): + +`$(subst FROM,TO,TEXT)' + Replace FROM with TO in TEXT. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(patsubst PATTERN,REPLACEMENT,TEXT)' + Replace words matching PATTERN with REPLACEMENT in TEXT. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(strip STRING)' + Remove excess whitespace characters from STRING. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(findstring FIND,TEXT)' + Locate FIND in TEXT. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(filter PATTERN...,TEXT)' + Select words in TEXT that match one of the PATTERN words. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(filter-out PATTERN...,TEXT)' + Select words in TEXT that _do not_ match any of the PATTERN words. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(sort LIST)' + Sort the words in LIST lexicographically, removing duplicates. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(word N,TEXT)' + Extract the Nth word (one-origin) of TEXT. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(words TEXT)' + Count the number of words in TEXT. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(wordlist S,E,TEXT)' + Returns the list of words in TEXT from S to E. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(firstword NAMES...)' + Extract the first word of NAMES. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(lastword NAMES...)' + Extract the last word of NAMES. + *Note Functions for String Substitution and Analysis: Text + Functions. + +`$(dir NAMES...)' + Extract the directory part of each file name. + *Note Functions for File Names: File Name Functions. + +`$(notdir NAMES...)' + Extract the non-directory part of each file name. + *Note Functions for File Names: File Name Functions. + +`$(suffix NAMES...)' + Extract the suffix (the last `.' and following characters) of each + file name. + *Note Functions for File Names: File Name Functions. + +`$(basename NAMES...)' + Extract the base name (name without suffix) of each file name. + *Note Functions for File Names: File Name Functions. + +`$(addsuffix SUFFIX,NAMES...)' + Append SUFFIX to each word in NAMES. + *Note Functions for File Names: File Name Functions. + +`$(addprefix PREFIX,NAMES...)' + Prepend PREFIX to each word in NAMES. + *Note Functions for File Names: File Name Functions. + +`$(join LIST1,LIST2)' + Join two parallel lists of words. + *Note Functions for File Names: File Name Functions. + +`$(wildcard PATTERN...)' + Find file names matching a shell file name pattern (_not_ a `%' + pattern). + *Note The Function `wildcard': Wildcard Function. + +`$(realpath NAMES...)' + For each file name in NAMES, expand to an absolute name that does + not contain any `.', `..', nor symlinks. + *Note Functions for File Names: File Name Functions. + +`$(abspath NAMES...)' + For each file name in NAMES, expand to an absolute name that does + not contain any `.' or `..' components, but preserves symlinks. + *Note Functions for File Names: File Name Functions. + +`$(error TEXT...)' + When this function is evaluated, `make' generates a fatal error + with the message TEXT. + *Note Functions That Control Make: Make Control Functions. + +`$(warning TEXT...)' + When this function is evaluated, `make' generates a warning with + the message TEXT. + *Note Functions That Control Make: Make Control Functions. + +`$(shell COMMAND)' + Execute a shell command and return its output. + *Note The `shell' Function: Shell Function. + +`$(origin VARIABLE)' + Return a string describing how the `make' variable VARIABLE was + defined. + *Note The `origin' Function: Origin Function. + +`$(flavor VARIABLE)' + Return a string describing the flavor of the `make' variable + VARIABLE. + *Note The `flavor' Function: Flavor Function. + +`$(foreach VAR,WORDS,TEXT)' + Evaluate TEXT with VAR bound to each word in WORDS, and + concatenate the results. + *Note The `foreach' Function: Foreach Function. + +`$(if CONDITION,THEN-PART[,ELSE-PART])' + Evaluate the condition CONDITION; if it's non-empty substitute the + expansion of the THEN-PART otherwise substitute the expansion of + the ELSE-PART. + *Note Functions for Conditionals: Conditional Functions. + +`$(or CONDITION1[,CONDITION2[,CONDITION3...]])' + Evaluate each condition CONDITIONN one at a time; substitute the + first non-empty expansion. If all expansions are empty, substitute + the empty string. + *Note Functions for Conditionals: Conditional Functions. + +`$(and CONDITION1[,CONDITION2[,CONDITION3...]])' + Evaluate each condition CONDITIONN one at a time; if any expansion + results in the empty string substitute the empty string. If all + expansions result in a non-empty string, substitute the expansion + of the last CONDITION. + *Note Functions for Conditionals: Conditional Functions. + +`$(call VAR,PARAM,...)' + Evaluate the variable VAR replacing any references to `$(1)', + `$(2)' with the first, second, etc. PARAM values. + *Note The `call' Function: Call Function. + +`$(eval TEXT)' + Evaluate TEXT then read the results as makefile commands. Expands + to the empty string. + *Note The `eval' Function: Eval Function. + +`$(value VAR)' + Evaluates to the contents of the variable VAR, with no expansion + performed on it. + *Note The `value' Function: Value Function. + + Here is a summary of the automatic variables. *Note Automatic +Variables::, for full information. + +`$@' + The file name of the target. + +`$%' + The target member name, when the target is an archive member. + +`$<' + The name of the first prerequisite. + +`$?' + The names of all the prerequisites that are newer than the target, + with spaces between them. For prerequisites which are archive + members, only the named member is used (*note Archives::). + +`$^' +`$+' + The names of all the prerequisites, with spaces between them. For + prerequisites which are archive members, only the named member is + used (*note Archives::). The value of `$^' omits duplicate + prerequisites, while `$+' retains them and preserves their order. + +`$*' + The stem with which an implicit rule matches (*note How Patterns + Match: Pattern Match.). + +`$(@D)' +`$(@F)' + The directory part and the file-within-directory part of `$@'. + +`$(*D)' +`$(*F)' + The directory part and the file-within-directory part of `$*'. + +`$(%D)' +`$(%F)' + The directory part and the file-within-directory part of `$%'. + +`$(<D)' +`$(<F)' + The directory part and the file-within-directory part of `$<'. + +`$(^D)' +`$(^F)' + The directory part and the file-within-directory part of `$^'. + +`$(+D)' +`$(+F)' + The directory part and the file-within-directory part of `$+'. + +`$(?D)' +`$(?F)' + The directory part and the file-within-directory part of `$?'. + + These variables are used specially by GNU `make': + +`MAKEFILES' + Makefiles to be read on every invocation of `make'. + *Note The Variable `MAKEFILES': MAKEFILES Variable. + +`VPATH' + Directory search path for files not found in the current directory. + *Note `VPATH' Search Path for All Prerequisites: General Search. + +`SHELL' + The name of the system default command interpreter, usually + `/bin/sh'. You can set `SHELL' in the makefile to change the + shell used to run recipes. *Note Recipe Execution: Execution. + The `SHELL' variable is handled specially when importing from and + exporting to the environment. *Note Choosing the Shell::. + +`MAKESHELL' + On MS-DOS only, the name of the command interpreter that is to be + used by `make'. This value takes precedence over the value of + `SHELL'. *Note MAKESHELL variable: Execution. + +`MAKE' + The name with which `make' was invoked. Using this variable in + recipes has special meaning. *Note How the `MAKE' Variable Works: + MAKE Variable. + +`MAKELEVEL' + The number of levels of recursion (sub-`make's). + *Note Variables/Recursion::. + +`MAKEFLAGS' + The flags given to `make'. You can set this in the environment or + a makefile to set flags. + *Note Communicating Options to a Sub-`make': Options/Recursion. + + It is _never_ appropriate to use `MAKEFLAGS' directly in a recipe + line: its contents may not be quoted correctly for use in the + shell. Always allow recursive `make''s to obtain these values + through the environment from its parent. + +`MAKECMDGOALS' + The targets given to `make' on the command line. Setting this + variable has no effect on the operation of `make'. + *Note Arguments to Specify the Goals: Goals. + +`CURDIR' + Set to the pathname of the current working directory (after all + `-C' options are processed, if any). Setting this variable has no + effect on the operation of `make'. + *Note Recursive Use of `make': Recursion. + +`SUFFIXES' + The default list of suffixes before `make' reads any makefiles. + +`.LIBPATTERNS' + Defines the naming of the libraries `make' searches for, and their + order. + *Note Directory Search for Link Libraries: Libraries/Search. + + +File: make.info, Node: Error Messages, Next: Complex Makefile, Prev: Quick Reference, Up: Top + +Appendix B Errors Generated by Make +*********************************** + +Here is a list of the more common errors you might see generated by +`make', and some information about what they mean and how to fix them. + + Sometimes `make' errors are not fatal, especially in the presence of +a `-' prefix on a recipe line, or the `-k' command line option. Errors +that are fatal are prefixed with the string `***'. + + Error messages are all either prefixed with the name of the program +(usually `make'), or, if the error is found in a makefile, the name of +the file and linenumber containing the problem. + + In the table below, these common prefixes are left off. + +`[FOO] Error NN' +`[FOO] SIGNAL DESCRIPTION' + These errors are not really `make' errors at all. They mean that a + program that `make' invoked as part of a recipe returned a non-0 + error code (`Error NN'), which `make' interprets as failure, or it + exited in some other abnormal fashion (with a signal of some + type). *Note Errors in Recipes: Errors. + + If no `***' is attached to the message, then the subprocess failed + but the rule in the makefile was prefixed with the `-' special + character, so `make' ignored the error. + +`missing separator. Stop.' +`missing separator (did you mean TAB instead of 8 spaces?). Stop.' + This means that `make' could not understand much of anything about + the makefile line it just read. GNU `make' looks for various + separators (`:', `=', recipe prefix characters, etc.) to indicate + what kind of line it's parsing. This message means it couldn't + find a valid one. + + One of the most common reasons for this message is that you (or + perhaps your oh-so-helpful editor, as is the case with many + MS-Windows editors) have attempted to indent your recipe lines + with spaces instead of a tab character. In this case, `make' will + use the second form of the error above. Remember that every line + in the recipe must begin with a tab character (unless you set + `.RECIPEPREFIX'; *note Special Variables::). Eight spaces do not + count. *Note Rule Syntax::. + +`recipe commences before first target. Stop.' +`missing rule before recipe. Stop.' + This means the first thing in the makefile seems to be part of a + recipe: it begins with a recipe prefix character and doesn't + appear to be a legal `make' directive (such as a variable + assignment). Recipes must always be associated with a target. + + The second form is generated if the line has a semicolon as the + first non-whitespace character; `make' interprets this to mean you + left out the "target: prerequisite" section of a rule. *Note Rule + Syntax::. + +`No rule to make target `XXX'.' +`No rule to make target `XXX', needed by `YYY'.' + This means that `make' decided it needed to build a target, but + then couldn't find any instructions in the makefile on how to do + that, either explicit or implicit (including in the default rules + database). + + If you want that file to be built, you will need to add a rule to + your makefile describing how that target can be built. Other + possible sources of this problem are typos in the makefile (if + that filename is wrong) or a corrupted source tree (if that file + is not supposed to be built, but rather only a prerequisite). + +`No targets specified and no makefile found. Stop.' +`No targets. Stop.' + The former means that you didn't provide any targets to be built + on the command line, and `make' couldn't find any makefiles to + read in. The latter means that some makefile was found, but it + didn't contain any default goal and none was given on the command + line. GNU `make' has nothing to do in these situations. *Note + Arguments to Specify the Makefile: Makefile Arguments. + +`Makefile `XXX' was not found.' +`Included makefile `XXX' was not found.' + A makefile specified on the command line (first form) or included + (second form) was not found. + +`warning: overriding recipe for target `XXX'' +`warning: ignoring old recipe for target `XXX'' + GNU `make' allows only one recipe to be specified per target + (except for double-colon rules). If you give a recipe for a target + which already has been defined to have one, this warning is issued + and the second recipe will overwrite the first. *Note Multiple + Rules for One Target: Multiple Rules. + +`Circular XXX <- YYY dependency dropped.' + This means that `make' detected a loop in the dependency graph: + after tracing the prerequisite YYY of target XXX, and its + prerequisites, etc., one of them depended on XXX again. + +`Recursive variable `XXX' references itself (eventually). Stop.' + This means you've defined a normal (recursive) `make' variable XXX + that, when it's expanded, will refer to itself (XXX). This is not + allowed; either use simply-expanded variables (`:=') or use the + append operator (`+='). *Note How to Use Variables: Using + Variables. + +`Unterminated variable reference. Stop.' + This means you forgot to provide the proper closing parenthesis or + brace in your variable or function reference. + +`insufficient arguments to function `XXX'. Stop.' + This means you haven't provided the requisite number of arguments + for this function. See the documentation of the function for a + description of its arguments. *Note Functions for Transforming + Text: Functions. + +`missing target pattern. Stop.' +`multiple target patterns. Stop.' +`target pattern contains no `%'. Stop.' +`mixed implicit and static pattern rules. Stop.' + These are generated for malformed static pattern rules. The first + means there's no pattern in the target section of the rule; the + second means there are multiple patterns in the target section; + the third means the target doesn't contain a pattern character + (`%'); and the fourth means that all three parts of the static + pattern rule contain pattern characters (`%')-only the first two + parts should. *Note Syntax of Static Pattern Rules: Static Usage. + +`warning: -jN forced in submake: disabling jobserver mode.' + This warning and the next are generated if `make' detects error + conditions related to parallel processing on systems where + sub-`make's can communicate (*note Communicating Options to a + Sub-`make': Options/Recursion.). This warning is generated if a + recursive invocation of a `make' process is forced to have `-jN' + in its argument list (where N is greater than one). This could + happen, for example, if you set the `MAKE' environment variable to + `make -j2'. In this case, the sub-`make' doesn't communicate with + other `make' processes and will simply pretend it has two jobs of + its own. + +`warning: jobserver unavailable: using -j1. Add `+' to parent make rule.' + In order for `make' processes to communicate, the parent will pass + information to the child. Since this could result in problems if + the child process isn't actually a `make', the parent will only do + this if it thinks the child is a `make'. The parent uses the + normal algorithms to determine this (*note How the `MAKE' Variable + Works: MAKE Variable.). If the makefile is constructed such that + the parent doesn't know the child is a `make' process, then the + child will receive only part of the information necessary. In + this case, the child will generate this warning message and + proceed with its build in a sequential manner. + + + +File: make.info, Node: Complex Makefile, Next: GNU Free Documentation License, Prev: Error Messages, Up: Top + +Appendix C Complex Makefile Example +*********************************** + +Here is the makefile for the GNU `tar' program. This is a moderately +complex makefile. + + Because it is the first target, the default goal is `all'. An +interesting feature of this makefile is that `testpad.h' is a source +file automatically created by the `testpad' program, itself compiled +from `testpad.c'. + + If you type `make' or `make all', then `make' creates the `tar' +executable, the `rmt' daemon that provides remote tape access, and the +`tar.info' Info file. + + If you type `make install', then `make' not only creates `tar', +`rmt', and `tar.info', but also installs them. + + If you type `make clean', then `make' removes the `.o' files, and +the `tar', `rmt', `testpad', `testpad.h', and `core' files. + + If you type `make distclean', then `make' not only removes the same +files as does `make clean' but also the `TAGS', `Makefile', and +`config.status' files. (Although it is not evident, this makefile (and +`config.status') is generated by the user with the `configure' program, +which is provided in the `tar' distribution, but is not shown here.) + + If you type `make realclean', then `make' removes the same files as +does `make distclean' and also removes the Info files generated from +`tar.texinfo'. + + In addition, there are targets `shar' and `dist' that create +distribution kits. + + # Generated automatically from Makefile.in by configure. + # Un*x Makefile for GNU tar program. + # Copyright (C) 1991 Free Software Foundation, Inc. + + # This program is free software; you can redistribute + # it and/or modify it under the terms of the GNU + # General Public License ... + ... + ... + + SHELL = /bin/sh + + #### Start of system configuration section. #### + + srcdir = . + + # If you use gcc, you should either run the + # fixincludes script that comes with it or else use + # gcc with the -traditional option. Otherwise ioctl + # calls will be compiled incorrectly on some systems. + CC = gcc -O + YACC = bison -y + INSTALL = /usr/local/bin/install -c + INSTALLDATA = /usr/local/bin/install -c -m 644 + + # Things you might add to DEFS: + # -DSTDC_HEADERS If you have ANSI C headers and + # libraries. + # -DPOSIX If you have POSIX.1 headers and + # libraries. + # -DBSD42 If you have sys/dir.h (unless + # you use -DPOSIX), sys/file.h, + # and st_blocks in `struct stat'. + # -DUSG If you have System V/ANSI C + # string and memory functions + # and headers, sys/sysmacros.h, + # fcntl.h, getcwd, no valloc, + # and ndir.h (unless + # you use -DDIRENT). + # -DNO_MEMORY_H If USG or STDC_HEADERS but do not + # include memory.h. + # -DDIRENT If USG and you have dirent.h + # instead of ndir.h. + # -DSIGTYPE=int If your signal handlers + # return int, not void. + # -DNO_MTIO If you lack sys/mtio.h + # (magtape ioctls). + # -DNO_REMOTE If you do not have a remote shell + # or rexec. + # -DUSE_REXEC To use rexec for remote tape + # operations instead of + # forking rsh or remsh. + # -DVPRINTF_MISSING If you lack vprintf function + # (but have _doprnt). + # -DDOPRNT_MISSING If you lack _doprnt function. + # Also need to define + # -DVPRINTF_MISSING. + # -DFTIME_MISSING If you lack ftime system call. + # -DSTRSTR_MISSING If you lack strstr function. + # -DVALLOC_MISSING If you lack valloc function. + # -DMKDIR_MISSING If you lack mkdir and + # rmdir system calls. + # -DRENAME_MISSING If you lack rename system call. + # -DFTRUNCATE_MISSING If you lack ftruncate + # system call. + # -DV7 On Version 7 Unix (not + # tested in a long time). + # -DEMUL_OPEN3 If you lack a 3-argument version + # of open, and want to emulate it + # with system calls you do have. + # -DNO_OPEN3 If you lack the 3-argument open + # and want to disable the tar -k + # option instead of emulating open. + # -DXENIX If you have sys/inode.h + # and need it 94 to be included. + + DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \ + -DVPRINTF_MISSING -DBSD42 + # Set this to rtapelib.o unless you defined NO_REMOTE, + # in which case make it empty. + RTAPELIB = rtapelib.o + LIBS = + DEF_AR_FILE = /dev/rmt8 + DEFBLOCKING = 20 + + CDEBUG = -g + CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \ + -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \ + -DDEFBLOCKING=$(DEFBLOCKING) + LDFLAGS = -g + + prefix = /usr/local + # Prefix for each installed program, + # normally empty or `g'. + binprefix = + + # The directory to install tar in. + bindir = $(prefix)/bin + + # The directory to install the info files in. + infodir = $(prefix)/info + + #### End of system configuration section. #### + + SRCS_C = tar.c create.c extract.c buffer.c \ + getoldopt.c update.c gnu.c mangle.c \ + version.c list.c names.c diffarch.c \ + port.c wildmat.c getopt.c getopt1.c \ + regex.c + SRCS_Y = getdate.y + SRCS = $(SRCS_C) $(SRCS_Y) + OBJS = $(SRCS_C:.c=.o) $(SRCS_Y:.y=.o) $(RTAPELIB) + AUX = README COPYING ChangeLog Makefile.in \ + makefile.pc configure configure.in \ + tar.texinfo tar.info* texinfo.tex \ + tar.h port.h open3.h getopt.h regex.h \ + rmt.h rmt.c rtapelib.c alloca.c \ + msd_dir.h msd_dir.c tcexparg.c \ + level-0 level-1 backup-specs testpad.c + + .PHONY: all + all: tar rmt tar.info + + tar: $(OBJS) + $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) + + rmt: rmt.c + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ rmt.c + + tar.info: tar.texinfo + makeinfo tar.texinfo + + .PHONY: install + install: all + $(INSTALL) tar $(bindir)/$(binprefix)tar + -test ! -f rmt || $(INSTALL) rmt /etc/rmt + $(INSTALLDATA) $(srcdir)/tar.info* $(infodir) + + $(OBJS): tar.h port.h testpad.h + regex.o buffer.o tar.o: regex.h + # getdate.y has 8 shift/reduce conflicts. + + testpad.h: testpad + ./testpad + + testpad: testpad.o + $(CC) -o $@ testpad.o + + TAGS: $(SRCS) + etags $(SRCS) + + .PHONY: clean + clean: + rm -f *.o tar rmt testpad testpad.h core + + .PHONY: distclean + distclean: clean + rm -f TAGS Makefile config.status + + .PHONY: realclean + realclean: distclean + rm -f tar.info* + + .PHONY: shar + shar: $(SRCS) $(AUX) + shar $(SRCS) $(AUX) | compress \ + > tar-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ + -e q + version.c`.shar.Z + + .PHONY: dist + dist: $(SRCS) $(AUX) + echo tar-`sed \ + -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ + -e q + version.c` > .fname + -rm -rf `cat .fname` + mkdir `cat .fname` + ln $(SRCS) $(AUX) `cat .fname` + tar chZf `cat .fname`.tar.Z `cat .fname` + -rm -rf `cat .fname` .fname + + tar.zoo: $(SRCS) $(AUX) + -rm -rf tmp.dir + -mkdir tmp.dir + -rm tar.zoo + for X in $(SRCS) $(AUX) ; do \ + echo $$X ; \ + sed 's/$$/^M/' $$X \ + > tmp.dir/$$X ; done + cd tmp.dir ; zoo aM ../tar.zoo * + -rm -rf tmp.dir + + +File: make.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Complex Makefile, Up: Top + +C.1 GNU Free Documentation License +================================== + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + `http://fsf.org/' + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, receipt of a copy of some or all of + the same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. If the Document specifies that a proxy + can decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: make.info, Node: Concept Index, Next: Name Index, Prev: GNU Free Documentation License, Up: Top + +Index of Concepts +***************** + + +* Menu: + +* # (comments), in makefile: Makefile Contents. (line 42) +* # (comments), in recipes: Recipe Syntax. (line 29) +* #include: Automatic Prerequisites. + (line 16) +* $, in function call: Syntax of Functions. (line 6) +* $, in rules: Rule Syntax. (line 34) +* $, in variable name: Computed Names. (line 6) +* $, in variable reference: Reference. (line 6) +* %, in pattern rules: Pattern Intro. (line 9) +* %, quoting in patsubst: Text Functions. (line 26) +* %, quoting in static pattern: Static Usage. (line 37) +* %, quoting in vpath: Selective Search. (line 38) +* %, quoting with \ (backslash) <1>: Text Functions. (line 26) +* %, quoting with \ (backslash) <2>: Static Usage. (line 37) +* %, quoting with \ (backslash): Selective Search. (line 38) +* * (wildcard character): Wildcards. (line 6) +* +, and define: Canned Recipes. (line 49) +* +, and recipe execution: Instead of Execution. + (line 60) +* +, and recipes: MAKE Variable. (line 18) +* +=: Appending. (line 6) +* +=, expansion: Reading Makefiles. (line 33) +* ,v (RCS file extension): Catalogue of Rules. (line 164) +* - (in recipes): Errors. (line 19) +* -, and define: Canned Recipes. (line 49) +* --always-make: Options Summary. (line 15) +* --assume-new <1>: Options Summary. (line 248) +* --assume-new: Instead of Execution. + (line 35) +* --assume-new, and recursion: Options/Recursion. (line 22) +* --assume-old <1>: Options Summary. (line 154) +* --assume-old: Avoiding Compilation. + (line 6) +* --assume-old, and recursion: Options/Recursion. (line 22) +* --check-symlink-times: Options Summary. (line 136) +* --debug: Options Summary. (line 42) +* --directory <1>: Options Summary. (line 26) +* --directory: Recursion. (line 20) +* --directory, and --print-directory: -w Option. (line 20) +* --directory, and recursion: Options/Recursion. (line 22) +* --dry-run <1>: Options Summary. (line 146) +* --dry-run <2>: Instead of Execution. + (line 14) +* --dry-run: Echoing. (line 18) +* --environment-overrides: Options Summary. (line 78) +* --eval: Options Summary. (line 83) +* --file <1>: Options Summary. (line 90) +* --file <2>: Makefile Arguments. (line 6) +* --file: Makefile Names. (line 23) +* --file, and recursion: Options/Recursion. (line 22) +* --help: Options Summary. (line 96) +* --ignore-errors <1>: Options Summary. (line 100) +* --ignore-errors: Errors. (line 30) +* --include-dir <1>: Options Summary. (line 105) +* --include-dir: Include. (line 53) +* --jobs <1>: Options Summary. (line 112) +* --jobs: Parallel. (line 6) +* --jobs, and recursion: Options/Recursion. (line 25) +* --just-print <1>: Options Summary. (line 145) +* --just-print <2>: Instead of Execution. + (line 14) +* --just-print: Echoing. (line 18) +* --keep-going <1>: Options Summary. (line 121) +* --keep-going <2>: Testing. (line 16) +* --keep-going: Errors. (line 47) +* --load-average <1>: Options Summary. (line 128) +* --load-average: Parallel. (line 58) +* --makefile <1>: Options Summary. (line 91) +* --makefile <2>: Makefile Arguments. (line 6) +* --makefile: Makefile Names. (line 23) +* --max-load <1>: Options Summary. (line 129) +* --max-load: Parallel. (line 58) +* --new-file <1>: Options Summary. (line 247) +* --new-file: Instead of Execution. + (line 35) +* --new-file, and recursion: Options/Recursion. (line 22) +* --no-builtin-rules: Options Summary. (line 182) +* --no-builtin-variables: Options Summary. (line 195) +* --no-keep-going: Options Summary. (line 210) +* --no-print-directory <1>: Options Summary. (line 239) +* --no-print-directory: -w Option. (line 20) +* --old-file <1>: Options Summary. (line 153) +* --old-file: Avoiding Compilation. + (line 6) +* --old-file, and recursion: Options/Recursion. (line 22) +* --print-data-base: Options Summary. (line 162) +* --print-directory: Options Summary. (line 231) +* --print-directory, and --directory: -w Option. (line 20) +* --print-directory, and recursion: -w Option. (line 20) +* --print-directory, disabling: -w Option. (line 20) +* --question <1>: Options Summary. (line 174) +* --question: Instead of Execution. + (line 27) +* --quiet <1>: Options Summary. (line 205) +* --quiet: Echoing. (line 24) +* --recon <1>: Options Summary. (line 147) +* --recon <2>: Instead of Execution. + (line 14) +* --recon: Echoing. (line 18) +* --silent <1>: Options Summary. (line 204) +* --silent: Echoing. (line 24) +* --stop: Options Summary. (line 211) +* --touch <1>: Options Summary. (line 219) +* --touch: Instead of Execution. + (line 21) +* --touch, and recursion: MAKE Variable. (line 34) +* --version: Options Summary. (line 226) +* --warn-undefined-variables: Options Summary. (line 257) +* --what-if <1>: Options Summary. (line 246) +* --what-if: Instead of Execution. + (line 35) +* -B: Options Summary. (line 14) +* -b: Options Summary. (line 9) +* -C <1>: Options Summary. (line 25) +* -C: Recursion. (line 20) +* -C, and -w: -w Option. (line 20) +* -C, and recursion: Options/Recursion. (line 22) +* -d: Options Summary. (line 33) +* -e: Options Summary. (line 77) +* -e (shell flag): Automatic Prerequisites. + (line 66) +* -f <1>: Options Summary. (line 89) +* -f <2>: Makefile Arguments. (line 6) +* -f: Makefile Names. (line 23) +* -f, and recursion: Options/Recursion. (line 22) +* -h: Options Summary. (line 95) +* -I: Options Summary. (line 104) +* -i <1>: Options Summary. (line 99) +* -i: Errors. (line 30) +* -I: Include. (line 53) +* -j <1>: Options Summary. (line 111) +* -j: Parallel. (line 6) +* -j, and archive update: Archive Pitfalls. (line 6) +* -j, and recursion: Options/Recursion. (line 25) +* -k <1>: Options Summary. (line 120) +* -k <2>: Testing. (line 16) +* -k: Errors. (line 47) +* -L: Options Summary. (line 135) +* -l: Options Summary. (line 127) +* -l (library search): Libraries/Search. (line 6) +* -l (load average): Parallel. (line 58) +* -m: Options Summary. (line 10) +* -M (to compiler): Automatic Prerequisites. + (line 18) +* -MM (to GNU compiler): Automatic Prerequisites. + (line 68) +* -n <1>: Options Summary. (line 144) +* -n <2>: Instead of Execution. + (line 14) +* -n: Echoing. (line 18) +* -o <1>: Options Summary. (line 152) +* -o: Avoiding Compilation. + (line 6) +* -o, and recursion: Options/Recursion. (line 22) +* -p: Options Summary. (line 161) +* -q <1>: Options Summary. (line 173) +* -q: Instead of Execution. + (line 27) +* -R: Options Summary. (line 194) +* -r: Options Summary. (line 181) +* -S: Options Summary. (line 209) +* -s <1>: Options Summary. (line 203) +* -s: Echoing. (line 24) +* -t <1>: Options Summary. (line 218) +* -t: Instead of Execution. + (line 21) +* -t, and recursion: MAKE Variable. (line 34) +* -v: Options Summary. (line 225) +* -W: Options Summary. (line 245) +* -w: Options Summary. (line 230) +* -W: Instead of Execution. + (line 35) +* -w, and -C: -w Option. (line 20) +* -w, and recursion: -w Option. (line 20) +* -W, and recursion: Options/Recursion. (line 22) +* -w, disabling: -w Option. (line 20) +* .a (archives): Archive Suffix Rules. + (line 6) +* .C: Catalogue of Rules. (line 39) +* .c: Catalogue of Rules. (line 35) +* .cc: Catalogue of Rules. (line 39) +* .ch: Catalogue of Rules. (line 151) +* .cpp: Catalogue of Rules. (line 39) +* .d: Automatic Prerequisites. + (line 81) +* .def: Catalogue of Rules. (line 74) +* .dvi: Catalogue of Rules. (line 151) +* .F: Catalogue of Rules. (line 49) +* .f: Catalogue of Rules. (line 49) +* .info: Catalogue of Rules. (line 158) +* .l: Catalogue of Rules. (line 124) +* .LIBPATTERNS, and link libraries: Libraries/Search. (line 6) +* .ln: Catalogue of Rules. (line 146) +* .mod: Catalogue of Rules. (line 74) +* .o: Catalogue of Rules. (line 35) +* .ONESHELL, use of: One Shell. (line 6) +* .p: Catalogue of Rules. (line 45) +* .PRECIOUS intermediate files: Chained Rules. (line 56) +* .r: Catalogue of Rules. (line 49) +* .S: Catalogue of Rules. (line 82) +* .s: Catalogue of Rules. (line 79) +* .sh: Catalogue of Rules. (line 180) +* .SHELLFLAGS, value of: Choosing the Shell. (line 6) +* .sym: Catalogue of Rules. (line 74) +* .tex: Catalogue of Rules. (line 151) +* .texi: Catalogue of Rules. (line 158) +* .texinfo: Catalogue of Rules. (line 158) +* .txinfo: Catalogue of Rules. (line 158) +* .w: Catalogue of Rules. (line 151) +* .web: Catalogue of Rules. (line 151) +* .y: Catalogue of Rules. (line 120) +* :: rules (double-colon): Double-Colon. (line 6) +* := <1>: Setting. (line 6) +* :=: Flavors. (line 56) +* = <1>: Setting. (line 6) +* =: Flavors. (line 10) +* =, expansion: Reading Makefiles. (line 33) +* ? (wildcard character): Wildcards. (line 6) +* ?= <1>: Setting. (line 6) +* ?=: Flavors. (line 129) +* ?=, expansion: Reading Makefiles. (line 33) +* @ (in recipes): Echoing. (line 6) +* @, and define: Canned Recipes. (line 49) +* [...] (wildcard characters): Wildcards. (line 6) +* \ (backslash), for continuation lines: Simple Makefile. (line 40) +* \ (backslash), in recipes: Splitting Lines. (line 6) +* \ (backslash), to quote % <1>: Text Functions. (line 26) +* \ (backslash), to quote % <2>: Static Usage. (line 37) +* \ (backslash), to quote %: Selective Search. (line 38) +* __.SYMDEF: Archive Symbols. (line 6) +* abspath: File Name Functions. (line 121) +* algorithm for directory search: Search Algorithm. (line 6) +* all (standard target): Goals. (line 72) +* appending to variables: Appending. (line 6) +* ar: Implicit Variables. (line 40) +* archive: Archives. (line 6) +* archive member targets: Archive Members. (line 6) +* archive symbol directory updating: Archive Symbols. (line 6) +* archive, and -j: Archive Pitfalls. (line 6) +* archive, and parallel execution: Archive Pitfalls. (line 6) +* archive, suffix rule for: Archive Suffix Rules. + (line 6) +* Arg list too long: Options/Recursion. (line 57) +* arguments of functions: Syntax of Functions. (line 6) +* as <1>: Implicit Variables. (line 43) +* as: Catalogue of Rules. (line 79) +* assembly, rule to compile: Catalogue of Rules. (line 79) +* automatic generation of prerequisites <1>: Automatic Prerequisites. + (line 6) +* automatic generation of prerequisites: Include. (line 51) +* automatic variables: Automatic Variables. (line 6) +* automatic variables in prerequisites: Automatic Variables. (line 17) +* backquotes: Shell Function. (line 6) +* backslash (\), for continuation lines: Simple Makefile. (line 40) +* backslash (\), in recipes: Splitting Lines. (line 6) +* backslash (\), to quote % <1>: Text Functions. (line 26) +* backslash (\), to quote % <2>: Static Usage. (line 37) +* backslash (\), to quote %: Selective Search. (line 38) +* backslashes in pathnames and wildcard expansion: Wildcard Pitfall. + (line 31) +* basename: File Name Functions. (line 57) +* binary packages: Install Command Categories. + (line 80) +* broken pipe: Parallel. (line 31) +* bugs, reporting: Bugs. (line 6) +* built-in special targets: Special Targets. (line 6) +* C++, rule to compile: Catalogue of Rules. (line 39) +* C, rule to compile: Catalogue of Rules. (line 35) +* canned recipes: Canned Recipes. (line 6) +* cc <1>: Implicit Variables. (line 46) +* cc: Catalogue of Rules. (line 35) +* cd (shell command) <1>: MAKE Variable. (line 16) +* cd (shell command): Execution. (line 12) +* chains of rules: Chained Rules. (line 6) +* check (standard target): Goals. (line 114) +* clean (standard target): Goals. (line 75) +* clean target <1>: Cleanup. (line 11) +* clean target: Simple Makefile. (line 84) +* cleaning up: Cleanup. (line 6) +* clobber (standard target): Goals. (line 86) +* co <1>: Implicit Variables. (line 66) +* co: Catalogue of Rules. (line 164) +* combining rules by prerequisite: Combine By Prerequisite. + (line 6) +* command expansion: Shell Function. (line 6) +* command line variable definitions, and recursion: Options/Recursion. + (line 17) +* command line variables: Overriding. (line 6) +* commands, sequences of: Canned Recipes. (line 6) +* comments, in makefile: Makefile Contents. (line 42) +* comments, in recipes: Recipe Syntax. (line 29) +* compatibility: Features. (line 6) +* compatibility in exporting: Variables/Recursion. (line 105) +* compilation, testing: Testing. (line 6) +* computed variable name: Computed Names. (line 6) +* conditional expansion: Conditional Functions. + (line 6) +* conditional variable assignment: Flavors. (line 129) +* conditionals: Conditionals. (line 6) +* continuation lines: Simple Makefile. (line 40) +* controlling make: Make Control Functions. + (line 6) +* conventions for makefiles: Makefile Conventions. + (line 6) +* ctangle <1>: Implicit Variables. (line 103) +* ctangle: Catalogue of Rules. (line 151) +* cweave <1>: Implicit Variables. (line 97) +* cweave: Catalogue of Rules. (line 151) +* data base of make rules: Options Summary. (line 162) +* deducing recipes (implicit rules): make Deduces. (line 6) +* default directories for included makefiles: Include. (line 53) +* default goal <1>: Rules. (line 11) +* default goal: How Make Works. (line 11) +* default makefile name: Makefile Names. (line 6) +* default rules, last-resort: Last Resort. (line 6) +* define, expansion: Reading Makefiles. (line 33) +* defining variables verbatim: Multi-Line. (line 6) +* deletion of target files <1>: Interrupts. (line 6) +* deletion of target files: Errors. (line 64) +* directive: Makefile Contents. (line 28) +* directories, creating installation: Directory Variables. (line 20) +* directories, printing them: -w Option. (line 6) +* directories, updating archive symbol: Archive Symbols. (line 6) +* directory part: File Name Functions. (line 17) +* directory search (VPATH): Directory Search. (line 6) +* directory search (VPATH), and implicit rules: Implicit/Search. + (line 6) +* directory search (VPATH), and link libraries: Libraries/Search. + (line 6) +* directory search (VPATH), and recipes: Recipes/Search. (line 6) +* directory search algorithm: Search Algorithm. (line 6) +* directory search, traditional (GPATH): Search Algorithm. (line 42) +* dist (standard target): Goals. (line 106) +* distclean (standard target): Goals. (line 84) +* dollar sign ($), in function call: Syntax of Functions. (line 6) +* dollar sign ($), in rules: Rule Syntax. (line 34) +* dollar sign ($), in variable name: Computed Names. (line 6) +* dollar sign ($), in variable reference: Reference. (line 6) +* DOS, choosing a shell in: Choosing the Shell. (line 38) +* double-colon rules: Double-Colon. (line 6) +* duplicate words, removing: Text Functions. (line 155) +* E2BIG: Options/Recursion. (line 57) +* echoing of recipes: Echoing. (line 6) +* editor: Introduction. (line 22) +* Emacs (M-x compile): Errors. (line 62) +* empty recipes: Empty Recipes. (line 6) +* empty targets: Empty Targets. (line 6) +* environment: Environment. (line 6) +* environment, and recursion: Variables/Recursion. (line 6) +* environment, SHELL in: Choosing the Shell. (line 12) +* error, stopping on: Make Control Functions. + (line 11) +* errors (in recipes): Errors. (line 6) +* errors with wildcards: Wildcard Pitfall. (line 6) +* evaluating makefile syntax: Eval Function. (line 6) +* execution, in parallel: Parallel. (line 6) +* execution, instead of: Instead of Execution. + (line 6) +* execution, of recipes: Execution. (line 6) +* exit status (errors): Errors. (line 6) +* exit status of make: Running. (line 18) +* expansion, secondary: Secondary Expansion. (line 6) +* explicit rule, definition of: Makefile Contents. (line 10) +* explicit rule, expansion: Reading Makefiles. (line 77) +* explicit rules, secondary expansion of: Secondary Expansion. + (line 106) +* exporting variables: Variables/Recursion. (line 6) +* f77 <1>: Implicit Variables. (line 57) +* f77: Catalogue of Rules. (line 49) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* features of GNU make: Features. (line 6) +* features, missing: Missing. (line 6) +* file name functions: File Name Functions. (line 6) +* file name of makefile: Makefile Names. (line 6) +* file name of makefile, how to specify: Makefile Names. (line 30) +* file name prefix, adding: File Name Functions. (line 79) +* file name suffix: File Name Functions. (line 43) +* file name suffix, adding: File Name Functions. (line 68) +* file name with wildcards: Wildcards. (line 6) +* file name, abspath of: File Name Functions. (line 121) +* file name, basename of: File Name Functions. (line 57) +* file name, directory part: File Name Functions. (line 17) +* file name, nondirectory part: File Name Functions. (line 27) +* file name, realpath of: File Name Functions. (line 114) +* files, assuming new: Instead of Execution. + (line 35) +* files, assuming old: Avoiding Compilation. + (line 6) +* files, avoiding recompilation of: Avoiding Compilation. + (line 6) +* files, intermediate: Chained Rules. (line 16) +* filtering out words: Text Functions. (line 132) +* filtering words: Text Functions. (line 114) +* finding strings: Text Functions. (line 103) +* flags: Options Summary. (line 6) +* flags for compilers: Implicit Variables. (line 6) +* flavor of variable: Flavor Function. (line 6) +* flavors of variables: Flavors. (line 6) +* FORCE: Force Targets. (line 6) +* force targets: Force Targets. (line 6) +* Fortran, rule to compile: Catalogue of Rules. (line 49) +* functions: Functions. (line 6) +* functions, for controlling make: Make Control Functions. + (line 6) +* functions, for file names: File Name Functions. (line 6) +* functions, for text: Text Functions. (line 6) +* functions, syntax of: Syntax of Functions. (line 6) +* functions, user defined: Call Function. (line 6) +* g++ <1>: Implicit Variables. (line 49) +* g++: Catalogue of Rules. (line 39) +* gcc: Catalogue of Rules. (line 35) +* generating prerequisites automatically <1>: Automatic Prerequisites. + (line 6) +* generating prerequisites automatically: Include. (line 51) +* get <1>: Implicit Variables. (line 69) +* get: Catalogue of Rules. (line 173) +* globbing (wildcards): Wildcards. (line 6) +* goal: How Make Works. (line 11) +* goal, default <1>: Rules. (line 11) +* goal, default: How Make Works. (line 11) +* goal, how to specify: Goals. (line 6) +* home directory: Wildcards. (line 11) +* IEEE Standard 1003.2: Overview. (line 13) +* ifdef, expansion: Reading Makefiles. (line 67) +* ifeq, expansion: Reading Makefiles. (line 67) +* ifndef, expansion: Reading Makefiles. (line 67) +* ifneq, expansion: Reading Makefiles. (line 67) +* implicit rule: Implicit Rules. (line 6) +* implicit rule, and directory search: Implicit/Search. (line 6) +* implicit rule, and VPATH: Implicit/Search. (line 6) +* implicit rule, definition of: Makefile Contents. (line 16) +* implicit rule, expansion: Reading Makefiles. (line 77) +* implicit rule, how to use: Using Implicit. (line 6) +* implicit rule, introduction to: make Deduces. (line 6) +* implicit rule, predefined: Catalogue of Rules. (line 6) +* implicit rule, search algorithm: Implicit Rule Search. + (line 6) +* implicit rules, secondary expansion of: Secondary Expansion. + (line 146) +* included makefiles, default directories: Include. (line 53) +* including (MAKEFILE_LIST variable): Special Variables. (line 8) +* including (MAKEFILES variable): MAKEFILES Variable. (line 6) +* including other makefiles: Include. (line 6) +* incompatibilities: Missing. (line 6) +* Info, rule to format: Catalogue of Rules. (line 158) +* inheritance, suppressing: Suppressing Inheritance. + (line 6) +* install (standard target): Goals. (line 92) +* installation directories, creating: Directory Variables. (line 20) +* installations, staged: DESTDIR. (line 6) +* intermediate files: Chained Rules. (line 16) +* intermediate files, preserving: Chained Rules. (line 46) +* intermediate targets, explicit: Special Targets. (line 44) +* interrupt: Interrupts. (line 6) +* job slots: Parallel. (line 6) +* job slots, and recursion: Options/Recursion. (line 25) +* jobs, limiting based on load: Parallel. (line 58) +* joining lists of words: File Name Functions. (line 90) +* killing (interruption): Interrupts. (line 6) +* last-resort default rules: Last Resort. (line 6) +* ld: Catalogue of Rules. (line 86) +* lex <1>: Implicit Variables. (line 73) +* lex: Catalogue of Rules. (line 124) +* Lex, rule to run: Catalogue of Rules. (line 124) +* libraries for linking, directory search: Libraries/Search. (line 6) +* library archive, suffix rule for: Archive Suffix Rules. + (line 6) +* limiting jobs based on load: Parallel. (line 58) +* link libraries, and directory search: Libraries/Search. (line 6) +* link libraries, patterns matching: Libraries/Search. (line 6) +* linking, predefined rule for: Catalogue of Rules. (line 86) +* lint <1>: Implicit Variables. (line 80) +* lint: Catalogue of Rules. (line 146) +* lint, rule to run: Catalogue of Rules. (line 146) +* list of all prerequisites: Automatic Variables. (line 61) +* list of changed prerequisites: Automatic Variables. (line 51) +* load average: Parallel. (line 58) +* loops in variable expansion: Flavors. (line 44) +* lpr (shell command) <1>: Empty Targets. (line 25) +* lpr (shell command): Wildcard Examples. (line 21) +* m2c <1>: Implicit Variables. (line 60) +* m2c: Catalogue of Rules. (line 74) +* macro: Using Variables. (line 10) +* make depend: Automatic Prerequisites. + (line 37) +* makefile: Introduction. (line 7) +* makefile name: Makefile Names. (line 6) +* makefile name, how to specify: Makefile Names. (line 30) +* makefile rule parts: Rule Introduction. (line 6) +* makefile syntax, evaluating: Eval Function. (line 6) +* makefile, and MAKEFILES variable: MAKEFILES Variable. (line 6) +* makefile, conventions for: Makefile Conventions. + (line 6) +* makefile, how make processes: How Make Works. (line 6) +* makefile, how to write: Makefiles. (line 6) +* makefile, including: Include. (line 6) +* makefile, overriding: Overriding Makefiles. + (line 6) +* makefile, parsing: Reading Makefiles. (line 6) +* makefile, remaking of: Remaking Makefiles. (line 6) +* makefile, simple: Simple Makefile. (line 6) +* makefiles, and MAKEFILE_LIST variable: Special Variables. (line 8) +* makefiles, and special variables: Special Variables. (line 6) +* makeinfo <1>: Implicit Variables. (line 84) +* makeinfo: Catalogue of Rules. (line 158) +* match-anything rule: Match-Anything Rules. + (line 6) +* match-anything rule, used to override: Overriding Makefiles. + (line 12) +* missing features: Missing. (line 6) +* mistakes with wildcards: Wildcard Pitfall. (line 6) +* modified variable reference: Substitution Refs. (line 6) +* Modula-2, rule to compile: Catalogue of Rules. (line 74) +* mostlyclean (standard target): Goals. (line 78) +* multi-line variable definition: Multi-Line. (line 6) +* multiple rules for one target: Multiple Rules. (line 6) +* multiple rules for one target (::): Double-Colon. (line 6) +* multiple targets: Multiple Targets. (line 6) +* multiple targets, in pattern rule: Pattern Intro. (line 53) +* name of makefile: Makefile Names. (line 6) +* name of makefile, how to specify: Makefile Names. (line 30) +* nested variable reference: Computed Names. (line 6) +* newline, quoting, in makefile: Simple Makefile. (line 40) +* newline, quoting, in recipes: Splitting Lines. (line 6) +* nondirectory part: File Name Functions. (line 27) +* normal prerequisites: Prerequisite Types. (line 6) +* OBJ: Variables Simplify. (line 20) +* obj: Variables Simplify. (line 20) +* OBJECTS: Variables Simplify. (line 20) +* objects: Variables Simplify. (line 14) +* OBJS: Variables Simplify. (line 20) +* objs: Variables Simplify. (line 20) +* old-fashioned suffix rules: Suffix Rules. (line 6) +* options: Options Summary. (line 6) +* options, and recursion: Options/Recursion. (line 6) +* options, setting from environment: Options/Recursion. (line 81) +* options, setting in makefiles: Options/Recursion. (line 81) +* order of pattern rules: Pattern Match. (line 30) +* order-only prerequisites: Prerequisite Types. (line 6) +* origin of variable: Origin Function. (line 6) +* overriding makefiles: Overriding Makefiles. + (line 6) +* overriding variables with arguments: Overriding. (line 6) +* overriding with override: Override Directive. (line 6) +* parallel execution: Parallel. (line 6) +* parallel execution, and archive update: Archive Pitfalls. (line 6) +* parallel execution, overriding: Special Targets. (line 130) +* parts of makefile rule: Rule Introduction. (line 6) +* Pascal, rule to compile: Catalogue of Rules. (line 45) +* pattern rule: Pattern Intro. (line 6) +* pattern rule, expansion: Reading Makefiles. (line 77) +* pattern rules, order of: Pattern Match. (line 30) +* pattern rules, static (not implicit): Static Pattern. (line 6) +* pattern rules, static, syntax of: Static Usage. (line 6) +* pattern-specific variables: Pattern-specific. (line 6) +* pc <1>: Implicit Variables. (line 63) +* pc: Catalogue of Rules. (line 45) +* phony targets: Phony Targets. (line 6) +* phony targets and recipe execution: Instead of Execution. + (line 68) +* pitfalls of wildcards: Wildcard Pitfall. (line 6) +* portability: Features. (line 6) +* POSIX: Overview. (line 13) +* POSIX-conforming mode, setting: Special Targets. (line 143) +* POSIX.2: Options/Recursion. (line 60) +* post-installation commands: Install Command Categories. + (line 6) +* pre-installation commands: Install Command Categories. + (line 6) +* precious targets: Special Targets. (line 29) +* predefined rules and variables, printing: Options Summary. (line 162) +* prefix, adding: File Name Functions. (line 79) +* prerequisite: Rules. (line 6) +* prerequisite pattern, implicit: Pattern Intro. (line 22) +* prerequisite pattern, static (not implicit): Static Usage. (line 30) +* prerequisite types: Prerequisite Types. (line 6) +* prerequisite, expansion: Reading Makefiles. (line 77) +* prerequisites: Rule Syntax. (line 48) +* prerequisites, and automatic variables: Automatic Variables. + (line 17) +* prerequisites, automatic generation <1>: Automatic Prerequisites. + (line 6) +* prerequisites, automatic generation: Include. (line 51) +* prerequisites, introduction to: Rule Introduction. (line 8) +* prerequisites, list of all: Automatic Variables. (line 61) +* prerequisites, list of changed: Automatic Variables. (line 51) +* prerequisites, normal: Prerequisite Types. (line 6) +* prerequisites, order-only: Prerequisite Types. (line 6) +* prerequisites, varying (static pattern): Static Pattern. (line 6) +* preserving intermediate files: Chained Rules. (line 46) +* preserving with .PRECIOUS <1>: Chained Rules. (line 56) +* preserving with .PRECIOUS: Special Targets. (line 29) +* preserving with .SECONDARY: Special Targets. (line 49) +* print (standard target): Goals. (line 97) +* print target <1>: Empty Targets. (line 25) +* print target: Wildcard Examples. (line 21) +* printing directories: -w Option. (line 6) +* printing messages: Make Control Functions. + (line 43) +* printing of recipes: Echoing. (line 6) +* printing user warnings: Make Control Functions. + (line 35) +* problems and bugs, reporting: Bugs. (line 6) +* problems with wildcards: Wildcard Pitfall. (line 6) +* processing a makefile: How Make Works. (line 6) +* question mode: Instead of Execution. + (line 27) +* quoting %, in patsubst: Text Functions. (line 26) +* quoting %, in static pattern: Static Usage. (line 37) +* quoting %, in vpath: Selective Search. (line 38) +* quoting newline, in makefile: Simple Makefile. (line 40) +* quoting newline, in recipes: Splitting Lines. (line 6) +* Ratfor, rule to compile: Catalogue of Rules. (line 49) +* RCS, rule to extract from: Catalogue of Rules. (line 164) +* reading makefiles: Reading Makefiles. (line 6) +* README: Makefile Names. (line 9) +* realclean (standard target): Goals. (line 85) +* realpath: File Name Functions. (line 114) +* recipe: Simple Makefile. (line 73) +* recipe execution, single invocation: Special Targets. (line 137) +* recipe lines, single shell: One Shell. (line 6) +* recipe syntax: Recipe Syntax. (line 6) +* recipe, execution: Execution. (line 6) +* recipes <1>: Recipes. (line 6) +* recipes: Rule Syntax. (line 26) +* recipes setting shell variables: Execution. (line 12) +* recipes, and directory search: Recipes/Search. (line 6) +* recipes, backslash (\) in: Splitting Lines. (line 6) +* recipes, canned: Canned Recipes. (line 6) +* recipes, comments in: Recipe Syntax. (line 29) +* recipes, echoing: Echoing. (line 6) +* recipes, empty: Empty Recipes. (line 6) +* recipes, errors in: Errors. (line 6) +* recipes, execution in parallel: Parallel. (line 6) +* recipes, how to write: Recipes. (line 6) +* recipes, instead of executing: Instead of Execution. + (line 6) +* recipes, introduction to: Rule Introduction. (line 8) +* recipes, quoting newlines in: Splitting Lines. (line 6) +* recipes, splitting: Splitting Lines. (line 6) +* recipes, using variables in: Variables in Recipes. + (line 6) +* recompilation: Introduction. (line 22) +* recompilation, avoiding: Avoiding Compilation. + (line 6) +* recording events with empty targets: Empty Targets. (line 6) +* recursion: Recursion. (line 6) +* recursion, and -C: Options/Recursion. (line 22) +* recursion, and -f: Options/Recursion. (line 22) +* recursion, and -j: Options/Recursion. (line 25) +* recursion, and -o: Options/Recursion. (line 22) +* recursion, and -t: MAKE Variable. (line 34) +* recursion, and -w: -w Option. (line 20) +* recursion, and -W: Options/Recursion. (line 22) +* recursion, and command line variable definitions: Options/Recursion. + (line 17) +* recursion, and environment: Variables/Recursion. (line 6) +* recursion, and MAKE variable: MAKE Variable. (line 6) +* recursion, and MAKEFILES variable: MAKEFILES Variable. (line 15) +* recursion, and options: Options/Recursion. (line 6) +* recursion, and printing directories: -w Option. (line 6) +* recursion, and variables: Variables/Recursion. (line 6) +* recursion, level of: Variables/Recursion. (line 115) +* recursive variable expansion <1>: Flavors. (line 6) +* recursive variable expansion: Using Variables. (line 6) +* recursively expanded variables: Flavors. (line 6) +* reference to variables <1>: Advanced. (line 6) +* reference to variables: Reference. (line 6) +* relinking: How Make Works. (line 46) +* remaking makefiles: Remaking Makefiles. (line 6) +* removal of target files <1>: Interrupts. (line 6) +* removal of target files: Errors. (line 64) +* removing duplicate words: Text Functions. (line 155) +* removing targets on failure: Special Targets. (line 64) +* removing, to clean up: Cleanup. (line 6) +* reporting bugs: Bugs. (line 6) +* rm: Implicit Variables. (line 106) +* rm (shell command) <1>: Errors. (line 27) +* rm (shell command) <2>: Phony Targets. (line 20) +* rm (shell command) <3>: Wildcard Examples. (line 12) +* rm (shell command): Simple Makefile. (line 84) +* rule prerequisites: Rule Syntax. (line 48) +* rule syntax: Rule Syntax. (line 6) +* rule targets: Rule Syntax. (line 18) +* rule, double-colon (::): Double-Colon. (line 6) +* rule, explicit, definition of: Makefile Contents. (line 10) +* rule, how to write: Rules. (line 6) +* rule, implicit: Implicit Rules. (line 6) +* rule, implicit, and directory search: Implicit/Search. (line 6) +* rule, implicit, and VPATH: Implicit/Search. (line 6) +* rule, implicit, chains of: Chained Rules. (line 6) +* rule, implicit, definition of: Makefile Contents. (line 16) +* rule, implicit, how to use: Using Implicit. (line 6) +* rule, implicit, introduction to: make Deduces. (line 6) +* rule, implicit, predefined: Catalogue of Rules. (line 6) +* rule, introduction to: Rule Introduction. (line 6) +* rule, multiple for one target: Multiple Rules. (line 6) +* rule, no recipe or prerequisites: Force Targets. (line 6) +* rule, pattern: Pattern Intro. (line 6) +* rule, static pattern: Static Pattern. (line 6) +* rule, static pattern versus implicit: Static versus Implicit. + (line 6) +* rule, with multiple targets: Multiple Targets. (line 6) +* rules, and $: Rule Syntax. (line 34) +* s. (SCCS file prefix): Catalogue of Rules. (line 173) +* SCCS, rule to extract from: Catalogue of Rules. (line 173) +* search algorithm, implicit rule: Implicit Rule Search. + (line 6) +* search path for prerequisites (VPATH): Directory Search. (line 6) +* search path for prerequisites (VPATH), and implicit rules: Implicit/Search. + (line 6) +* search path for prerequisites (VPATH), and link libraries: Libraries/Search. + (line 6) +* searching for strings: Text Functions. (line 103) +* secondary expansion: Secondary Expansion. (line 6) +* secondary expansion and explicit rules: Secondary Expansion. + (line 106) +* secondary expansion and implicit rules: Secondary Expansion. + (line 146) +* secondary expansion and static pattern rules: Secondary Expansion. + (line 138) +* secondary files: Chained Rules. (line 46) +* secondary targets: Special Targets. (line 49) +* sed (shell command): Automatic Prerequisites. + (line 73) +* selecting a word: Text Functions. (line 159) +* selecting word lists: Text Functions. (line 168) +* sequences of commands: Canned Recipes. (line 6) +* setting options from environment: Options/Recursion. (line 81) +* setting options in makefiles: Options/Recursion. (line 81) +* setting variables: Setting. (line 6) +* several rules for one target: Multiple Rules. (line 6) +* several targets in a rule: Multiple Targets. (line 6) +* shar (standard target): Goals. (line 103) +* shell command, function for: Shell Function. (line 6) +* shell file name pattern (in include): Include. (line 13) +* shell variables, setting in recipes: Execution. (line 12) +* shell wildcards (in include): Include. (line 13) +* shell, choosing the: Choosing the Shell. (line 6) +* SHELL, exported value: Variables/Recursion. (line 23) +* SHELL, import from environment: Environment. (line 37) +* shell, in DOS and Windows: Choosing the Shell. (line 38) +* SHELL, MS-DOS specifics: Choosing the Shell. (line 44) +* SHELL, value of: Choosing the Shell. (line 6) +* signal: Interrupts. (line 6) +* silent operation: Echoing. (line 6) +* simple makefile: Simple Makefile. (line 6) +* simple variable expansion: Using Variables. (line 6) +* simplifying with variables: Variables Simplify. (line 6) +* simply expanded variables: Flavors. (line 56) +* sorting words: Text Functions. (line 146) +* spaces, in variable values: Flavors. (line 103) +* spaces, stripping: Text Functions. (line 80) +* special targets: Special Targets. (line 6) +* special variables: Special Variables. (line 6) +* specifying makefile name: Makefile Names. (line 30) +* splitting recipes: Splitting Lines. (line 6) +* staged installs: DESTDIR. (line 6) +* standard input: Parallel. (line 31) +* standards conformance: Overview. (line 13) +* standards for makefiles: Makefile Conventions. + (line 6) +* static pattern rule: Static Pattern. (line 6) +* static pattern rule, syntax of: Static Usage. (line 6) +* static pattern rule, versus implicit: Static versus Implicit. + (line 6) +* static pattern rules, secondary expansion of: Secondary Expansion. + (line 138) +* stem <1>: Pattern Match. (line 6) +* stem: Static Usage. (line 17) +* stem, shortest: Pattern Match. (line 38) +* stem, variable for: Automatic Variables. (line 77) +* stopping make: Make Control Functions. + (line 11) +* strings, searching for: Text Functions. (line 103) +* stripping whitespace: Text Functions. (line 80) +* sub-make: Variables/Recursion. (line 6) +* subdirectories, recursion for: Recursion. (line 6) +* substitution variable reference: Substitution Refs. (line 6) +* suffix rule: Suffix Rules. (line 6) +* suffix rule, for archive: Archive Suffix Rules. + (line 6) +* suffix, adding: File Name Functions. (line 68) +* suffix, function to find: File Name Functions. (line 43) +* suffix, substituting in variables: Substitution Refs. (line 6) +* suppressing inheritance: Suppressing Inheritance. + (line 6) +* switches: Options Summary. (line 6) +* symbol directories, updating archive: Archive Symbols. (line 6) +* syntax of recipe: Recipe Syntax. (line 6) +* syntax of rules: Rule Syntax. (line 6) +* tab character (in commands): Rule Syntax. (line 26) +* tabs in rules: Rule Introduction. (line 21) +* TAGS (standard target): Goals. (line 111) +* tangle <1>: Implicit Variables. (line 100) +* tangle: Catalogue of Rules. (line 151) +* tar (standard target): Goals. (line 100) +* target: Rules. (line 6) +* target pattern, implicit: Pattern Intro. (line 9) +* target pattern, static (not implicit): Static Usage. (line 17) +* target, deleting on error: Errors. (line 64) +* target, deleting on interrupt: Interrupts. (line 6) +* target, expansion: Reading Makefiles. (line 77) +* target, multiple in pattern rule: Pattern Intro. (line 53) +* target, multiple rules for one: Multiple Rules. (line 6) +* target, touching: Instead of Execution. + (line 21) +* target-specific variables: Target-specific. (line 6) +* targets: Rule Syntax. (line 18) +* targets without a file: Phony Targets. (line 6) +* targets, built-in special: Special Targets. (line 6) +* targets, empty: Empty Targets. (line 6) +* targets, force: Force Targets. (line 6) +* targets, introduction to: Rule Introduction. (line 8) +* targets, multiple: Multiple Targets. (line 6) +* targets, phony: Phony Targets. (line 6) +* terminal rule: Match-Anything Rules. + (line 6) +* test (standard target): Goals. (line 115) +* testing compilation: Testing. (line 6) +* tex <1>: Implicit Variables. (line 87) +* tex: Catalogue of Rules. (line 151) +* TeX, rule to run: Catalogue of Rules. (line 151) +* texi2dvi <1>: Implicit Variables. (line 91) +* texi2dvi: Catalogue of Rules. (line 158) +* Texinfo, rule to format: Catalogue of Rules. (line 158) +* tilde (~): Wildcards. (line 11) +* touch (shell command) <1>: Empty Targets. (line 25) +* touch (shell command): Wildcard Examples. (line 21) +* touching files: Instead of Execution. + (line 21) +* traditional directory search (GPATH): Search Algorithm. (line 42) +* types of prerequisites: Prerequisite Types. (line 6) +* undefined variables, warning message: Options Summary. (line 257) +* undefining variable: Undefine Directive. (line 6) +* updating archive symbol directories: Archive Symbols. (line 6) +* updating makefiles: Remaking Makefiles. (line 6) +* user defined functions: Call Function. (line 6) +* value: Using Variables. (line 6) +* value, how a variable gets it: Values. (line 6) +* variable: Using Variables. (line 6) +* variable definition: Makefile Contents. (line 22) +* variable references in recipes: Variables in Recipes. + (line 6) +* variables: Variables Simplify. (line 6) +* variables, $ in name: Computed Names. (line 6) +* variables, and implicit rule: Automatic Variables. (line 6) +* variables, appending to: Appending. (line 6) +* variables, automatic: Automatic Variables. (line 6) +* variables, command line: Overriding. (line 6) +* variables, command line, and recursion: Options/Recursion. (line 17) +* variables, computed names: Computed Names. (line 6) +* variables, conditional assignment: Flavors. (line 129) +* variables, defining verbatim: Multi-Line. (line 6) +* variables, environment <1>: Environment. (line 6) +* variables, environment: Variables/Recursion. (line 6) +* variables, exporting: Variables/Recursion. (line 6) +* variables, flavor of: Flavor Function. (line 6) +* variables, flavors: Flavors. (line 6) +* variables, how they get their values: Values. (line 6) +* variables, how to reference: Reference. (line 6) +* variables, loops in expansion: Flavors. (line 44) +* variables, modified reference: Substitution Refs. (line 6) +* variables, multi-line: Multi-Line. (line 6) +* variables, nested references: Computed Names. (line 6) +* variables, origin of: Origin Function. (line 6) +* variables, overriding: Override Directive. (line 6) +* variables, overriding with arguments: Overriding. (line 6) +* variables, pattern-specific: Pattern-specific. (line 6) +* variables, recursively expanded: Flavors. (line 6) +* variables, setting: Setting. (line 6) +* variables, simply expanded: Flavors. (line 56) +* variables, spaces in values: Flavors. (line 103) +* variables, substituting suffix in: Substitution Refs. (line 6) +* variables, substitution reference: Substitution Refs. (line 6) +* variables, target-specific: Target-specific. (line 6) +* variables, unexpanded value: Value Function. (line 6) +* variables, warning for undefined: Options Summary. (line 257) +* varying prerequisites: Static Pattern. (line 6) +* verbatim variable definition: Multi-Line. (line 6) +* vpath: Directory Search. (line 6) +* VPATH, and implicit rules: Implicit/Search. (line 6) +* VPATH, and link libraries: Libraries/Search. (line 6) +* warnings, printing: Make Control Functions. + (line 35) +* weave <1>: Implicit Variables. (line 94) +* weave: Catalogue of Rules. (line 151) +* Web, rule to run: Catalogue of Rules. (line 151) +* what if: Instead of Execution. + (line 35) +* whitespace, in variable values: Flavors. (line 103) +* whitespace, stripping: Text Functions. (line 80) +* wildcard: Wildcards. (line 6) +* wildcard pitfalls: Wildcard Pitfall. (line 6) +* wildcard, function: File Name Functions. (line 107) +* wildcard, in archive member: Archive Members. (line 36) +* wildcard, in include: Include. (line 13) +* wildcards and MS-DOS/MS-Windows backslashes: Wildcard Pitfall. + (line 31) +* Windows, choosing a shell in: Choosing the Shell. (line 38) +* word, selecting a: Text Functions. (line 159) +* words, extracting first: Text Functions. (line 184) +* words, extracting last: Text Functions. (line 197) +* words, filtering: Text Functions. (line 114) +* words, filtering out: Text Functions. (line 132) +* words, finding number: Text Functions. (line 180) +* words, iterating over: Foreach Function. (line 6) +* words, joining lists: File Name Functions. (line 90) +* words, removing duplicates: Text Functions. (line 155) +* words, selecting lists of: Text Functions. (line 168) +* writing recipes: Recipes. (line 6) +* writing rules: Rules. (line 6) +* yacc <1>: Implicit Variables. (line 77) +* yacc <2>: Catalogue of Rules. (line 120) +* yacc: Canned Recipes. (line 18) +* Yacc, rule to run: Catalogue of Rules. (line 120) +* ~ (tilde): Wildcards. (line 11) + + +File: make.info, Node: Name Index, Prev: Concept Index, Up: Top + +Index of Functions, Variables, & Directives +******************************************* + + +* Menu: + +* $%: Automatic Variables. (line 37) +* $(%D): Automatic Variables. (line 129) +* $(%F): Automatic Variables. (line 130) +* $(*D): Automatic Variables. (line 124) +* $(*F): Automatic Variables. (line 125) +* $(+D): Automatic Variables. (line 147) +* $(+F): Automatic Variables. (line 148) +* $(<D): Automatic Variables. (line 137) +* $(<F): Automatic Variables. (line 138) +* $(?D): Automatic Variables. (line 153) +* $(?F): Automatic Variables. (line 154) +* $(@D): Automatic Variables. (line 113) +* $(@F): Automatic Variables. (line 119) +* $(^D): Automatic Variables. (line 142) +* $(^F): Automatic Variables. (line 143) +* $*: Automatic Variables. (line 73) +* $*, and static pattern: Static Usage. (line 81) +* $+: Automatic Variables. (line 63) +* $<: Automatic Variables. (line 43) +* $?: Automatic Variables. (line 48) +* $@: Automatic Variables. (line 30) +* $^: Automatic Variables. (line 53) +* $|: Automatic Variables. (line 69) +* % (automatic variable): Automatic Variables. (line 37) +* %D (automatic variable): Automatic Variables. (line 129) +* %F (automatic variable): Automatic Variables. (line 130) +* * (automatic variable): Automatic Variables. (line 73) +* * (automatic variable), unsupported bizarre usage: Missing. (line 44) +* *D (automatic variable): Automatic Variables. (line 124) +* *F (automatic variable): Automatic Variables. (line 125) +* + (automatic variable): Automatic Variables. (line 63) +* +D (automatic variable): Automatic Variables. (line 147) +* +F (automatic variable): Automatic Variables. (line 148) +* .DEFAULT <1>: Last Resort. (line 23) +* .DEFAULT: Special Targets. (line 20) +* .DEFAULT, and empty recipes: Empty Recipes. (line 16) +* .DEFAULT_GOAL (define default goal): Special Variables. (line 34) +* .DELETE_ON_ERROR <1>: Errors. (line 64) +* .DELETE_ON_ERROR: Special Targets. (line 63) +* .EXPORT_ALL_VARIABLES <1>: Variables/Recursion. (line 99) +* .EXPORT_ALL_VARIABLES: Special Targets. (line 124) +* .FEATURES (list of supported features): Special Variables. (line 102) +* .IGNORE <1>: Errors. (line 30) +* .IGNORE: Special Targets. (line 69) +* .INCLUDE_DIRS (list of include directories): Special Variables. + (line 135) +* .INTERMEDIATE: Special Targets. (line 43) +* .LIBPATTERNS: Libraries/Search. (line 6) +* .LOW_RESOLUTION_TIME: Special Targets. (line 81) +* .NOTPARALLEL: Special Targets. (line 129) +* .ONESHELL <1>: One Shell. (line 6) +* .ONESHELL: Special Targets. (line 136) +* .PHONY <1>: Special Targets. (line 8) +* .PHONY: Phony Targets. (line 22) +* .POSIX <1>: Options/Recursion. (line 60) +* .POSIX: Special Targets. (line 142) +* .PRECIOUS <1>: Interrupts. (line 22) +* .PRECIOUS: Special Targets. (line 28) +* .RECIPEPREFIX (change the recipe prefix character): Special Variables. + (line 80) +* .SECONDARY: Special Targets. (line 48) +* .SECONDEXPANSION <1>: Special Targets. (line 57) +* .SECONDEXPANSION: Secondary Expansion. (line 6) +* .SHELLFLAGS: Choosing the Shell. (line 6) +* .SILENT <1>: Echoing. (line 24) +* .SILENT: Special Targets. (line 111) +* .SUFFIXES <1>: Suffix Rules. (line 61) +* .SUFFIXES: Special Targets. (line 15) +* .VARIABLES (list of variables): Special Variables. (line 93) +* /usr/gnu/include: Include. (line 53) +* /usr/include: Include. (line 53) +* /usr/local/include: Include. (line 53) +* < (automatic variable): Automatic Variables. (line 43) +* <D (automatic variable): Automatic Variables. (line 137) +* <F (automatic variable): Automatic Variables. (line 138) +* ? (automatic variable): Automatic Variables. (line 48) +* ?D (automatic variable): Automatic Variables. (line 153) +* ?F (automatic variable): Automatic Variables. (line 154) +* @ (automatic variable): Automatic Variables. (line 30) +* @D (automatic variable): Automatic Variables. (line 113) +* @F (automatic variable): Automatic Variables. (line 119) +* ^ (automatic variable): Automatic Variables. (line 53) +* ^D (automatic variable): Automatic Variables. (line 142) +* ^F (automatic variable): Automatic Variables. (line 143) +* abspath: File Name Functions. (line 121) +* addprefix: File Name Functions. (line 79) +* addsuffix: File Name Functions. (line 68) +* and: Conditional Functions. + (line 45) +* AR: Implicit Variables. (line 40) +* ARFLAGS: Implicit Variables. (line 113) +* AS: Implicit Variables. (line 43) +* ASFLAGS: Implicit Variables. (line 116) +* basename: File Name Functions. (line 57) +* bindir: Directory Variables. (line 57) +* call: Call Function. (line 6) +* CC: Implicit Variables. (line 46) +* CFLAGS: Implicit Variables. (line 120) +* CO: Implicit Variables. (line 66) +* COFLAGS: Implicit Variables. (line 126) +* COMSPEC: Choosing the Shell. (line 41) +* CPP: Implicit Variables. (line 52) +* CPPFLAGS: Implicit Variables. (line 129) +* CTANGLE: Implicit Variables. (line 103) +* CURDIR: Recursion. (line 28) +* CWEAVE: Implicit Variables. (line 97) +* CXX: Implicit Variables. (line 49) +* CXXFLAGS: Implicit Variables. (line 123) +* define: Multi-Line. (line 6) +* DESTDIR: DESTDIR. (line 6) +* dir: File Name Functions. (line 17) +* else: Conditional Syntax. (line 6) +* endef: Multi-Line. (line 6) +* endif: Conditional Syntax. (line 6) +* error: Make Control Functions. + (line 11) +* eval: Eval Function. (line 6) +* exec_prefix: Directory Variables. (line 39) +* export: Variables/Recursion. (line 40) +* FC: Implicit Variables. (line 56) +* FFLAGS: Implicit Variables. (line 133) +* filter: Text Functions. (line 114) +* filter-out: Text Functions. (line 132) +* findstring: Text Functions. (line 103) +* firstword: Text Functions. (line 184) +* flavor: Flavor Function. (line 6) +* foreach: Foreach Function. (line 6) +* GET: Implicit Variables. (line 69) +* GFLAGS: Implicit Variables. (line 136) +* GNUmakefile: Makefile Names. (line 7) +* GPATH: Search Algorithm. (line 48) +* if: Conditional Functions. + (line 6) +* ifdef: Conditional Syntax. (line 6) +* ifeq: Conditional Syntax. (line 6) +* ifndef: Conditional Syntax. (line 6) +* ifneq: Conditional Syntax. (line 6) +* include: Include. (line 6) +* info: Make Control Functions. + (line 43) +* join: File Name Functions. (line 90) +* lastword: Text Functions. (line 197) +* LDFLAGS: Implicit Variables. (line 139) +* LEX: Implicit Variables. (line 72) +* LFLAGS: Implicit Variables. (line 143) +* libexecdir: Directory Variables. (line 70) +* LINT: Implicit Variables. (line 80) +* LINTFLAGS: Implicit Variables. (line 155) +* M2C: Implicit Variables. (line 60) +* MAKE <1>: Flavors. (line 84) +* MAKE: MAKE Variable. (line 6) +* MAKE_RESTARTS (number of times make has restarted): Special Variables. + (line 73) +* MAKE_VERSION: Features. (line 197) +* MAKECMDGOALS: Goals. (line 30) +* makefile: Makefile Names. (line 7) +* Makefile: Makefile Names. (line 7) +* MAKEFILE_LIST (list of parsed makefiles): Special Variables. + (line 8) +* MAKEFILES <1>: Variables/Recursion. (line 127) +* MAKEFILES: MAKEFILES Variable. (line 6) +* MAKEFLAGS: Options/Recursion. (line 6) +* MAKEINFO: Implicit Variables. (line 83) +* MAKELEVEL <1>: Flavors. (line 84) +* MAKELEVEL: Variables/Recursion. (line 115) +* MAKEOVERRIDES: Options/Recursion. (line 49) +* MAKESHELL (MS-DOS alternative to SHELL): Choosing the Shell. + (line 27) +* MFLAGS: Options/Recursion. (line 65) +* notdir: File Name Functions. (line 27) +* or: Conditional Functions. + (line 37) +* origin: Origin Function. (line 6) +* OUTPUT_OPTION: Catalogue of Rules. (line 202) +* override: Override Directive. (line 6) +* patsubst <1>: Text Functions. (line 18) +* patsubst: Substitution Refs. (line 28) +* PC: Implicit Variables. (line 63) +* PFLAGS: Implicit Variables. (line 149) +* prefix: Directory Variables. (line 29) +* private: Suppressing Inheritance. + (line 6) +* realpath: File Name Functions. (line 114) +* RFLAGS: Implicit Variables. (line 152) +* RM: Implicit Variables. (line 106) +* sbindir: Directory Variables. (line 63) +* shell: Shell Function. (line 6) +* SHELL: Choosing the Shell. (line 6) +* SHELL (recipe execution): Execution. (line 6) +* sort: Text Functions. (line 146) +* strip: Text Functions. (line 80) +* subst <1>: Text Functions. (line 9) +* subst: Multiple Targets. (line 28) +* suffix: File Name Functions. (line 43) +* SUFFIXES: Suffix Rules. (line 81) +* TANGLE: Implicit Variables. (line 100) +* TEX: Implicit Variables. (line 87) +* TEXI2DVI: Implicit Variables. (line 90) +* undefine: Undefine Directive. (line 6) +* unexport: Variables/Recursion. (line 45) +* value: Value Function. (line 6) +* vpath: Selective Search. (line 6) +* VPATH: General Search. (line 6) +* vpath: Directory Search. (line 6) +* VPATH: Directory Search. (line 6) +* warning: Make Control Functions. + (line 35) +* WEAVE: Implicit Variables. (line 94) +* wildcard <1>: File Name Functions. (line 107) +* wildcard: Wildcard Function. (line 6) +* word: Text Functions. (line 159) +* wordlist: Text Functions. (line 168) +* words: Text Functions. (line 180) +* YACC: Implicit Variables. (line 76) +* YFLAGS: Implicit Variables. (line 146) +* | (automatic variable): Automatic Variables. (line 69) + + diff --git a/doc/make.texi b/doc/make.texi new file mode 100644 index 0000000..fc7e8a3 --- /dev/null +++ b/doc/make.texi @@ -0,0 +1,11458 @@ +\input texinfo @c -*- Texinfo -*- +@c %**start of header +@setfilename make.info + +@include version.texi +@set EDITION 0.71 +@set RCSID $Id: make.texi,v 1.66 2010/07/19 07:10:54 psmith Exp $ + +@settitle GNU @code{make} +@setchapternewpage odd +@c Combine the variable and function indices: +@syncodeindex vr fn +@c Combine the program and concept indices: +@syncodeindex pg cp +@c FSF publishers: format makebook.texi instead of using this file directly. +@c ISBN confirmed by Jasimin Huang <jasimin@fsf.org> on 25 Mar 2009 +@set ISBN 1-882114-83-3 +@c %**end of header + +@copying +This file documents the GNU @code{make} utility, which determines +automatically which pieces of a large program need to be recompiled, +and issues the commands to recompile them. + +This is Edition @value{EDITION}, last updated @value{UPDATED}, +of @cite{The GNU Make Manual}, for GNU @code{make} version @value{VERSION}. + +Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, +1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, +2008, 2009, 2010 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' +@end quotation +@end copying + +@c finalout + +@c ISPELL CHECK: done, 10 June 1993 --roland +@c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz + + +@dircategory Software development +@direntry +* Make: (make). Remake files automatically. +@end direntry + +@iftex +@shorttitlepage GNU Make +@end iftex +@titlepage +@title GNU Make +@subtitle A Program for Directing Recompilation +@subtitle GNU @code{make} Version @value{VERSION} +@subtitle @value{UPDATED-MONTH} +@author Richard M. Stallman, Roland McGrath, Paul D. Smith +@page +@vskip 0pt plus 1filll +@insertcopying +@sp 2 +Published by the Free Software Foundation @* +51 Franklin St. -- Fifth Floor @* +Boston, MA 02110-1301 USA @* +ISBN @value{ISBN} @* +@sp 2 +Cover art by Etienne Suvasa. +@end titlepage + +@summarycontents +@contents + +@ifnottex +@node Top, Overview, (dir), (dir) +@top GNU @code{make} + +@insertcopying +@end ifnottex + +@menu +* Overview:: Overview of @code{make}. +* Introduction:: An introduction to @code{make}. +* Makefiles:: Makefiles tell @code{make} what to do. +* Rules:: Rules describe when a file must be remade. +* Recipes:: Recipes say how to remake a file. +* Using Variables:: You can use variables to avoid repetition. +* Conditionals:: Use or ignore parts of the makefile based + on the values of variables. +* Functions:: Many powerful ways to manipulate text. +* Invoking make: Running. How to invoke @code{make} on the command line. +* Implicit Rules:: Use implicit rules to treat many files alike, + based on their file names. +* Archives:: How @code{make} can update library archives. +* Features:: Features GNU @code{make} has over other @code{make}s. +* Missing:: What GNU @code{make} lacks from other @code{make}s. +* Makefile Conventions:: Conventions for writing makefiles for + GNU programs. +* Quick Reference:: A quick reference for experienced users. +* Error Messages:: A list of common errors generated by @code{make}. +* Complex Makefile:: A real example of a straightforward, + but nontrivial, makefile. + +* GNU Free Documentation License:: License for copying this manual +* Concept Index:: Index of Concepts +* Name Index:: Index of Functions, Variables, & Directives + +@detailmenu + --- The Detailed Node Listing --- + +Overview of @code{make} + +* Preparing:: Preparing and running make +* Reading:: On reading this text +* Bugs:: Problems and bugs + +An Introduction to Makefiles + +* Rule Introduction:: What a rule looks like. +* Simple Makefile:: A simple makefile +* How Make Works:: How @code{make} processes this makefile +* Variables Simplify:: Variables make makefiles simpler +* make Deduces:: Letting @code{make} deduce the recipe +* Combine By Prerequisite:: Another style of makefile +* Cleanup:: Rules for cleaning the directory + +Writing Makefiles + +* Makefile Contents:: What makefiles contain. +* Makefile Names:: How to name your makefile. +* Include:: How one makefile can use another makefile. +* MAKEFILES Variable:: The environment can specify extra makefiles. +* Remaking Makefiles:: How makefiles get remade. +* Overriding Makefiles:: How to override part of one makefile + with another makefile. +* Reading Makefiles:: How makefiles are parsed. +* Secondary Expansion:: How and when secondary expansion is performed. + +Writing Rules + +* Rule Example:: An example explained. +* Rule Syntax:: General syntax explained. +* Prerequisite Types:: There are two types of prerequisites. +* Wildcards:: Using wildcard characters such as `*'. +* Directory Search:: Searching other directories for source files. +* Phony Targets:: Using a target that is not a real file's name. +* Force Targets:: You can use a target without a recipe + or prerequisites to mark other targets + as phony. +* Empty Targets:: When only the date matters and the + files are empty. +* Special Targets:: Targets with special built-in meanings. +* Multiple Targets:: When to make use of several targets in a rule. +* Multiple Rules:: How to use several rules with the same target. +* Static Pattern:: Static pattern rules apply to multiple targets + and can vary the prerequisites according to + the target name. +* Double-Colon:: How to use a special kind of rule to allow + several independent rules for one target. +* Automatic Prerequisites:: How to automatically generate rules giving + prerequisites from source files themselves. + +Using Wildcard Characters in File Names + +* Wildcard Examples:: Several examples +* Wildcard Pitfall:: Problems to avoid. +* Wildcard Function:: How to cause wildcard expansion where + it does not normally take place. + +Searching Directories for Prerequisites + +* General Search:: Specifying a search path that applies + to every prerequisite. +* Selective Search:: Specifying a search path + for a specified class of names. +* Search Algorithm:: When and how search paths are applied. +* Recipes/Search:: How to write recipes that work together + with search paths. +* Implicit/Search:: How search paths affect implicit rules. +* Libraries/Search:: Directory search for link libraries. + +Static Pattern Rules + +* Static Usage:: The syntax of static pattern rules. +* Static versus Implicit:: When are they better than implicit rules? + +Writing Recipes in Rules + +* Recipe Syntax:: Recipe syntax features and pitfalls. +* Echoing:: How to control when recipes are echoed. +* Execution:: How recipes are executed. +* Parallel:: How recipes can be executed in parallel. +* Errors:: What happens after a recipe execution error. +* Interrupts:: What happens when a recipe is interrupted. +* Recursion:: Invoking @code{make} from makefiles. +* Canned Recipes:: Defining canned recipes. +* Empty Recipes:: Defining useful, do-nothing recipes. + +Recipe Syntax + +* Splitting Lines:: Breaking long recipe lines for readability. +* Variables in Recipes:: Using @code{make} variables in recipes. + +Recipe Execution + +* Choosing the Shell:: How @code{make} chooses the shell used + to run recipes. + +Recursive Use of @code{make} + +* MAKE Variable:: The special effects of using @samp{$(MAKE)}. +* Variables/Recursion:: How to communicate variables to a sub-@code{make}. +* Options/Recursion:: How to communicate options to a sub-@code{make}. +* -w Option:: How the @samp{-w} or @samp{--print-directory} option + helps debug use of recursive @code{make} commands. + +How to Use Variables + +* Reference:: How to use the value of a variable. +* Flavors:: Variables come in two flavors. +* Advanced:: Advanced features for referencing a variable. +* Values:: All the ways variables get their values. +* Setting:: How to set a variable in the makefile. +* Appending:: How to append more text to the old value + of a variable. +* Override Directive:: How to set a variable in the makefile even if + the user has set it with a command argument. +* Multi-Line:: An alternate way to set a variable + to a multi-line string. +* Environment:: Variable values can come from the environment. +* Target-specific:: Variable values can be defined on a per-target + basis. +* Pattern-specific:: Target-specific variable values can be applied + to a group of targets that match a pattern. +* Suppressing Inheritance:: Suppress inheritance of variables. +* Special Variables:: Variables with special meaning or behavior. + +Advanced Features for Reference to Variables + +* Substitution Refs:: Referencing a variable with + substitutions on the value. +* Computed Names:: Computing the name of the variable to refer to. + +Conditional Parts of Makefiles + +* Conditional Example:: Example of a conditional +* Conditional Syntax:: The syntax of conditionals. +* Testing Flags:: Conditionals that test flags. + +Functions for Transforming Text + +* Syntax of Functions:: How to write a function call. +* Text Functions:: General-purpose text manipulation functions. +* File Name Functions:: Functions for manipulating file names. +* Conditional Functions:: Functions that implement conditions. +* Foreach Function:: Repeat some text with controlled variation. +* Call Function:: Expand a user-defined function. +* Value Function:: Return the un-expanded value of a variable. +* Eval Function:: Evaluate the arguments as makefile syntax. +* Origin Function:: Find where a variable got its value. +* Flavor Function:: Find out the flavor of a variable. +* Shell Function:: Substitute the output of a shell command. +* Make Control Functions:: Functions that control how make runs. + +How to Run @code{make} + +* Makefile Arguments:: How to specify which makefile to use. +* Goals:: How to use goal arguments to specify which + parts of the makefile to use. +* Instead of Execution:: How to use mode flags to specify what + kind of thing to do with the recipes + in the makefile other than simply + execute them. +* Avoiding Compilation:: How to avoid recompiling certain files. +* Overriding:: How to override a variable to specify + an alternate compiler and other things. +* Testing:: How to proceed past some errors, to + test compilation. +* Options Summary:: Summary of Options + +Using Implicit Rules + +* Using Implicit:: How to use an existing implicit rule + to get the recipe for updating a file. +* Catalogue of Rules:: A list of built-in implicit rules. +* Implicit Variables:: How to change what predefined rules do. +* Chained Rules:: How to use a chain of implicit rules. +* Pattern Rules:: How to define new implicit rules. +* Last Resort:: How to define a recipe for rules which + cannot find any. +* Suffix Rules:: The old-fashioned style of implicit rule. +* Implicit Rule Search:: The precise algorithm for applying + implicit rules. + +Defining and Redefining Pattern Rules + +* Pattern Intro:: An introduction to pattern rules. +* Pattern Examples:: Examples of pattern rules. +* Automatic Variables:: How to use automatic variables in the + recipe of implicit rules. +* Pattern Match:: How patterns match. +* Match-Anything Rules:: Precautions you should take prior to + defining rules that can match any + target file whatever. +* Canceling Rules:: How to override or cancel built-in rules. + +Using @code{make} to Update Archive Files + +* Archive Members:: Archive members as targets. +* Archive Update:: The implicit rule for archive member targets. +* Archive Pitfalls:: Dangers to watch out for when using archives. +* Archive Suffix Rules:: You can write a special kind of suffix rule + for updating archives. + +Implicit Rule for Archive Member Targets + +* Archive Symbols:: How to update archive symbol directories. + +@end detailmenu +@end menu + +@node Overview, Introduction, Top, Top +@comment node-name, next, previous, up +@chapter Overview of @code{make} + +The @code{make} utility automatically determines which pieces of a large +program need to be recompiled, and issues commands to recompile them. +This manual describes GNU @code{make}, which was implemented by Richard +Stallman and Roland McGrath. Development since Version 3.76 has been +handled by Paul D. Smith. + +GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard +1003.2-1992} (POSIX.2). +@cindex POSIX +@cindex IEEE Standard 1003.2 +@cindex standards conformance + +Our examples show C programs, since they are most common, but you can use +@code{make} with any programming language whose compiler can be run with a +shell command. Indeed, @code{make} is not limited to programs. You can +use it to describe any task where some files must be updated automatically +from others whenever the others change. + +@menu +* Preparing:: Preparing and Running Make +* Reading:: On Reading this Text +* Bugs:: Problems and Bugs +@end menu + +@node Preparing, Reading, Overview, Overview +@ifnottex +@heading Preparing and Running Make +@end ifnottex + +To prepare to use @code{make}, you must write a file called +the @dfn{makefile} that describes the relationships among files +in your program and provides commands for updating each file. +In a program, typically, the executable file is updated from object +files, which are in turn made by compiling source files.@refill + +Once a suitable makefile exists, each time you change some source files, +this simple shell command: + +@example +make +@end example + +@noindent +suffices to perform all necessary recompilations. The @code{make} program +uses the makefile data base and the last-modification times of the files to +decide which of the files need to be updated. For each of those files, it +issues the recipes recorded in the data base. + +You can provide command line arguments to @code{make} to control which +files should be recompiled, or how. @xref{Running, ,How to Run +@code{make}}. + +@node Reading, Bugs, Preparing, Overview +@section How to Read This Manual + +If you are new to @code{make}, or are looking for a general +introduction, read the first few sections of each chapter, skipping the +later sections. In each chapter, the first few sections contain +introductory or general information and the later sections contain +specialized or technical information. +@ifnottex +The exception is the second chapter, @ref{Introduction, ,An +Introduction to Makefiles}, all of which is introductory. +@end ifnottex +@iftex +The exception is @ref{Introduction, ,An Introduction to Makefiles}, +all of which is introductory. +@end iftex + +If you are familiar with other @code{make} programs, see @ref{Features, +,Features of GNU @code{make}}, which lists the enhancements GNU +@code{make} has, and @ref{Missing, ,Incompatibilities and Missing +Features}, which explains the few things GNU @code{make} lacks that +others have. + +For a quick summary, see @ref{Options Summary}, @ref{Quick Reference}, +and @ref{Special Targets}. + +@node Bugs, , Reading, Overview +@section Problems and Bugs +@cindex reporting bugs +@cindex bugs, reporting +@cindex problems and bugs, reporting + +If you have problems with GNU @code{make} or think you've found a bug, +please report it to the developers; we cannot promise to do anything but +we might well want to fix it. + +Before reporting a bug, make sure you've actually found a real bug. +Carefully reread the documentation and see if it really says you can do +what you're trying to do. If it's not clear whether you should be able +to do something or not, report that too; it's a bug in the +documentation! + +Before reporting a bug or trying to fix it yourself, try to isolate it +to the smallest possible makefile that reproduces the problem. Then +send us the makefile and the exact results @code{make} gave you, +including any error or warning messages. Please don't paraphrase +these messages: it's best to cut and paste them into your report. +When generating this small makefile, be sure to not use any non-free +or unusual tools in your recipes: you can almost always emulate what +such a tool would do with simple shell commands. Finally, be sure to +explain what you expected to occur; this will help us decide whether +the problem was really in the documentation. + +Once you have a precise problem you can report it in one of two ways. +Either send electronic mail to: + +@example + bug-make@@gnu.org +@end example + +@noindent +or use our Web-based project management tool, at: + +@example + http://savannah.gnu.org/projects/make/ +@end example + +@noindent +In addition to the information above, please be careful to include the +version number of @code{make} you are using. You can get this +information with the command @samp{make --version}. Be sure also to +include the type of machine and operating system you are using. One +way to obtain this information is by looking at the final lines of +output from the command @samp{make --help}. + +@node Introduction, Makefiles, Overview, Top +@comment node-name, next, previous, up +@chapter An Introduction to Makefiles + +You need a file called a @dfn{makefile} to tell @code{make} what to do. +Most often, the makefile tells @code{make} how to compile and link a +program. +@cindex makefile + +In this chapter, we will discuss a simple makefile that describes how to +compile and link a text editor which consists of eight C source files +and three header files. The makefile can also tell @code{make} how to +run miscellaneous commands when explicitly asked (for example, to remove +certain files as a clean-up operation). To see a more complex example +of a makefile, see @ref{Complex Makefile}. + +When @code{make} recompiles the editor, each changed C source file +must be recompiled. If a header file has changed, each C source file +that includes the header file must be recompiled to be safe. Each +compilation produces an object file corresponding to the source file. +Finally, if any source file has been recompiled, all the object files, +whether newly made or saved from previous compilations, must be linked +together to produce the new executable editor. +@cindex recompilation +@cindex editor + +@menu +* Rule Introduction:: What a rule looks like. +* Simple Makefile:: A Simple Makefile +* How Make Works:: How @code{make} Processes This Makefile +* Variables Simplify:: Variables Make Makefiles Simpler +* make Deduces:: Letting @code{make} Deduce the Recipes +* Combine By Prerequisite:: Another Style of Makefile +* Cleanup:: Rules for Cleaning the Directory +@end menu + +@node Rule Introduction, Simple Makefile, Introduction, Introduction +@comment node-name, next, previous, up +@section What a Rule Looks Like +@cindex rule, introduction to +@cindex makefile rule parts +@cindex parts of makefile rule + +A simple makefile consists of ``rules'' with the following shape: + +@cindex targets, introduction to +@cindex prerequisites, introduction to +@cindex recipes, introduction to +@example +@group +@var{target} @dots{} : @var{prerequisites} @dots{} + @var{recipe} + @dots{} + @dots{} +@end group +@end example + +A @dfn{target} is usually the name of a file that is generated by a +program; examples of targets are executable or object files. A target +can also be the name of an action to carry out, such as @samp{clean} +(@pxref{Phony Targets}). + +A @dfn{prerequisite} is a file that is used as input to create the +target. A target often depends on several files. + +@cindex tabs in rules +A @dfn{recipe} is an action that @code{make} carries out. A recipe +may have more than one command, either on the same line or each on its +own line. @strong{Please note:} you need to put a tab character at +the beginning of every recipe line! This is an obscurity that catches +the unwary. If you prefer to prefix your recipes with a character +other than tab, you can set the @code{.RECIPEPREFIX} variable to an +alternate character (@pxref{Special Variables}). + +Usually a recipe is in a rule with prerequisites and serves to create a +target file if any of the prerequisites change. However, the rule that +specifies a recipe for the target need not have prerequisites. For +example, the rule containing the delete command associated with the +target @samp{clean} does not have prerequisites. + +A @dfn{rule}, then, explains how and when to remake certain files +which are the targets of the particular rule. @code{make} carries out +the recipe on the prerequisites to create or update the target. A +rule can also explain how and when to carry out an action. +@xref{Rules, , Writing Rules}. + +A makefile may contain other text besides rules, but a simple makefile +need only contain rules. Rules may look somewhat more complicated +than shown in this template, but all fit the pattern more or less. + +@node Simple Makefile, How Make Works, Rule Introduction, Introduction +@section A Simple Makefile +@cindex simple makefile +@cindex makefile, simple + +Here is a straightforward makefile that describes the way an +executable file called @code{edit} depends on eight object files +which, in turn, depend on eight C source and three header files. + +In this example, all the C files include @file{defs.h}, but only those +defining editing commands include @file{command.h}, and only low +level files that change the editor buffer include @file{buffer.h}. + +@example +@group +edit : main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + cc -o edit main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + +main.o : main.c defs.h + cc -c main.c +kbd.o : kbd.c defs.h command.h + cc -c kbd.c +command.o : command.c defs.h command.h + cc -c command.c +display.o : display.c defs.h buffer.h + cc -c display.c +insert.o : insert.c defs.h buffer.h + cc -c insert.c +search.o : search.c defs.h buffer.h + cc -c search.c +files.o : files.c defs.h buffer.h command.h + cc -c files.c +utils.o : utils.c defs.h + cc -c utils.c +clean : + rm edit main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o +@end group +@end example + +@noindent +We split each long line into two lines using backslash-newline; this is +like using one long line, but is easier to read. +@cindex continuation lines +@cindex @code{\} (backslash), for continuation lines +@cindex backslash (@code{\}), for continuation lines +@cindex quoting newline, in makefile +@cindex newline, quoting, in makefile + +To use this makefile to create the executable file called @file{edit}, +type: + +@example +make +@end example + +To use this makefile to delete the executable file and all the object +files from the directory, type: + +@example +make clean +@end example + +In the example makefile, the targets include the executable file +@samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The +prerequisites are files such as @samp{main.c} and @samp{defs.h}. +In fact, each @samp{.o} file is both a target and a prerequisite. +Recipes include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}. + +When a target is a file, it needs to be recompiled or relinked if any +of its prerequisites change. In addition, any prerequisites that are +themselves automatically generated should be updated first. In this +example, @file{edit} depends on each of the eight object files; the +object file @file{main.o} depends on the source file @file{main.c} and +on the header file @file{defs.h}. + +A recipe may follow each line that contains a target and +prerequisites. These recipes say how to update the target file. A +tab character (or whatever character is specified by the +@code{.RECIPEPREFIX} variable; @pxref{Special Variables}) must come at +the beginning of every line in the recipe to distinguish recipes from +other lines in the makefile. (Bear in mind that @code{make} does not +know anything about how the recipes work. It is up to you to supply +recipes that will update the target file properly. All @code{make} +does is execute the recipe you have specified when the target file +needs to be updated.)@refill +@cindex recipe + +The target @samp{clean} is not a file, but merely the name of an +action. Since you normally do not want to carry out the actions in +this rule, @samp{clean} is not a prerequisite of any other rule. +Consequently, @code{make} never does anything with it unless you tell +it specifically. Note that this rule not only is not a prerequisite, +it also does not have any prerequisites, so the only purpose of the +rule is to run the specified recipe. Targets that do not refer to +files but are just actions are called @dfn{phony targets}. +@xref{Phony Targets}, for information about this kind of target. +@xref{Errors, , Errors in Recipes}, to see how to cause @code{make} +to ignore errors from @code{rm} or any other command. +@cindex @code{clean} target +@cindex @code{rm} (shell command) + +@node How Make Works, Variables Simplify, Simple Makefile, Introduction +@comment node-name, next, previous, up +@section How @code{make} Processes a Makefile +@cindex processing a makefile +@cindex makefile, how @code{make} processes + +By default, @code{make} starts with the first target (not targets whose +names start with @samp{.}). This is called the @dfn{default goal}. +(@dfn{Goals} are the targets that @code{make} strives ultimately to +update. You can override this behavior using the command line +(@pxref{Goals, , Arguments to Specify the Goals}) or with the +@code{.DEFAULT_GOAL} special variable (@pxref{Special Variables, , +Other Special Variables}). +@cindex default goal +@cindex goal, default +@cindex goal + +In the simple example of the previous section, the default goal is to +update the executable program @file{edit}; therefore, we put that rule +first. + +Thus, when you give the command: + +@example +make +@end example + +@noindent +@code{make} reads the makefile in the current directory and begins by +processing the first rule. In the example, this rule is for relinking +@file{edit}; but before @code{make} can fully process this rule, it +must process the rules for the files that @file{edit} depends on, +which in this case are the object files. Each of these files is +processed according to its own rule. These rules say to update each +@samp{.o} file by compiling its source file. The recompilation must +be done if the source file, or any of the header files named as +prerequisites, is more recent than the object file, or if the object +file does not exist. + +The other rules are processed because their targets appear as +prerequisites of the goal. If some other rule is not depended on by the +goal (or anything it depends on, etc.), that rule is not processed, +unless you tell @code{make} to do so (with a command such as +@w{@code{make clean}}). + +Before recompiling an object file, @code{make} considers updating its +prerequisites, the source file and header files. This makefile does not +specify anything to be done for them---the @samp{.c} and @samp{.h} files +are not the targets of any rules---so @code{make} does nothing for these +files. But @code{make} would update automatically generated C programs, +such as those made by Bison or Yacc, by their own rules at this time. + +After recompiling whichever object files need it, @code{make} decides +whether to relink @file{edit}. This must be done if the file +@file{edit} does not exist, or if any of the object files are newer than +it. If an object file was just recompiled, it is now newer than +@file{edit}, so @file{edit} is relinked. +@cindex relinking + +Thus, if we change the file @file{insert.c} and run @code{make}, +@code{make} will compile that file to update @file{insert.o}, and then +link @file{edit}. If we change the file @file{command.h} and run +@code{make}, @code{make} will recompile the object files @file{kbd.o}, +@file{command.o} and @file{files.o} and then link the file @file{edit}. + +@node Variables Simplify, make Deduces, How Make Works, Introduction +@section Variables Make Makefiles Simpler +@cindex variables +@cindex simplifying with variables + +In our example, we had to list all the object files twice in the rule for +@file{edit} (repeated here): + +@example +@group +edit : main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + cc -o edit main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o +@end group +@end example + +@cindex @code{objects} +Such duplication is error-prone; if a new object file is added to the +system, we might add it to one list and forget the other. We can eliminate +the risk and simplify the makefile by using a variable. @dfn{Variables} +allow a text string to be defined once and substituted in multiple places +later (@pxref{Using Variables, ,How to Use Variables}). + +@cindex @code{OBJECTS} +@cindex @code{objs} +@cindex @code{OBJS} +@cindex @code{obj} +@cindex @code{OBJ} +It is standard practice for every makefile to have a variable named +@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj}, +or @code{OBJ} which is a list of all object file names. We would +define such a variable @code{objects} with a line like this in the +makefile:@refill + +@example +@group +objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o +@end group +@end example + +@noindent +Then, each place we want to put a list of the object file names, we can +substitute the variable's value by writing @samp{$(objects)} +(@pxref{Using Variables, ,How to Use Variables}). + +Here is how the complete simple makefile looks when you use a variable +for the object files: + +@example +@group +objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + +edit : $(objects) + cc -o edit $(objects) +main.o : main.c defs.h + cc -c main.c +kbd.o : kbd.c defs.h command.h + cc -c kbd.c +command.o : command.c defs.h command.h + cc -c command.c +display.o : display.c defs.h buffer.h + cc -c display.c +insert.o : insert.c defs.h buffer.h + cc -c insert.c +search.o : search.c defs.h buffer.h + cc -c search.c +files.o : files.c defs.h buffer.h command.h + cc -c files.c +utils.o : utils.c defs.h + cc -c utils.c +clean : + rm edit $(objects) +@end group +@end example + +@node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction +@section Letting @code{make} Deduce the Recipes +@cindex deducing recipes (implicit rules) +@cindex implicit rule, introduction to +@cindex rule, implicit, introduction to + +It is not necessary to spell out the recipes for compiling the individual +C source files, because @code{make} can figure them out: it has an +@dfn{implicit rule} for updating a @samp{.o} file from a correspondingly +named @samp{.c} file using a @samp{cc -c} command. For example, it will +use the recipe @samp{cc -c main.c -o main.o} to compile @file{main.c} into +@file{main.o}. We can therefore omit the recipes from the rules for the +object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill + +When a @samp{.c} file is used automatically in this way, it is also +automatically added to the list of prerequisites. We can therefore omit +the @samp{.c} files from the prerequisites, provided we omit the recipe. + +Here is the entire example, with both of these changes, and a variable +@code{objects} as suggested above: + +@example +@group +objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + +edit : $(objects) + cc -o edit $(objects) + +main.o : defs.h +kbd.o : defs.h command.h +command.o : defs.h command.h +display.o : defs.h buffer.h +insert.o : defs.h buffer.h +search.o : defs.h buffer.h +files.o : defs.h buffer.h command.h +utils.o : defs.h + +.PHONY : clean +clean : + rm edit $(objects) +@end group +@end example + +@noindent +This is how we would write the makefile in actual practice. (The +complications associated with @samp{clean} are described elsewhere. +See @ref{Phony Targets}, and @ref{Errors, ,Errors in Recipes}.) + +Because implicit rules are so convenient, they are important. You +will see them used frequently.@refill + +@node Combine By Prerequisite, Cleanup, make Deduces, Introduction +@section Another Style of Makefile +@cindex combining rules by prerequisite + +When the objects of a makefile are created only by implicit rules, an +alternative style of makefile is possible. In this style of makefile, +you group entries by their prerequisites instead of by their targets. +Here is what one looks like: + +@example +@group +objects = main.o kbd.o command.o display.o \ + insert.o search.o files.o utils.o + +edit : $(objects) + cc -o edit $(objects) + +$(objects) : defs.h +kbd.o command.o files.o : command.h +display.o insert.o search.o files.o : buffer.h +@end group +@end example + +@noindent +Here @file{defs.h} is given as a prerequisite of all the object files; +@file{command.h} and @file{buffer.h} are prerequisites of the specific +object files listed for them. + +Whether this is better is a matter of taste: it is more compact, but some +people dislike it because they find it clearer to put all the information +about each target in one place. + +@node Cleanup, , Combine By Prerequisite, Introduction +@section Rules for Cleaning the Directory +@cindex cleaning up +@cindex removing, to clean up + +Compiling a program is not the only thing you might want to write rules +for. Makefiles commonly tell how to do a few other things besides +compiling a program: for example, how to delete all the object files +and executables so that the directory is @samp{clean}. + +@cindex @code{clean} target +Here is how we +could write a @code{make} rule for cleaning our example editor: + +@example +@group +clean: + rm edit $(objects) +@end group +@end example + +In practice, we might want to write the rule in a somewhat more +complicated manner to handle unanticipated situations. We would do this: + +@example +@group +.PHONY : clean +clean : + -rm edit $(objects) +@end group +@end example + +@noindent +This prevents @code{make} from getting confused by an actual file +called @file{clean} and causes it to continue in spite of errors from +@code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in +Recipes}.) + +@noindent +A rule such as this should not be placed at the beginning of the +makefile, because we do not want it to run by default! Thus, in the +example makefile, we want the rule for @code{edit}, which recompiles +the editor, to remain the default goal. + +Since @code{clean} is not a prerequisite of @code{edit}, this rule will not +run at all if we give the command @samp{make} with no arguments. In +order to make the rule run, we have to type @samp{make clean}. +@xref{Running, ,How to Run @code{make}}. + +@node Makefiles, Rules, Introduction, Top +@chapter Writing Makefiles + +@cindex makefile, how to write +The information that tells @code{make} how to recompile a system comes from +reading a data base called the @dfn{makefile}. + +@menu +* Makefile Contents:: What makefiles contain. +* Makefile Names:: How to name your makefile. +* Include:: How one makefile can use another makefile. +* MAKEFILES Variable:: The environment can specify extra makefiles. +* Remaking Makefiles:: How makefiles get remade. +* Overriding Makefiles:: How to override part of one makefile + with another makefile. +* Reading Makefiles:: How makefiles are parsed. +* Secondary Expansion:: How and when secondary expansion is performed. +@end menu + +@node Makefile Contents, Makefile Names, Makefiles, Makefiles +@section What Makefiles Contain + +Makefiles contain five kinds of things: @dfn{explicit rules}, +@dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives}, +and @dfn{comments}. Rules, variables, and directives are described at +length in later chapters.@refill + +@itemize @bullet +@cindex rule, explicit, definition of +@cindex explicit rule, definition of +@item +An @dfn{explicit rule} says when and how to remake one or more files, +called the rule's @dfn{targets}. It lists the other files that the +targets depend on, called the @dfn{prerequisites} of the target, and +may also give a recipe to use to create or update the targets. +@xref{Rules, ,Writing Rules}. + +@cindex rule, implicit, definition of +@cindex implicit rule, definition of +@item +An @dfn{implicit rule} says when and how to remake a class of files +based on their names. It describes how a target may depend on a file +with a name similar to the target and gives a recipe to create or +update such a target. @xref{Implicit Rules, ,Using Implicit Rules}. + +@cindex variable definition +@item +A @dfn{variable definition} is a line that specifies a text string +value for a variable that can be substituted into the text later. The +simple makefile example shows a variable definition for @code{objects} +as a list of all object files (@pxref{Variables Simplify, , Variables +Make Makefiles Simpler}). + +@cindex directive +@item +A @dfn{directive} is an instruction for @code{make} to do something +special while reading the makefile. These include: + +@itemize @bullet +@item +Reading another makefile (@pxref{Include, ,Including Other Makefiles}). + +@item +Deciding (based on the values of variables) whether to use or +ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}). + +@item +Defining a variable from a verbatim string containing multiple lines +(@pxref{Multi-Line, ,Defining Multi-Line Variables}). +@end itemize + +@cindex comments, in makefile +@cindex @code{#} (comments), in makefile +@item +@samp{#} in a line of a makefile starts a @dfn{comment}. It and the +rest of the line are ignored, except that a trailing backslash not +escaped by another backslash will continue the comment across multiple +lines. A line containing just a comment (with perhaps spaces before +it) is effectively blank, and is ignored. If you want a literal +@code{#}, escape it with a backslash (e.g., @code{\#}). Comments may +appear on any line in the makefile, although they are treated +specially in certain situations. + +You cannot use comments within variable references or function calls: +any instance of @code{#} will be treated literally (rather than as the +start of a comment) inside a variable reference or function call. + +Comments within a recipe are passed to the shell, just as with any +other recipe text. The shell decides how to interpret it: whether or +not this is a comment is up to the shell. + +Within a @code{define} directive, comments are not ignored during the +definition of the variable, but rather kept intact in the value of the +variable. When the variable is expanded they will either be treated +as @code{make} comments or as recipe text, depending on the context in +which the variable is evaluated. +@end itemize + +@node Makefile Names, Include, Makefile Contents, Makefiles +@section What Name to Give Your Makefile +@cindex makefile name +@cindex name of makefile +@cindex default makefile name +@cindex file name of makefile + +@c following paragraph rewritten to avoid overfull hbox +By default, when @code{make} looks for the makefile, it tries the +following names, in order: @file{GNUmakefile}, @file{makefile} +and @file{Makefile}.@refill +@findex Makefile +@findex GNUmakefile +@findex makefile + +@cindex @code{README} +Normally you should call your makefile either @file{makefile} or +@file{Makefile}. (We recommend @file{Makefile} because it appears +prominently near the beginning of a directory listing, right near other +important files such as @file{README}.) The first name checked, +@file{GNUmakefile}, is not recommended for most makefiles. You should +use this name if you have a makefile that is specific to GNU +@code{make}, and will not be understood by other versions of +@code{make}. Other @code{make} programs look for @file{makefile} and +@file{Makefile}, but not @file{GNUmakefile}. + +If @code{make} finds none of these names, it does not use any makefile. +Then you must specify a goal with a command argument, and @code{make} +will attempt to figure out how to remake it using only its built-in +implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}. + +@cindex @code{-f} +@cindex @code{--file} +@cindex @code{--makefile} +If you want to use a nonstandard name for your makefile, you can specify +the makefile name with the @samp{-f} or @samp{--file} option. The +arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell +@code{make} to read the file @var{name} as the makefile. If you use +more than one @samp{-f} or @samp{--file} option, you can specify several +makefiles. All the makefiles are effectively concatenated in the order +specified. The default makefile names @file{GNUmakefile}, +@file{makefile} and @file{Makefile} are not checked automatically if you +specify @samp{-f} or @samp{--file}.@refill +@cindex specifying makefile name +@cindex makefile name, how to specify +@cindex name of makefile, how to specify +@cindex file name of makefile, how to specify + +@node Include, MAKEFILES Variable, Makefile Names, Makefiles +@section Including Other Makefiles +@cindex including other makefiles +@cindex makefile, including + +@findex include +The @code{include} directive tells @code{make} to suspend reading the +current makefile and read one or more other makefiles before continuing. +The directive is a line in the makefile that looks like this: + +@example +include @var{filenames}@dots{} +@end example + +@noindent +@var{filenames} can contain shell file name patterns. If +@var{filenames} is empty, nothing is included and no error is printed. +@cindex shell file name pattern (in @code{include}) +@cindex shell wildcards (in @code{include}) +@cindex wildcard, in @code{include} + +Extra spaces are allowed and ignored at the beginning of the line, but +the first character must not be a tab (or the value of +@code{.RECIPEPREFIX})---if the line begins with a tab, it will be +considered a recipe line. Whitespace is required between +@code{include} and the file names, and between file names; extra +whitespace is ignored there and at the end of the directive. A +comment starting with @samp{#} is allowed at the end of the line. If +the file names contain any variable or function references, they are +expanded. @xref{Using Variables, ,How to Use Variables}. + +For example, if you have three @file{.mk} files, @file{a.mk}, +@file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to +@code{bish bash}, then the following expression + +@example +include foo *.mk $(bar) +@end example + +is equivalent to + +@example +include foo a.mk b.mk c.mk bish bash +@end example + +When @code{make} processes an @code{include} directive, it suspends +reading of the containing makefile and reads from each listed file in +turn. When that is finished, @code{make} resumes reading the +makefile in which the directive appears. + +One occasion for using @code{include} directives is when several programs, +handled by individual makefiles in various directories, need to use a +common set of variable definitions +(@pxref{Setting, ,Setting Variables}) or pattern rules +(@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). + +Another such occasion is when you want to generate prerequisites from +source files automatically; the prerequisites can be put in a file that +is included by the main makefile. This practice is generally cleaner +than that of somehow appending the prerequisites to the end of the main +makefile as has been traditionally done with other versions of +@code{make}. @xref{Automatic Prerequisites}. +@cindex prerequisites, automatic generation +@cindex automatic generation of prerequisites +@cindex generating prerequisites automatically + +@cindex @code{-I} +@cindex @code{--include-dir} +@cindex included makefiles, default directories +@cindex default directories for included makefiles +@findex /usr/gnu/include +@findex /usr/local/include +@findex /usr/include +If the specified name does not start with a slash, and the file is not +found in the current directory, several other directories are searched. +First, any directories you have specified with the @samp{-I} or +@samp{--include-dir} option are searched +(@pxref{Options Summary, ,Summary of Options}). +Then the following directories (if they exist) +are searched, in this order: +@file{@var{prefix}/include} (normally @file{/usr/local/include} +@footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if +@var{prefix} has been defined to be the root of the DJGPP tree +hierarchy.}) +@file{/usr/gnu/include}, +@file{/usr/local/include}, @file{/usr/include}. + +If an included makefile cannot be found in any of these directories, a +warning message is generated, but it is not an immediately fatal error; +processing of the makefile containing the @code{include} continues. +Once it has finished reading makefiles, @code{make} will try to remake +any that are out of date or don't exist. +@xref{Remaking Makefiles, ,How Makefiles Are Remade}. +Only after it has tried to find a way to remake a makefile and failed, +will @code{make} diagnose the missing makefile as a fatal error. + +If you want @code{make} to simply ignore a makefile which does not exist +or cannot be remade, with no error message, use the @w{@code{-include}} +directive instead of @code{include}, like this: + +@example +-include @var{filenames}@dots{} +@end example + +This acts like @code{include} in every way except that there is no +error (not even a warning) if any of the @var{filenames} (or any +prerequisites of any of the @var{filenames}) do not exist or cannot be +remade. + +For compatibility with some other @code{make} implementations, +@code{sinclude} is another name for @w{@code{-include}}. + +@node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles +@section The Variable @code{MAKEFILES} +@cindex makefile, and @code{MAKEFILES} variable +@cindex including (@code{MAKEFILES} variable) + +@vindex MAKEFILES +If the environment variable @code{MAKEFILES} is defined, @code{make} +considers its value as a list of names (separated by whitespace) of +additional makefiles to be read before the others. This works much +like the @code{include} directive: various directories are searched +for those files (@pxref{Include, ,Including Other Makefiles}). In +addition, the default goal is never taken from one of these makefiles +(or any makefile included by them) and it is not an error if the files +listed in @code{MAKEFILES} are not found.@refill + +@cindex recursion, and @code{MAKEFILES} variable +The main use of @code{MAKEFILES} is in communication between recursive +invocations of @code{make} (@pxref{Recursion, ,Recursive Use of +@code{make}}). It usually is not desirable to set the environment +variable before a top-level invocation of @code{make}, because it is +usually better not to mess with a makefile from outside. However, if +you are running @code{make} without a specific makefile, a makefile in +@code{MAKEFILES} can do useful things to help the built-in implicit +rules work better, such as defining search paths (@pxref{Directory Search}). + +Some users are tempted to set @code{MAKEFILES} in the environment +automatically on login, and program makefiles to expect this to be done. +This is a very bad idea, because such makefiles will fail to work if run by +anyone else. It is much better to write explicit @code{include} directives +in the makefiles. @xref{Include, , Including Other Makefiles}. + +@node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles +@section How Makefiles Are Remade + +@cindex updating makefiles +@cindex remaking makefiles +@cindex makefile, remaking of +Sometimes makefiles can be remade from other files, such as RCS or SCCS +files. If a makefile can be remade from other files, you probably want +@code{make} to get an up-to-date version of the makefile to read in. + +To this end, after reading in all makefiles, @code{make} will consider +each as a goal target and attempt to update it. If a makefile has a +rule which says how to update it (found either in that very makefile or +in another one) or if an implicit rule applies to it (@pxref{Implicit +Rules, ,Using Implicit Rules}), it will be updated if necessary. After +all makefiles have been checked, if any have actually been changed, +@code{make} starts with a clean slate and reads all the makefiles over +again. (It will also attempt to update each of them over again, but +normally this will not change them again, since they are already up to +date.)@refill + +If you know that one or more of your makefiles cannot be remade and +you want to keep @code{make} from performing an implicit rule search +on them, perhaps for efficiency reasons, you can use any normal method +of preventing implicit rule lookup to do so. For example, you can +write an explicit rule with the makefile as the target, and an empty +recipe (@pxref{Empty Recipes, ,Using Empty Recipes}). + +If the makefiles specify a double-colon rule to remake a file with +a recipe but no prerequisites, that file will always be remade +(@pxref{Double-Colon}). In the case of makefiles, a makefile that has a +double-colon rule with a recipe but no prerequisites will be remade every +time @code{make} is run, and then again after @code{make} starts over +and reads the makefiles in again. This would cause an infinite loop: +@code{make} would constantly remake the makefile, and never do anything +else. So, to avoid this, @code{make} will @strong{not} attempt to +remake makefiles which are specified as targets of a double-colon rule +with a recipe but no prerequisites.@refill + +If you do not specify any makefiles to be read with @samp{-f} or +@samp{--file} options, @code{make} will try the default makefile names; +@pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike +makefiles explicitly requested with @samp{-f} or @samp{--file} options, +@code{make} is not certain that these makefiles should exist. However, +if a default makefile does not exist but can be created by running +@code{make} rules, you probably want the rules to be run so that the +makefile can be used. + +Therefore, if none of the default makefiles exists, @code{make} will try +to make each of them in the same order in which they are searched for +(@pxref{Makefile Names, ,What Name to Give Your Makefile}) +until it succeeds in making one, or it runs out of names to try. Note +that it is not an error if @code{make} cannot find or make any makefile; +a makefile is not always necessary.@refill + +When you use the @samp{-t} or @samp{--touch} option +(@pxref{Instead of Execution, ,Instead of Executing Recipes}), +you would not want to use an out-of-date makefile to decide which +targets to touch. So the @samp{-t} option has no effect on updating +makefiles; they are really updated even if @samp{-t} is specified. +Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or +@samp{--just-print}) do not prevent updating of makefiles, because an +out-of-date makefile would result in the wrong output for other targets. +Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in, +and then print the recipe to update @file{foo} and its prerequisites +without running it. The recipe printed for @file{foo} will be the one +specified in the updated contents of @file{mfile}. + +However, on occasion you might actually wish to prevent updating of even +the makefiles. You can do this by specifying the makefiles as goals in +the command line as well as specifying them as makefiles. When the +makefile name is specified explicitly as a goal, the options @samp{-t} +and so on do apply to them. + +Thus, @samp{make -f mfile -n mfile foo} would read the makefile +@file{mfile}, print the recipe needed to update it without actually +running it, and then print the recipe needed to update @file{foo} +without running that. The recipe for @file{foo} will be the one +specified by the existing contents of @file{mfile}. + +@node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles +@section Overriding Part of Another Makefile + +@cindex overriding makefiles +@cindex makefile, overriding +Sometimes it is useful to have a makefile that is mostly just like +another makefile. You can often use the @samp{include} directive to +include one in the other, and add more targets or variable definitions. +However, it is illegal for two makefiles to give different recipes for +the same target. But there is another way. + +@cindex match-anything rule, used to override +In the containing makefile (the one that wants to include the other), +you can use a match-anything pattern rule to say that to remake any +target that cannot be made from the information in the containing +makefile, @code{make} should look in another makefile. +@xref{Pattern Rules}, for more information on pattern rules. + +For example, if you have a makefile called @file{Makefile} that says how +to make the target @samp{foo} (and other targets), you can write a +makefile called @file{GNUmakefile} that contains: + +@example +foo: + frobnicate > foo + +%: force + @@$(MAKE) -f Makefile $@@ +force: ; +@end example + +If you say @samp{make foo}, @code{make} will find @file{GNUmakefile}, +read it, and see that to make @file{foo}, it needs to run the recipe +@samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will +find no way to make @file{bar} in @file{GNUmakefile}, so it will use the +recipe from the pattern rule: @samp{make -f Makefile bar}. If +@file{Makefile} provides a rule for updating @file{bar}, @code{make} +will apply the rule. And likewise for any other target that +@file{GNUmakefile} does not say how to make. + +The way this works is that the pattern rule has a pattern of just +@samp{%}, so it matches any target whatever. The rule specifies a +prerequisite @file{force}, to guarantee that the recipe will be run even +if the target file already exists. We give the @file{force} target an +empty recipe to prevent @code{make} from searching for an implicit rule to +build it---otherwise it would apply the same match-anything rule to +@file{force} itself and create a prerequisite loop! + +@node Reading Makefiles, Secondary Expansion, Overriding Makefiles, Makefiles +@section How @code{make} Reads a Makefile +@cindex reading makefiles +@cindex makefile, parsing + +GNU @code{make} does its work in two distinct phases. During the first +phase it reads all the makefiles, included makefiles, etc. and +internalizes all the variables and their values, implicit and explicit +rules, and constructs a dependency graph of all the targets and their +prerequisites. During the second phase, @code{make} uses these internal +structures to determine what targets will need to be rebuilt and to +invoke the rules necessary to do so. + +It's important to understand this two-phase approach because it has a +direct impact on how variable and function expansion happens; this is +often a source of some confusion when writing makefiles. Here we will +present a summary of the phases in which expansion happens for different +constructs within the makefile. We say that expansion is +@dfn{immediate} if it happens during the first phase: in this case +@code{make} will expand any variables or functions in that section of a +construct as the makefile is parsed. We say that expansion is +@dfn{deferred} if expansion is not performed immediately. Expansion of +a deferred construct is not performed until either the construct appears +later in an immediate context, or until the second phase. + +You may not be familiar with some of these constructs yet. You can +reference this section as you become familiar with them, in later +chapters. + +@subheading Variable Assignment +@cindex +=, expansion +@cindex =, expansion +@cindex ?=, expansion +@cindex +=, expansion +@cindex define, expansion + +Variable definitions are parsed as follows: + +@example +@var{immediate} = @var{deferred} +@var{immediate} ?= @var{deferred} +@var{immediate} := @var{immediate} +@var{immediate} += @var{deferred} or @var{immediate} + +define @var{immediate} + @var{deferred} +endef + +define @var{immediate} = + @var{deferred} +endef + +define @var{immediate} ?= + @var{deferred} +endef + +define @var{immediate} := + @var{immediate} +endef + +define @var{immediate} += + @var{deferred} or @var{immediate} +endef +@end example + +For the append operator, @samp{+=}, the right-hand side is considered +immediate if the variable was previously set as a simple variable +(@samp{:=}), and deferred otherwise. + +@subheading Conditional Directives +@cindex ifdef, expansion +@cindex ifeq, expansion +@cindex ifndef, expansion +@cindex ifneq, expansion + +Conditional directives are parsed immediately. This means, for +example, that automatic variables cannot be used in conditional +directives, as automatic variables are not set until the recipe for +that rule is invoked. If you need to use automatic variables in a +conditional directive you @emph{must} move the condition into the +recipe and use shell conditional syntax instead. + +@subheading Rule Definition +@cindex target, expansion +@cindex prerequisite, expansion +@cindex implicit rule, expansion +@cindex pattern rule, expansion +@cindex explicit rule, expansion + +A rule is always expanded the same way, regardless of the form: + +@example +@var{immediate} : @var{immediate} ; @var{deferred} + @var{deferred} +@end example + +That is, the target and prerequisite sections are expanded immediately, +and the recipe used to construct the target is always deferred. This +general rule is true for explicit rules, pattern rules, suffix rules, +static pattern rules, and simple prerequisite definitions. + +@node Secondary Expansion, , Reading Makefiles, Makefiles +@section Secondary Expansion +@cindex secondary expansion +@cindex expansion, secondary + +@findex .SECONDEXPANSION +In the previous section we learned that GNU @code{make} works in two +distinct phases: a read-in phase and a target-update phase +(@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}). GNU +make also has the ability to enable a @emph{second expansion} of the +prerequisites (only) for some or all targets defined in the makefile. +In order for this second expansion to occur, the special target +@code{.SECONDEXPANSION} must be defined before the first prerequisite +list that makes use of this feature. + +If that special target is defined then in between the two phases +mentioned above, right at the end of the read-in phase, all the +prerequisites of the targets defined after the special target are +expanded a @emph{second time}. In most circumstances this secondary +expansion will have no effect, since all variable and function +references will have been expanded during the initial parsing of the +makefiles. In order to take advantage of the secondary expansion +phase of the parser, then, it's necessary to @emph{escape} the +variable or function reference in the makefile. In this case the +first expansion merely un-escapes the reference but doesn't expand it, +and expansion is left to the secondary expansion phase. For example, +consider this makefile: + +@example +.SECONDEXPANSION: +ONEVAR = onefile +TWOVAR = twofile +myfile: $(ONEVAR) $$(TWOVAR) +@end example + +After the first expansion phase the prerequisites list of the +@file{myfile} target will be @code{onefile} and @code{$(TWOVAR)}; the +first (unescaped) variable reference to @var{ONEVAR} is expanded, +while the second (escaped) variable reference is simply unescaped, +without being recognized as a variable reference. Now during the +secondary expansion the first word is expanded again but since it +contains no variable or function references it remains the static +value @file{onefile}, while the second word is now a normal reference +to the variable @var{TWOVAR}, which is expanded to the value +@file{twofile}. The final result is that there are two prerequisites, +@file{onefile} and @file{twofile}. + +Obviously, this is not a very interesting case since the same result +could more easily have been achieved simply by having both variables +appear, unescaped, in the prerequisites list. One difference becomes +apparent if the variables are reset; consider this example: + +@example +.SECONDEXPANSION: +AVAR = top +onefile: $(AVAR) +twofile: $$(AVAR) +AVAR = bottom +@end example + +Here the prerequisite of @file{onefile} will be expanded immediately, +and resolve to the value @file{top}, while the prerequisite of +@file{twofile} will not be full expanded until the secondary expansion +and yield a value of @file{bottom}. + +This is marginally more exciting, but the true power of this feature +only becomes apparent when you discover that secondary expansions +always take place within the scope of the automatic variables for that +target. This means that you can use variables such as @code{$@@}, +@code{$*}, etc. during the second expansion and they will have their +expected values, just as in the recipe. All you have to do is defer +the expansion by escaping the @code{$}. Also, secondary expansion +occurs for both explicit and implicit (pattern) rules. Knowing this, +the possible uses for this feature increase dramatically. For +example: + +@example +.SECONDEXPANSION: +main_OBJS := main.o try.o test.o +lib_OBJS := lib.o api.o + +main lib: $$($$@@_OBJS) +@end example + +Here, after the initial expansion the prerequisites of both the +@file{main} and @file{lib} targets will be @code{$($@@_OBJS)}. During +the secondary expansion, the @code{$@@} variable is set to the name of +the target and so the expansion for the @file{main} target will yield +@code{$(main_OBJS)}, or @code{main.o try.o test.o}, while the +secondary expansion for the @file{lib} target will yield +@code{$(lib_OBJS)}, or @code{lib.o api.o}. + +You can also mix in functions here, as long as they are properly escaped: + +@example +main_SRCS := main.c try.c test.c +lib_SRCS := lib.c api.c + +.SECONDEXPANSION: +main lib: $$(patsubst %.c,%.o,$$($$@@_SRCS)) +@end example + +This version allows users to specify source files rather than object +files, but gives the same resulting prerequisites list as the previous +example. + +Evaluation of automatic variables during the secondary expansion +phase, especially of the target name variable @code{$$@@}, behaves +similarly to evaluation within recipes. However, there are some +subtle differences and ``corner cases'' which come into play for the +different types of rule definitions that @code{make} understands. The +subtleties of using the different automatic variables are described +below. + +@subheading Secondary Expansion of Explicit Rules +@cindex secondary expansion and explicit rules +@cindex explicit rules, secondary expansion of + +During the secondary expansion of explicit rules, @code{$$@@} and +@code{$$%} evaluate, respectively, to the file name of the target and, +when the target is an archive member, the target member name. The +@code{$$<} variable evaluates to the first prerequisite in the first +rule for this target. @code{$$^} and @code{$$+} evaluate to the list +of all prerequisites of rules @emph{that have already appeared} for +the same target (@code{$$+} with repetitions and @code{$$^} +without). The following example will help illustrate these behaviors: + +@example +.SECONDEXPANSION: + +foo: foo.1 bar.1 $$< $$^ $$+ # line #1 + +foo: foo.2 bar.2 $$< $$^ $$+ # line #2 + +foo: foo.3 bar.3 $$< $$^ $$+ # line #3 +@end example + +In the first prerequisite list, all three variables (@code{$$<}, +@code{$$^}, and @code{$$+}) expand to the empty string. In the +second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and +@code{foo.1 bar.1} respectively. In the third they will have values +@code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1 +foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1} respectively. + +Rules undergo secondary expansion in makefile order, except that +the rule with the recipe is always evaluated last. + +The variables @code{$$?} and @code{$$*} are not available and expand +to the empty string. + +@subheading Secondary Expansion of Static Pattern Rules +@cindex secondary expansion and static pattern rules +@cindex static pattern rules, secondary expansion of + +Rules for secondary expansion of static pattern rules are identical to +those for explicit rules, above, with one exception: for static +pattern rules the @code{$$*} variable is set to the pattern stem. As +with explicit rules, @code{$$?} is not available and expands to the +empty string. + +@subheading Secondary Expansion of Implicit Rules +@cindex secondary expansion and implicit rules +@cindex implicit rules, secondary expansion of + +As @code{make} searches for an implicit rule, it substitutes the stem +and then performs secondary expansion for every rule with a matching +target pattern. The value of the automatic variables is derived in +the same fashion as for static pattern rules. As an example: + +@example +.SECONDEXPANSION: + +foo: bar + +foo foz: fo%: bo% + +%oo: $$< $$^ $$+ $$* +@end example + +When the implicit rule is tried for target @file{foo}, @code{$$<} +expands to @file{bar}, @code{$$^} expands to @file{bar boo}, +@code{$$+} also expands to @file{bar boo}, and @code{$$*} expands to +@file{f}. + +Note that the directory prefix (D), as described in @ref{Implicit Rule +Search, ,Implicit Rule Search Algorithm}, is appended (after +expansion) to all the patterns in the prerequisites list. As an +example: + +@example +.SECONDEXPANSION: + +/tmp/foo.o: + +%.o: $$(addsuffix /%.c,foo bar) foo.h +@end example + +The prerequisite list after the secondary expansion and directory +prefix reconstruction will be @file{/tmp/foo/foo.c /tmp/var/bar/foo.c +foo.h}. If you are not interested in this reconstruction, you can use +@code{$$*} instead of @code{%} in the prerequisites list. + +@node Rules, Recipes, Makefiles, Top +@chapter Writing Rules +@cindex writing rules +@cindex rule, how to write +@cindex target +@cindex prerequisite + +A @dfn{rule} appears in the makefile and says when and how to remake +certain files, called the rule's @dfn{targets} (most often only one per rule). +It lists the other files that are the @dfn{prerequisites} of the target, and +the @dfn{recipe} to use to create or update the target. + +@cindex default goal +@cindex goal, default +The order of rules is not significant, except for determining the +@dfn{default goal}: the target for @code{make} to consider, if you do +not otherwise specify one. The default goal is the target of the first +rule in the first makefile. If the first rule has multiple targets, +only the first target is taken as the default. There are two +exceptions: a target starting with a period is not a default unless it +contains one or more slashes, @samp{/}, as well; and, a target that +defines a pattern rule has no effect on the default goal. +(@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.) + +Therefore, we usually write the makefile so that the first rule is the +one for compiling the entire program or all the programs described by +the makefile (often with a target called @samp{all}). +@xref{Goals, ,Arguments to Specify the Goals}. + +@menu +* Rule Example:: An example explained. +* Rule Syntax:: General syntax explained. +* Prerequisite Types:: There are two types of prerequisites. +* Wildcards:: Using wildcard characters such as `*'. +* Directory Search:: Searching other directories for source files. +* Phony Targets:: Using a target that is not a real file's name. +* Force Targets:: You can use a target without recipes + or prerequisites to mark other targets + as phony. +* Empty Targets:: When only the date matters and the + files are empty. +* Special Targets:: Targets with special built-in meanings. +* Multiple Targets:: When to make use of several targets in a rule. +* Multiple Rules:: How to use several rules with the same target. +* Static Pattern:: Static pattern rules apply to multiple targets + and can vary the prerequisites according to + the target name. +* Double-Colon:: How to use a special kind of rule to allow + several independent rules for one target. +* Automatic Prerequisites:: How to automatically generate rules giving + prerequisites from source files themselves. +@end menu + +@ifnottex +@node Rule Example, Rule Syntax, Rules, Rules +@section Rule Example + +Here is an example of a rule: + +@example +foo.o : foo.c defs.h # module for twiddling the frobs + cc -c -g foo.c +@end example + +Its target is @file{foo.o} and its prerequisites are @file{foo.c} and +@file{defs.h}. It has one command in the recipe: @samp{cc -c -g foo.c}. +The recipe starts with a tab to identify it as a recipe. + +This rule says two things: + +@itemize @bullet +@item +How to decide whether @file{foo.o} is out of date: it is out of date +if it does not exist, or if either @file{foo.c} or @file{defs.h} is +more recent than it. + +@item +How to update the file @file{foo.o}: by running @code{cc} as stated. +The recipe does not explicitly mention @file{defs.h}, but we presume +that @file{foo.c} includes it, and that that is why @file{defs.h} was +added to the prerequisites. +@end itemize +@end ifnottex + +@node Rule Syntax, Prerequisite Types, Rule Example, Rules +@section Rule Syntax + +@cindex rule syntax +@cindex syntax of rules +In general, a rule looks like this: + +@example +@var{targets} : @var{prerequisites} + @var{recipe} + @dots{} +@end example + +@noindent +or like this: + +@example +@var{targets} : @var{prerequisites} ; @var{recipe} + @var{recipe} + @dots{} +@end example + +@cindex targets +@cindex rule targets +The @var{targets} are file names, separated by spaces. Wildcard +characters may be used (@pxref{Wildcards, ,Using Wildcard Characters +in File Names}) and a name of the form @file{@var{a}(@var{m})} +represents member @var{m} in archive file @var{a} +(@pxref{Archive Members, ,Archive Members as Targets}). +Usually there is only one +target per rule, but occasionally there is a reason to have more +(@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill + +@cindex recipes +@cindex tab character (in commands) +The @var{recipe} lines start with a tab character (or the first +character in the value of the @code{.RECIPEPREFIX} variable; +@pxref{Special Variables}). The first recipe line may appear on the line +after the prerequisites, with a tab character, or may appear on the +same line, with a semicolon. Either way, the effect is the same. +There are other differences in the syntax of recipes. +@xref{Recipes, ,Writing Recipes in Rules}. + +@cindex dollar sign (@code{$}), in rules +@cindex @code{$}, in rules +@cindex rules, and @code{$} +Because dollar signs are used to start @code{make} variable +references, if you really want a dollar sign in a target or +prerequisite you must write two of them, @samp{$$} (@pxref{Using +Variables, ,How to Use Variables}). If you have enabled secondary +expansion (@pxref{Secondary Expansion}) and you want a literal dollar +sign in the prerequisites list, you must actually write @emph{four} +dollar signs (@samp{$$$$}). + +You may split a long line by inserting a backslash followed by a +newline, but this is not required, as @code{make} places no limit on +the length of a line in a makefile. + +A rule tells @code{make} two things: when the targets are out of date, +and how to update them when necessary. + +@cindex prerequisites +@cindex rule prerequisites +The criterion for being out of date is specified in terms of the +@var{prerequisites}, which consist of file names separated by spaces. +(Wildcards and archive members (@pxref{Archives}) are allowed here too.) +A target is out of date if it does not exist or if it is older than any +of the prerequisites (by comparison of last-modification times). The +idea is that the contents of the target file are computed based on +information in the prerequisites, so if any of the prerequisites changes, +the contents of the existing target file are no longer necessarily +valid. + +How to update is specified by a @var{recipe}. This is one or more +lines to be executed by the shell (normally @samp{sh}), but with some +extra features (@pxref{Recipes, ,Writing Recipes in Rules}). + +@node Prerequisite Types, Wildcards, Rule Syntax, Rules +@comment node-name, next, previous, up +@section Types of Prerequisites +@cindex prerequisite types +@cindex types of prerequisites + +@cindex prerequisites, normal +@cindex normal prerequisites +@cindex prerequisites, order-only +@cindex order-only prerequisites +There are actually two different types of prerequisites understood by +GNU @code{make}: normal prerequisites such as described in the +previous section, and @dfn{order-only} prerequisites. A normal +prerequisite makes two statements: first, it imposes an order in which +recipes will be invoked: the recipes for all prerequisites of a target +will be completed before the recipe for the target is run. Second, it +imposes a dependency relationship: if any prerequisite is newer than +the target, then the target is considered out-of-date and must be +rebuilt. + +Normally, this is exactly what you want: if a target's prerequisite is +updated, then the target should also be updated. + +Occasionally, however, you have a situation where you want to impose a +specific ordering on the rules to be invoked @emph{without} forcing +the target to be updated if one of those rules is executed. In that +case, you want to define @dfn{order-only} prerequisites. Order-only +prerequisites can be specified by placing a pipe symbol (@code{|}) +in the prerequisites list: any prerequisites to the left of the pipe +symbol are normal; any prerequisites to the right are order-only: + +@example +@var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites} +@end example + +The normal prerequisites section may of course be empty. Also, you +may still declare multiple lines of prerequisites for the same target: +they are appended appropriately (normal prerequisites are appended to +the list of normal prerequisites; order-only prerequisites are +appended to the list of order-only prerequisites). Note that if you +declare the same file to be both a normal and an order-only +prerequisite, the normal prerequisite takes precedence (since they +have a strict superset of the behavior of an order-only prerequisite). + +Consider an example where your targets are to be placed in a separate +directory, and that directory might not exist before @code{make} is +run. In this situation, you want the directory to be created before +any targets are placed into it but, because the timestamps on +directories change whenever a file is added, removed, or renamed, we +certainly don't want to rebuild all the targets whenever the +directory's timestamp changes. One way to manage this is with +order-only prerequisites: make the directory an order-only +prerequisite on all the targets: + +@example +OBJDIR := objdir +OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o) + +$(OBJDIR)/%.o : %.c + $(COMPILE.c) $(OUTPUT_OPTION) $< + +all: $(OBJS) + +$(OBJS): | $(OBJDIR) + +$(OBJDIR): + mkdir $(OBJDIR) +@end example + +Now the rule to create the @file{objdir} directory will be run, if +needed, before any @samp{.o} is built, but no @samp{.o} will be built +because the @file{objdir} directory timestamp changed. + +@node Wildcards, Directory Search, Prerequisite Types, Rules +@section Using Wildcard Characters in File Names +@cindex wildcard +@cindex file name with wildcards +@cindex globbing (wildcards) + +@cindex @code{*} (wildcard character) +@cindex @code{?} (wildcard character) +@cindex @code{[@dots{}]} (wildcard characters) +A single file name can specify many files using @dfn{wildcard characters}. +The wildcard characters in @code{make} are @samp{*}, @samp{?} and +@samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c} +specifies a list of all the files (in the working directory) whose names +end in @samp{.c}.@refill + +@cindex @code{~} (tilde) +@cindex tilde (@code{~}) +@cindex home directory +The character @samp{~} at the beginning of a file name also has special +significance. If alone, or followed by a slash, it represents your home +directory. For example @file{~/bin} expands to @file{/home/you/bin}. +If the @samp{~} is followed by a word, the string represents the home +directory of the user named by that word. For example @file{~john/bin} +expands to @file{/home/john/bin}. On systems which don't have a home +directory for each user (such as MS-DOS or MS-Windows), this +functionality can be simulated by setting the environment variable +@var{HOME}.@refill + +Wildcard expansion is performed by @code{make} automatically in +targets and in prerequisites. In recipes, the shell is responsible +for wildcard expansion. In other contexts, wildcard expansion happens +only if you request it explicitly with the @code{wildcard} function. + +The special significance of a wildcard character can be turned off by +preceding it with a backslash. Thus, @file{foo\*bar} would refer to a +specific file whose name consists of @samp{foo}, an asterisk, and +@samp{bar}.@refill + +@menu +* Wildcard Examples:: Several examples +* Wildcard Pitfall:: Problems to avoid. +* Wildcard Function:: How to cause wildcard expansion where + it does not normally take place. +@end menu + +@node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards +@subsection Wildcard Examples + +Wildcards can be used in the recipe of a rule, where they are expanded +by the shell. For example, here is a rule to delete all the object files: + +@example +@group +clean: + rm -f *.o +@end group +@end example +@cindex @code{rm} (shell command) + +Wildcards are also useful in the prerequisites of a rule. With the +following rule in the makefile, @samp{make print} will print all the +@samp{.c} files that have changed since the last time you printed them: + +@example +print: *.c + lpr -p $? + touch print +@end example + +@cindex @code{print} target +@cindex @code{lpr} (shell command) +@cindex @code{touch} (shell command) +@noindent +This rule uses @file{print} as an empty target file; see @ref{Empty +Targets, ,Empty Target Files to Record Events}. (The automatic variable +@samp{$?} is used to print only those files that have changed; see +@ref{Automatic Variables}.)@refill + +Wildcard expansion does not happen when you define a variable. Thus, if +you write this: + +@example +objects = *.o +@end example + +@noindent +then the value of the variable @code{objects} is the actual string +@samp{*.o}. However, if you use the value of @code{objects} in a +target or prerequisite, wildcard expansion will take place there. If +you use the value of @code{objects} in a recipe, the shell may perform +wildcard expansion when the recipe runs. To set @code{objects} to the +expansion, instead use: + +@example +objects := $(wildcard *.o) +@end example + +@noindent +@xref{Wildcard Function}. + +@node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards +@subsection Pitfalls of Using Wildcards +@cindex wildcard pitfalls +@cindex pitfalls of wildcards +@cindex mistakes with wildcards +@cindex errors with wildcards +@cindex problems with wildcards + +Now here is an example of a naive way of using wildcard expansion, that +does not do what you would intend. Suppose you would like to say that the +executable file @file{foo} is made from all the object files in the +directory, and you write this: + +@example +objects = *.o + +foo : $(objects) + cc -o foo $(CFLAGS) $(objects) +@end example + +@noindent +The value of @code{objects} is the actual string @samp{*.o}. Wildcard +expansion happens in the rule for @file{foo}, so that each @emph{existing} +@samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if +necessary. + +But what if you delete all the @samp{.o} files? When a wildcard matches +no files, it is left as it is, so then @file{foo} will depend on the +oddly-named file @file{*.o}. Since no such file is likely to exist, +@code{make} will give you an error saying it cannot figure out how to +make @file{*.o}. This is not what you want! + +Actually it is possible to obtain the desired result with wildcard +expansion, but you need more sophisticated techniques, including the +@code{wildcard} function and string substitution. +@ifnottex +@xref{Wildcard Function, ,The Function @code{wildcard}}. +@end ifnottex +@iftex +These are described in the following section. +@end iftex + +@cindex wildcards and MS-DOS/MS-Windows backslashes +@cindex backslashes in pathnames and wildcard expansion + +Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to +separate directories in pathnames, like so: + +@example + c:\foo\bar\baz.c +@end example + +This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the +@file{c:} part is the so-called drive letter). When @code{make} runs on +these systems, it supports backslashes as well as the Unix-style forward +slashes in pathnames. However, this support does @emph{not} include the +wildcard expansion, where backslash is a quote character. Therefore, +you @emph{must} use Unix-style slashes in these cases. + + +@node Wildcard Function, , Wildcard Pitfall, Wildcards +@subsection The Function @code{wildcard} +@findex wildcard + +Wildcard expansion happens automatically in rules. But wildcard expansion +does not normally take place when a variable is set, or inside the +arguments of a function. If you want to do wildcard expansion in such +places, you need to use the @code{wildcard} function, like this: + +@example +$(wildcard @var{pattern}@dots{}) +@end example + +@noindent +This string, used anywhere in a makefile, is replaced by a +space-separated list of names of existing files that match one of the +given file name patterns. If no existing file name matches a pattern, +then that pattern is omitted from the output of the @code{wildcard} +function. Note that this is different from how unmatched wildcards +behave in rules, where they are used verbatim rather than ignored +(@pxref{Wildcard Pitfall}). + +One use of the @code{wildcard} function is to get a list of all the C source +files in a directory, like this: + +@example +$(wildcard *.c) +@end example + +We can change the list of C source files into a list of object files by +replacing the @samp{.c} suffix with @samp{.o} in the result, like this: + +@example +$(patsubst %.c,%.o,$(wildcard *.c)) +@end example + +@noindent +(Here we have used another function, @code{patsubst}. +@xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill + +Thus, a makefile to compile all C source files in the directory and then +link them together could be written as follows: + +@example +objects := $(patsubst %.c,%.o,$(wildcard *.c)) + +foo : $(objects) + cc -o foo $(objects) +@end example + +@noindent +(This takes advantage of the implicit rule for compiling C programs, so +there is no need to write explicit rules for compiling the files. +@xref{Flavors, ,The Two Flavors of Variables}, for an explanation of +@samp{:=}, which is a variant of @samp{=}.) + +@node Directory Search, Phony Targets, Wildcards, Rules +@section Searching Directories for Prerequisites +@vindex VPATH +@findex vpath +@cindex vpath +@cindex search path for prerequisites (@code{VPATH}) +@cindex directory search (@code{VPATH}) + +For large systems, it is often desirable to put sources in a separate +directory from the binaries. The @dfn{directory search} features of +@code{make} facilitate this by searching several directories +automatically to find a prerequisite. When you redistribute the files +among directories, you do not need to change the individual rules, +just the search paths. + +@menu +* General Search:: Specifying a search path that applies + to every prerequisite. +* Selective Search:: Specifying a search path + for a specified class of names. +* Search Algorithm:: When and how search paths are applied. +* Recipes/Search:: How to write recipes that work together + with search paths. +* Implicit/Search:: How search paths affect implicit rules. +* Libraries/Search:: Directory search for link libraries. +@end menu + +@node General Search, Selective Search, Directory Search, Directory Search +@subsection @code{VPATH}: Search Path for All Prerequisites +@vindex VPATH + +The value of the @code{make} variable @code{VPATH} specifies a list of +directories that @code{make} should search. Most often, the +directories are expected to contain prerequisite files that are not in the +current directory; however, @code{make} uses @code{VPATH} as a search +list for both prerequisites and targets of rules. + +Thus, if a file that is listed as a target or prerequisite does not exist +in the current directory, @code{make} searches the directories listed in +@code{VPATH} for a file with that name. If a file is found in one of +them, that file may become the prerequisite (see below). Rules may then +specify the names of files in the prerequisite list as if they all +existed in the current directory. @xref{Recipes/Search, ,Writing Recipes with Directory Search}. + +In the @code{VPATH} variable, directory names are separated by colons or +blanks. The order in which directories are listed is the order followed +by @code{make} in its search. (On MS-DOS and MS-Windows, semi-colons +are used as separators of directory names in @code{VPATH}, since the +colon can be used in the pathname itself, after the drive letter.) + +For example, + +@example +VPATH = src:../headers +@end example + +@noindent +specifies a path containing two directories, @file{src} and +@file{../headers}, which @code{make} searches in that order. + +With this value of @code{VPATH}, the following rule, + +@example +foo.o : foo.c +@end example + +@noindent +is interpreted as if it were written like this: + +@example +foo.o : src/foo.c +@end example + +@noindent +assuming the file @file{foo.c} does not exist in the current directory but +is found in the directory @file{src}. + +@node Selective Search, Search Algorithm, General Search, Directory Search +@subsection The @code{vpath} Directive +@findex vpath + +Similar to the @code{VPATH} variable, but more selective, is the +@code{vpath} directive (note lower case), which allows you to specify a +search path for a particular class of file names: those that match a +particular pattern. Thus you can supply certain search directories for +one class of file names and other directories (or none) for other file +names. + +There are three forms of the @code{vpath} directive: + +@table @code +@item vpath @var{pattern} @var{directories} +Specify the search path @var{directories} for file names that match +@var{pattern}. + +The search path, @var{directories}, is a list of directories to be +searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or +blanks, just like the search path used in the @code{VPATH} variable. + +@item vpath @var{pattern} +Clear out the search path associated with @var{pattern}. + +@c Extra blank line makes sure this gets two lines. +@item vpath + +Clear all search paths previously specified with @code{vpath} directives. +@end table + +A @code{vpath} pattern is a string containing a @samp{%} character. The +string must match the file name of a prerequisite that is being searched +for, the @samp{%} character matching any sequence of zero or more +characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and +Redefining Pattern Rules}). For example, @code{%.h} matches files that +end in @code{.h}. (If there is no @samp{%}, the pattern must match the +prerequisite exactly, which is not useful very often.) + +@cindex @code{%}, quoting in @code{vpath} +@cindex @code{%}, quoting with @code{\} (backslash) +@cindex @code{\} (backslash), to quote @code{%} +@cindex backslash (@code{\}), to quote @code{%} +@cindex quoting @code{%}, in @code{vpath} +@samp{%} characters in a @code{vpath} directive's pattern can be quoted +with preceding backslashes (@samp{\}). Backslashes that would otherwise +quote @samp{%} characters can be quoted with more backslashes. +Backslashes that quote @samp{%} characters or other backslashes are +removed from the pattern before it is compared to file names. Backslashes +that are not in danger of quoting @samp{%} characters go unmolested.@refill + +When a prerequisite fails to exist in the current directory, if the +@var{pattern} in a @code{vpath} directive matches the name of the +prerequisite file, then the @var{directories} in that directive are searched +just like (and before) the directories in the @code{VPATH} variable. + +For example, + +@example +vpath %.h ../headers +@end example + +@noindent +tells @code{make} to look for any prerequisite whose name ends in @file{.h} +in the directory @file{../headers} if the file is not found in the current +directory. + +If several @code{vpath} patterns match the prerequisite file's name, then +@code{make} processes each matching @code{vpath} directive one by one, +searching all the directories mentioned in each directive. @code{make} +handles multiple @code{vpath} directives in the order in which they +appear in the makefile; multiple directives with the same pattern are +independent of each other. + +@need 750 +Thus, + +@example +@group +vpath %.c foo +vpath % blish +vpath %.c bar +@end group +@end example + +@noindent +will look for a file ending in @samp{.c} in @file{foo}, then +@file{blish}, then @file{bar}, while + +@example +@group +vpath %.c foo:bar +vpath % blish +@end group +@end example + +@noindent +will look for a file ending in @samp{.c} in @file{foo}, then +@file{bar}, then @file{blish}. + +@node Search Algorithm, Recipes/Search, Selective Search, Directory Search +@subsection How Directory Searches are Performed +@cindex algorithm for directory search +@cindex directory search algorithm + +When a prerequisite is found through directory search, regardless of type +(general or selective), the pathname located may not be the one that +@code{make} actually provides you in the prerequisite list. Sometimes +the path discovered through directory search is thrown away. + +The algorithm @code{make} uses to decide whether to keep or abandon a +path found via directory search is as follows: + +@enumerate +@item +If a target file does not exist at the path specified in the makefile, +directory search is performed. + +@item +If the directory search is successful, that path is kept and this file +is tentatively stored as the target. + +@item +All prerequisites of this target are examined using this same method. + +@item +After processing the prerequisites, the target may or may not need to be +rebuilt: + +@enumerate a +@item +If the target does @emph{not} need to be rebuilt, the path to the file +found during directory search is used for any prerequisite lists which +contain this target. In short, if @code{make} doesn't need to rebuild +the target then you use the path found via directory search. + +@item +If the target @emph{does} need to be rebuilt (is out-of-date), the +pathname found during directory search is @emph{thrown away}, and the +target is rebuilt using the file name specified in the makefile. In +short, if @code{make} must rebuild, then the target is rebuilt locally, +not in the directory found via directory search. +@end enumerate +@end enumerate + +This algorithm may seem complex, but in practice it is quite often +exactly what you want. + +@cindex traditional directory search (GPATH) +@cindex directory search, traditional (GPATH) +Other versions of @code{make} use a simpler algorithm: if the file does +not exist, and it is found via directory search, then that pathname is +always used whether or not the target needs to be built. Thus, if the +target is rebuilt it is created at the pathname discovered during +directory search. + +@vindex GPATH +If, in fact, this is the behavior you want for some or all of your +directories, you can use the @code{GPATH} variable to indicate this to +@code{make}. + +@code{GPATH} has the same syntax and format as @code{VPATH} (that is, a +space- or colon-delimited list of pathnames). If an out-of-date target +is found by directory search in a directory that also appears in +@code{GPATH}, then that pathname is not thrown away. The target is +rebuilt using the expanded path. + +@node Recipes/Search, Implicit/Search, Search Algorithm, Directory Search +@subsection Writing Recipes with Directory Search +@cindex recipes, and directory search +@cindex directory search (@code{VPATH}), and recipes + +When a prerequisite is found in another directory through directory search, +this cannot change the recipe of the rule; they will execute as written. +Therefore, you must write the recipe with care so that it will look for +the prerequisite in the directory where @code{make} finds it. + +This is done with the @dfn{automatic variables} such as @samp{$^} +(@pxref{Automatic Variables}). +For instance, the value of @samp{$^} is a +list of all the prerequisites of the rule, including the names of +the directories in which they were found, and the value of +@samp{$@@} is the target. Thus:@refill + +@example +foo.o : foo.c + cc -c $(CFLAGS) $^ -o $@@ +@end example + +@noindent +(The variable @code{CFLAGS} exists so you can specify flags for C +compilation by implicit rules; we use it here for consistency so it will +affect all C compilations uniformly; +@pxref{Implicit Variables, ,Variables Used by Implicit Rules}.) + +Often the prerequisites include header files as well, which you do not +want to mention in the recipe. The automatic variable @samp{$<} is +just the first prerequisite: + +@example +VPATH = src:../headers +foo.o : foo.c defs.h hack.h + cc -c $(CFLAGS) $< -o $@@ +@end example + +@node Implicit/Search, Libraries/Search, Recipes/Search, Directory Search +@subsection Directory Search and Implicit Rules +@cindex @code{VPATH}, and implicit rules +@cindex directory search (@code{VPATH}), and implicit rules +@cindex search path for prerequisites (@code{VPATH}), and implicit rules +@cindex implicit rule, and directory search +@cindex implicit rule, and @code{VPATH} +@cindex rule, implicit, and directory search +@cindex rule, implicit, and @code{VPATH} + +The search through the directories specified in @code{VPATH} or with +@code{vpath} also happens during consideration of implicit rules +(@pxref{Implicit Rules, ,Using Implicit Rules}). + +For example, when a file @file{foo.o} has no explicit rule, @code{make} +considers implicit rules, such as the built-in rule to compile +@file{foo.c} if that file exists. If such a file is lacking in the +current directory, the appropriate directories are searched for it. If +@file{foo.c} exists (or is mentioned in the makefile) in any of the +directories, the implicit rule for C compilation is applied. + +The recipes of implicit rules normally use automatic variables as a +matter of necessity; consequently they will use the file names found by +directory search with no extra effort. + +@node Libraries/Search, , Implicit/Search, Directory Search +@subsection Directory Search for Link Libraries +@cindex link libraries, and directory search +@cindex libraries for linking, directory search +@cindex directory search (@code{VPATH}), and link libraries +@cindex @code{VPATH}, and link libraries +@cindex search path for prerequisites (@code{VPATH}), and link libraries +@cindex @code{-l} (library search) +@cindex link libraries, patterns matching +@cindex @code{.LIBPATTERNS}, and link libraries +@vindex .LIBPATTERNS + +Directory search applies in a special way to libraries used with the +linker. This special feature comes into play when you write a prerequisite +whose name is of the form @samp{-l@var{name}}. (You can tell something +strange is going on here because the prerequisite is normally the name of a +file, and the @emph{file name} of a library generally looks like +@file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill + +When a prerequisite's name has the form @samp{-l@var{name}}, @code{make} +handles it specially by searching for the file @file{lib@var{name}.so}, +and, if it is not found, for the file @file{lib@var{name}.a} in the current +directory, in directories specified by matching @code{vpath} +search paths and the @code{VPATH} search path, and then in the +directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib} +(normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of +@code{make} behave as if @var{prefix} is defined to be the root of the +DJGPP installation tree). + +For example, if there is a @file{/usr/lib/libcurses.a} library on your +system (and no @file{/usr/lib/libcurses.so} file), then + +@example +@group +foo : foo.c -lcurses + cc $^ -o $@@ +@end group +@end example + +@noindent +would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to +be executed when @file{foo} is older than @file{foo.c} or than +@file{/usr/lib/libcurses.a}.@refill + +Although the default set of files to be searched for is +@file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable +via the @code{.LIBPATTERNS} variable. Each word in the value of this +variable is a pattern string. When a prerequisite like +@samp{-l@var{name}} is seen, @code{make} will replace the percent in +each pattern in the list with @var{name} and perform the above directory +searches using each library filename. + +The default value for @code{.LIBPATTERNS} is @samp{lib%.so lib%.a}, +which provides the default behavior described above. + +You can turn off link library expansion completely by setting this +variable to an empty value. + +@node Phony Targets, Force Targets, Directory Search, Rules +@section Phony Targets +@cindex phony targets +@cindex targets, phony +@cindex targets without a file + +A phony target is one that is not really the name of a file; rather it +is just a name for a recipe to be executed when you make an explicit +request. There are two reasons to use a phony target: to avoid a +conflict with a file of the same name, and to improve performance. + +If you write a rule whose recipe will not create the target file, the +recipe will be executed every time the target comes up for remaking. +Here is an example: + +@example +@group +clean: + rm *.o temp +@end group +@end example + +@noindent +Because the @code{rm} command does not create a file named @file{clean}, +probably no such file will ever exist. Therefore, the @code{rm} command +will be executed every time you say @samp{make clean}. +@cindex @code{rm} (shell command) + +@findex .PHONY +The phony target will cease to work if anything ever does create a file +named @file{clean} in this directory. Since it has no prerequisites, the +file @file{clean} would inevitably be considered up to date, and its +recipe would not be executed. To avoid this problem, you can explicitly +declare the target to be phony, using the special target @code{.PHONY} +(@pxref{Special Targets, ,Special Built-in Target Names}) as follows: + +@example +.PHONY : clean +@end example + +@noindent +Once this is done, @samp{make clean} will run the recipe regardless of +whether there is a file named @file{clean}. + +Since it knows that phony targets do not name actual files that could be +remade from other files, @code{make} skips the implicit rule search for +phony targets (@pxref{Implicit Rules}). This is why declaring a target +phony is good for performance, even if you are not worried about the +actual file existing. + +Thus, you first write the line that states that @code{clean} is a +phony target, then you write the rule, like this: + +@example +@group +.PHONY: clean +clean: + rm *.o temp +@end group +@end example + +Another example of the usefulness of phony targets is in conjunction +with recursive invocations of @code{make} (for more information, see +@ref{Recursion, ,Recursive Use of @code{make}}). In this case the +makefile will often contain a variable which lists a number of +subdirectories to be built. One way to handle this is with one rule +whose recipe is a shell loop over the subdirectories, like this: + +@example +@group +SUBDIRS = foo bar baz + +subdirs: + for dir in $(SUBDIRS); do \ + $(MAKE) -C $$dir; \ + done +@end group +@end example + +There are problems with this method, however. First, any error +detected in a submake is ignored by this rule, so it will continue +to build the rest of the directories even when one fails. This can be +overcome by adding shell commands to note the error and exit, but then +it will do so even if @code{make} is invoked with the @code{-k} +option, which is unfortunate. Second, and perhaps more importantly, +you cannot take advantage of @code{make}'s ability to build targets in +parallel (@pxref{Parallel, ,Parallel Execution}), since there is only +one rule. + +By declaring the subdirectories as phony targets (you must do this as +the subdirectory obviously always exists; otherwise it won't be built) +you can remove these problems: + +@example +@group +SUBDIRS = foo bar baz + +.PHONY: subdirs $(SUBDIRS) + +subdirs: $(SUBDIRS) + +$(SUBDIRS): + $(MAKE) -C $@@ + +foo: baz +@end group +@end example + +Here we've also declared that the @file{foo} subdirectory cannot be +built until after the @file{baz} subdirectory is complete; this kind of +relationship declaration is particularly important when attempting +parallel builds. + +A phony target should not be a prerequisite of a real target file; if it +is, its recipe will be run every time @code{make} goes to update that +file. As long as a phony target is never a prerequisite of a real +target, the phony target recipe will be executed only when the phony +target is a specified goal (@pxref{Goals, ,Arguments to Specify the +Goals}). + +Phony targets can have prerequisites. When one directory contains multiple +programs, it is most convenient to describe all of the programs in one +makefile @file{./Makefile}. Since the target remade by default will be the +first one in the makefile, it is common to make this a phony target named +@samp{all} and give it, as prerequisites, all the individual programs. For +example: + +@example +all : prog1 prog2 prog3 +.PHONY : all + +prog1 : prog1.o utils.o + cc -o prog1 prog1.o utils.o + +prog2 : prog2.o + cc -o prog2 prog2.o + +prog3 : prog3.o sort.o utils.o + cc -o prog3 prog3.o sort.o utils.o +@end example + +@noindent +Now you can say just @samp{make} to remake all three programs, or +specify as arguments the ones to remake (as in @samp{make prog1 +prog3}). Phoniness is not inherited: the prerequisites of a phony +target are not themselves phony, unless explicitly declared to be so. + +When one phony target is a prerequisite of another, it serves as a subroutine +of the other. For example, here @samp{make cleanall} will delete the +object files, the difference files, and the file @file{program}: + +@example +.PHONY: cleanall cleanobj cleandiff + +cleanall : cleanobj cleandiff + rm program + +cleanobj : + rm *.o + +cleandiff : + rm *.diff +@end example + +@node Force Targets, Empty Targets, Phony Targets, Rules +@section Rules without Recipes or Prerequisites +@cindex force targets +@cindex targets, force +@cindex @code{FORCE} +@cindex rule, no recipe or prerequisites + +If a rule has no prerequisites or recipe, and the target of the rule +is a nonexistent file, then @code{make} imagines this target to have +been updated whenever its rule is run. This implies that all targets +depending on this one will always have their recipe run. + +An example will illustrate this: + +@example +@group +clean: FORCE + rm $(objects) +FORCE: +@end group +@end example + +Here the target @samp{FORCE} satisfies the special conditions, so the +target @file{clean} that depends on it is forced to run its recipe. +There is nothing special about the name @samp{FORCE}, but that is one +name commonly used this way. + +As you can see, using @samp{FORCE} this way has the same results as using +@samp{.PHONY: clean}. + +Using @samp{.PHONY} is more explicit and more efficient. However, +other versions of @code{make} do not support @samp{.PHONY}; thus +@samp{FORCE} appears in many makefiles. @xref{Phony Targets}. + +@node Empty Targets, Special Targets, Force Targets, Rules +@section Empty Target Files to Record Events +@cindex empty targets +@cindex targets, empty +@cindex recording events with empty targets + +The @dfn{empty target} is a variant of the phony target; it is used to hold +recipes for an action that you request explicitly from time to time. +Unlike a phony target, this target file can really exist; but the file's +contents do not matter, and usually are empty. + +The purpose of the empty target file is to record, with its +last-modification time, when the rule's recipe was last executed. It +does so because one of the commands in the recipe is a @code{touch} +command to update the target file. + +The empty target file should have some prerequisites (otherwise it +doesn't make sense). When you ask to remake the empty target, the +recipe is executed if any prerequisite is more recent than the target; +in other words, if a prerequisite has changed since the last time you +remade the target. Here is an example: + +@example +print: foo.c bar.c + lpr -p $? + touch print +@end example +@cindex @code{print} target +@cindex @code{lpr} (shell command) +@cindex @code{touch} (shell command) + +@noindent +With this rule, @samp{make print} will execute the @code{lpr} command if +either source file has changed since the last @samp{make print}. The +automatic variable @samp{$?} is used to print only those files that have +changed (@pxref{Automatic Variables}). + +@node Special Targets, Multiple Targets, Empty Targets, Rules +@section Special Built-in Target Names +@cindex special targets +@cindex built-in special targets +@cindex targets, built-in special + +Certain names have special meanings if they appear as targets. + +@table @code +@findex .PHONY +@item .PHONY + +The prerequisites of the special target @code{.PHONY} are considered to +be phony targets. When it is time to consider such a target, +@code{make} will run its recipe unconditionally, regardless of +whether a file with that name exists or what its last-modification +time is. @xref{Phony Targets, ,Phony Targets}. + +@findex .SUFFIXES +@item .SUFFIXES + +The prerequisites of the special target @code{.SUFFIXES} are the list +of suffixes to be used in checking for suffix rules. +@xref{Suffix Rules, , Old-Fashioned Suffix Rules}. + +@findex .DEFAULT +@item .DEFAULT + +The recipe specified for @code{.DEFAULT} is used for any target for +which no rules are found (either explicit rules or implicit rules). +@xref{Last Resort}. If a @code{.DEFAULT} recipe is specified, every +file mentioned as a prerequisite, but not as a target in a rule, will have +that recipe executed on its behalf. @xref{Implicit Rule Search, +,Implicit Rule Search Algorithm}. + +@findex .PRECIOUS +@item .PRECIOUS +@cindex precious targets +@cindex preserving with @code{.PRECIOUS} + +The targets which @code{.PRECIOUS} depends on are given the following +special treatment: if @code{make} is killed or interrupted during the +execution of their recipes, the target is not deleted. +@xref{Interrupts, ,Interrupting or Killing @code{make}}. Also, if the +target is an intermediate file, it will not be deleted after it is no +longer needed, as is normally done. @xref{Chained Rules, ,Chains of +Implicit Rules}. In this latter respect it overlaps with the +@code{.SECONDARY} special target. + +You can also list the target pattern of an implicit rule (such as +@samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS} +to preserve intermediate files created by rules whose target patterns +match that file's name. + +@findex .INTERMEDIATE +@item .INTERMEDIATE +@cindex intermediate targets, explicit + +The targets which @code{.INTERMEDIATE} depends on are treated as +intermediate files. @xref{Chained Rules, ,Chains of Implicit Rules}. +@code{.INTERMEDIATE} with no prerequisites has no effect. + +@findex .SECONDARY +@item .SECONDARY +@cindex secondary targets +@cindex preserving with @code{.SECONDARY} + +The targets which @code{.SECONDARY} depends on are treated as +intermediate files, except that they are never automatically deleted. +@xref{Chained Rules, ,Chains of Implicit Rules}. + +@code{.SECONDARY} with no prerequisites causes all targets to be treated +as secondary (i.e., no target is removed because it is considered +intermediate). + +@findex .SECONDEXPANSION +@item .SECONDEXPANSION + +If @code{.SECONDEXPANSION} is mentioned as a target anywhere in the +makefile, then all prerequisite lists defined @emph{after} it appears +will be expanded a second time after all makefiles have been read in. +@xref{Secondary Expansion, ,Secondary Expansion}. + +@findex .DELETE_ON_ERROR +@item .DELETE_ON_ERROR +@cindex removing targets on failure + +If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the +makefile, then @code{make} will delete the target of a rule if it has +changed and its recipe exits with a nonzero exit status, just as it +does when it receives a signal. @xref{Errors, ,Errors in Recipes}. + +@findex .IGNORE +@item .IGNORE + +If you specify prerequisites for @code{.IGNORE}, then @code{make} will +ignore errors in execution of the recipe for those particular files. +The recipe for @code{.IGNORE} (if any) is ignored. + +If mentioned as a target with no prerequisites, @code{.IGNORE} says to +ignore errors in execution of recipes for all files. This usage of +@samp{.IGNORE} is supported only for historical compatibility. Since +this affects every recipe in the makefile, it is not very useful; we +recommend you use the more selective ways to ignore errors in specific +recipes. @xref{Errors, ,Errors in Recipes}. + +@findex .LOW_RESOLUTION_TIME +@item .LOW_RESOLUTION_TIME + +If you specify prerequisites for @code{.LOW_RESOLUTION_TIME}, +@command{make} assumes that these files are created by commands that +generate low resolution time stamps. The recipe for the +@code{.LOW_RESOLUTION_TIME} target are ignored. + +The high resolution file time stamps of many modern file systems +lessen the chance of @command{make} incorrectly concluding that a file +is up to date. Unfortunately, some hosts do not provide a way to set a +high resolution file time stamp, so commands like @samp{cp -p} that +explicitly set a file's time stamp must discard its subsecond part. +If a file is created by such a command, you should list it as a +prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} +does not mistakenly conclude that the file is out of date. For +example: + +@example +@group +.LOW_RESOLUTION_TIME: dst +dst: src + cp -p src dst +@end group +@end example + +Since @samp{cp -p} discards the subsecond part of @file{src}'s time +stamp, @file{dst} is typically slightly older than @file{src} even when +it is up to date. The @code{.LOW_RESOLUTION_TIME} line causes +@command{make} to consider @file{dst} to be up to date if its time stamp +is at the start of the same second that @file{src}'s time stamp is in. + +Due to a limitation of the archive format, archive member time stamps +are always low resolution. You need not list archive members as +prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this +automatically. + +@findex .SILENT +@item .SILENT + +If you specify prerequisites for @code{.SILENT}, then @code{make} will +not print the recipe used to remake those particular files before +executing them. The recipe for @code{.SILENT} is ignored. + +If mentioned as a target with no prerequisites, @code{.SILENT} says not +to print any recipes before executing them. This usage of +@samp{.SILENT} is supported only for historical compatibility. We +recommend you use the more selective ways to silence specific recipes. +@xref{Echoing, ,Recipe Echoing}. If you want to silence all recipes +for a particular run of @code{make}, use the @samp{-s} or +@w{@samp{--silent}} option (@pxref{Options Summary}). + +@findex .EXPORT_ALL_VARIABLES +@item .EXPORT_ALL_VARIABLES + +Simply by being mentioned as a target, this tells @code{make} to +export all variables to child processes by default. +@xref{Variables/Recursion, ,Communicating Variables to a +Sub-@code{make}}. + +@findex .NOTPARALLEL +@item .NOTPARALLEL +@cindex parallel execution, overriding + +If @code{.NOTPARALLEL} is mentioned as a target, then this invocation +of @code{make} will be run serially, even if the @samp{-j} option is +given. Any recursively invoked @code{make} command will still run +recipes in parallel (unless its makefile also contains this target). +Any prerequisites on this target are ignored. + +@findex .ONESHELL +@item .ONESHELL +@cindex recipe execution, single invocation + +If @code{.ONESHELL} is mentioned as a target, then when a target is +built all lines of the recipe will be given to a single invocation of +the shell rather than each line being invoked separately +(@pxref{Execution, ,Recipe Execution}). + +@findex .POSIX +@item .POSIX +@cindex POSIX-conforming mode, setting + +If @code{.POSIX} is mentioned as a target, then the makefile will be +parsed and run in POSIX-conforming mode. This does @emph{not} mean +that only POSIX-conforming makefiles will be accepted: all advanced +GNU @code{make} features are still available. Rather, this target +causes @code{make} to behave as required by POSIX in those areas +where @code{make}'s default behavior differs. + +In particular, if this target is mentioned then recipes will be +invoked as if the shell had been passed the @code{-e} flag: the first +failing command in a recipe will cause the recipe to fail immediately. +@end table + +Any defined implicit rule suffix also counts as a special target if it +appears as a target, and so does the concatenation of two suffixes, such +as @samp{.c.o}. These targets are suffix rules, an obsolete way of +defining implicit rules (but a way still widely used). In principle, any +target name could be special in this way if you break it in two and add +both pieces to the suffix list. In practice, suffixes normally begin with +@samp{.}, so these special target names also begin with @samp{.}. +@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. + +@node Multiple Targets, Multiple Rules, Special Targets, Rules +@section Multiple Targets in a Rule +@cindex multiple targets +@cindex several targets in a rule +@cindex targets, multiple +@cindex rule, with multiple targets + +A rule with multiple targets is equivalent to writing many rules, each with +one target, and all identical aside from that. The same recipe applies to +all the targets, but its effect may vary because you can substitute the +actual target name into the recipe using @samp{$@@}. The rule contributes +the same prerequisites to all the targets also. + +This is useful in two cases. + +@itemize @bullet +@item +You want just prerequisites, no recipe. For example: + +@example +kbd.o command.o files.o: command.h +@end example + +@noindent +gives an additional prerequisite to each of the three object files +mentioned. + +@item +Similar recipes work for all the targets. The recipes do not need +to be absolutely identical, since the automatic variable @samp{$@@} +can be used to substitute the particular target to be remade into the +commands (@pxref{Automatic Variables}). For example: + +@example +@group +bigoutput littleoutput : text.g + generate text.g -$(subst output,,$@@) > $@@ +@end group +@end example +@findex subst + +@noindent +is equivalent to + +@example +bigoutput : text.g + generate text.g -big > bigoutput +littleoutput : text.g + generate text.g -little > littleoutput +@end example + +@noindent +Here we assume the hypothetical program @code{generate} makes two +types of output, one if given @samp{-big} and one if given +@samp{-little}. +@xref{Text Functions, ,Functions for String Substitution and Analysis}, +for an explanation of the @code{subst} function. +@end itemize + +Suppose you would like to vary the prerequisites according to the +target, much as the variable @samp{$@@} allows you to vary the recipe. +You cannot do this with multiple targets in an ordinary rule, but you +can do it with a @dfn{static pattern rule}. @xref{Static Pattern, +,Static Pattern Rules}. + +@node Multiple Rules, Static Pattern, Multiple Targets, Rules +@section Multiple Rules for One Target +@cindex multiple rules for one target +@cindex several rules for one target +@cindex rule, multiple for one target +@cindex target, multiple rules for one + +One file can be the target of several rules. All the prerequisites +mentioned in all the rules are merged into one list of prerequisites for +the target. If the target is older than any prerequisite from any rule, +the recipe is executed. + +There can only be one recipe to be executed for a file. If more than +one rule gives a recipe for the same file, @code{make} uses the last +one given and prints an error message. (As a special case, if the +file's name begins with a dot, no error message is printed. This odd +behavior is only for compatibility with other implementations of +@code{make}@dots{} you should avoid using it). Occasionally it is +useful to have the same target invoke multiple recipes which are +defined in different parts of your makefile; you can use +@dfn{double-colon rules} (@pxref{Double-Colon}) for this. + +An extra rule with just prerequisites can be used to give a few extra +prerequisites to many files at once. For example, makefiles often +have a variable, such as @code{objects}, containing a list of all the +compiler output files in the system being made. An easy way to say +that all of them must be recompiled if @file{config.h} changes is to +write the following: + +@example +objects = foo.o bar.o +foo.o : defs.h +bar.o : defs.h test.h +$(objects) : config.h +@end example + +This could be inserted or taken out without changing the rules that really +specify how to make the object files, making it a convenient form to use if +you wish to add the additional prerequisite intermittently. + +Another wrinkle is that the additional prerequisites could be +specified with a variable that you set with a command line argument to +@code{make} (@pxref{Overriding, ,Overriding Variables}). For example, + +@example +@group +extradeps= +$(objects) : $(extradeps) +@end group +@end example + +@noindent +means that the command @samp{make extradeps=foo.h} will consider +@file{foo.h} as a prerequisite of each object file, but plain @samp{make} +will not. + +If none of the explicit rules for a target has a recipe, then @code{make} +searches for an applicable implicit rule to find one +@pxref{Implicit Rules, ,Using Implicit Rules}). + +@node Static Pattern, Double-Colon, Multiple Rules, Rules +@section Static Pattern Rules +@cindex static pattern rule +@cindex rule, static pattern +@cindex pattern rules, static (not implicit) +@cindex varying prerequisites +@cindex prerequisites, varying (static pattern) + +@dfn{Static pattern rules} are rules which specify multiple targets and +construct the prerequisite names for each target based on the target name. +They are more general than ordinary rules with multiple targets because the +targets do not have to have identical prerequisites. Their prerequisites must +be @emph{analogous}, but not necessarily @emph{identical}. + +@menu +* Static Usage:: The syntax of static pattern rules. +* Static versus Implicit:: When are they better than implicit rules? +@end menu + +@node Static Usage, Static versus Implicit, Static Pattern, Static Pattern +@subsection Syntax of Static Pattern Rules +@cindex static pattern rule, syntax of +@cindex pattern rules, static, syntax of + +Here is the syntax of a static pattern rule: + +@example +@var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{} + @var{recipe} + @dots{} +@end example + +@noindent +The @var{targets} list specifies the targets that the rule applies to. +The targets can contain wildcard characters, just like the targets of +ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File +Names}). + +@cindex target pattern, static (not implicit) +@cindex stem +The @var{target-pattern} and @var{prereq-patterns} say how to compute the +prerequisites of each target. Each target is matched against the +@var{target-pattern} to extract a part of the target name, called the +@dfn{stem}. This stem is substituted into each of the @var{prereq-patterns} +to make the prerequisite names (one from each @var{prereq-pattern}). + +Each pattern normally contains the character @samp{%} just once. When the +@var{target-pattern} matches a target, the @samp{%} can match any part of +the target name; this part is called the @dfn{stem}. The rest of the +pattern must match exactly. For example, the target @file{foo.o} matches +the pattern @samp{%.o}, with @samp{foo} as the stem. The targets +@file{foo.c} and @file{foo.out} do not match that pattern.@refill + +@cindex prerequisite pattern, static (not implicit) +The prerequisite names for each target are made by substituting the stem +for the @samp{%} in each prerequisite pattern. For example, if one +prerequisite pattern is @file{%.c}, then substitution of the stem +@samp{foo} gives the prerequisite name @file{foo.c}. It is legitimate +to write a prerequisite pattern that does not contain @samp{%}; then this +prerequisite is the same for all targets. + +@cindex @code{%}, quoting in static pattern +@cindex @code{%}, quoting with @code{\} (backslash) +@cindex @code{\} (backslash), to quote @code{%} +@cindex backslash (@code{\}), to quote @code{%} +@cindex quoting @code{%}, in static pattern +@samp{%} characters in pattern rules can be quoted with preceding +backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} +characters can be quoted with more backslashes. Backslashes that quote +@samp{%} characters or other backslashes are removed from the pattern +before it is compared to file names or has a stem substituted into it. +Backslashes that are not in danger of quoting @samp{%} characters go +unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has +@samp{the%weird\} preceding the operative @samp{%} character, and +@samp{pattern\\} following it. The final two backslashes are left alone +because they cannot affect any @samp{%} character.@refill + +Here is an example, which compiles each of @file{foo.o} and @file{bar.o} +from the corresponding @file{.c} file: + +@example +@group +objects = foo.o bar.o + +all: $(objects) + +$(objects): %.o: %.c + $(CC) -c $(CFLAGS) $< -o $@@ +@end group +@end example + +@noindent +Here @samp{$<} is the automatic variable that holds the name of the +prerequisite and @samp{$@@} is the automatic variable that holds the name +of the target; see @ref{Automatic Variables}. + +Each target specified must match the target pattern; a warning is issued +for each target that does not. If you have a list of files, only some of +which will match the pattern, you can use the @code{filter} function to +remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): + +@example +files = foo.elc bar.o lose.o + +$(filter %.o,$(files)): %.o: %.c + $(CC) -c $(CFLAGS) $< -o $@@ +$(filter %.elc,$(files)): %.elc: %.el + emacs -f batch-byte-compile $< +@end example + +@noindent +In this example the result of @samp{$(filter %.o,$(files))} is +@file{bar.o lose.o}, and the first static pattern rule causes each of +these object files to be updated by compiling the corresponding C source +file. The result of @w{@samp{$(filter %.elc,$(files))}} is +@file{foo.elc}, so that file is made from @file{foo.el}.@refill + +Another example shows how to use @code{$*} in static pattern rules: +@vindex $*@r{, and static pattern} + +@example +@group +bigoutput littleoutput : %output : text.g + generate text.g -$* > $@@ +@end group +@end example + +@noindent +When the @code{generate} command is run, @code{$*} will expand to the +stem, either @samp{big} or @samp{little}. + +@node Static versus Implicit, , Static Usage, Static Pattern +@subsection Static Pattern Rules versus Implicit Rules +@cindex rule, static pattern versus implicit +@cindex static pattern rule, versus implicit + +A static pattern rule has much in common with an implicit rule defined as a +pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). +Both have a pattern for the target and patterns for constructing the +names of prerequisites. The difference is in how @code{make} decides +@emph{when} the rule applies. + +An implicit rule @emph{can} apply to any target that matches its pattern, +but it @emph{does} apply only when the target has no recipe otherwise +specified, and only when the prerequisites can be found. If more than one +implicit rule appears applicable, only one applies; the choice depends on +the order of rules. + +By contrast, a static pattern rule applies to the precise list of targets +that you specify in the rule. It cannot apply to any other target and it +invariably does apply to each of the targets specified. If two conflicting +rules apply, and both have recipes, that's an error. + +The static pattern rule can be better than an implicit rule for these +reasons: + +@itemize @bullet +@item +You may wish to override the usual implicit rule for a few +files whose names cannot be categorized syntactically but +can be given in an explicit list. + +@item +If you cannot be sure of the precise contents of the directories +you are using, you may not be sure which other irrelevant files +might lead @code{make} to use the wrong implicit rule. The choice +might depend on the order in which the implicit rule search is done. +With static pattern rules, there is no uncertainty: each rule applies +to precisely the targets specified. +@end itemize + +@node Double-Colon, Automatic Prerequisites, Static Pattern, Rules +@section Double-Colon Rules +@cindex double-colon rules +@cindex rule, double-colon (@code{::}) +@cindex multiple rules for one target (@code{::}) +@cindex @code{::} rules (double-colon) + +@dfn{Double-colon} rules are explicit rules written with @samp{::} +instead of @samp{:} after the target names. They are handled +differently from ordinary rules when the same target appears in more +than one rule. Pattern rules with double-colons have an entirely +different meaning (@pxref{Match-Anything Rules}). + +When a target appears in multiple rules, all the rules must be the same +type: all ordinary, or all double-colon. If they are double-colon, each +of them is independent of the others. Each double-colon rule's recipe +is executed if the target is older than any prerequisites of that rule. +If there are no prerequisites for that rule, its recipe is always +executed (even if the target already exists). This can result in +executing none, any, or all of the double-colon rules. + +Double-colon rules with the same target are in fact completely separate +from one another. Each double-colon rule is processed individually, just +as rules with different targets are processed. + +The double-colon rules for a target are executed in the order they appear +in the makefile. However, the cases where double-colon rules really make +sense are those where the order of executing the recipes would not matter. + +Double-colon rules are somewhat obscure and not often very useful; they +provide a mechanism for cases in which the method used to update a target +differs depending on which prerequisite files caused the update, and such +cases are rare. + +Each double-colon rule should specify a recipe; if it does not, an +implicit rule will be used if one applies. +@xref{Implicit Rules, ,Using Implicit Rules}. + +@node Automatic Prerequisites, , Double-Colon, Rules +@section Generating Prerequisites Automatically +@cindex prerequisites, automatic generation +@cindex automatic generation of prerequisites +@cindex generating prerequisites automatically + +In the makefile for a program, many of the rules you need to write often +say only that some object file depends on some header +file. For example, if @file{main.c} uses @file{defs.h} via an +@code{#include}, you would write: + +@example +main.o: defs.h +@end example + +@noindent +You need this rule so that @code{make} knows that it must remake +@file{main.o} whenever @file{defs.h} changes. You can see that for a +large program you would have to write dozens of such rules in your +makefile. And, you must always be very careful to update the makefile +every time you add or remove an @code{#include}. +@cindex @code{#include} + +@cindex @code{-M} (to compiler) +To avoid this hassle, most modern C compilers can write these rules for +you, by looking at the @code{#include} lines in the source files. +Usually this is done with the @samp{-M} option to the compiler. +For example, the command: + +@example +cc -M main.c +@end example + +@noindent +generates the output: + +@example +main.o : main.c defs.h +@end example + +@noindent +Thus you no longer have to write all those rules yourself. +The compiler will do it for you. + +Note that such a prerequisite constitutes mentioning @file{main.o} in a +makefile, so it can never be considered an intermediate file by implicit +rule search. This means that @code{make} won't ever remove the file +after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}. + +@cindex @code{make depend} +With old @code{make} programs, it was traditional practice to use this +compiler feature to generate prerequisites on demand with a command like +@samp{make depend}. That command would create a file @file{depend} +containing all the automatically-generated prerequisites; then the +makefile could use @code{include} to read them in (@pxref{Include}). + +In GNU @code{make}, the feature of remaking makefiles makes this +practice obsolete---you need never tell @code{make} explicitly to +regenerate the prerequisites, because it always regenerates any makefile +that is out of date. @xref{Remaking Makefiles}. + +The practice we recommend for automatic prerequisite generation is to have +one makefile corresponding to each source file. For each source file +@file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists +what files the object file @file{@var{name}.o} depends on. That way +only the source files that have changed need to be rescanned to produce +the new prerequisites. + +Here is the pattern rule to generate a file of prerequisites (i.e., a makefile) +called @file{@var{name}.d} from a C source file called @file{@var{name}.c}: + +@smallexample +@group +%.d: %.c + @@set -e; rm -f $@@; \ + $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \ + sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \ + rm -f $@@.$$$$ +@end group +@end smallexample + +@noindent +@xref{Pattern Rules}, for information on defining pattern rules. The +@samp{-e} flag to the shell causes it to exit immediately if the +@code{$(CC)} command (or any other command) fails (exits with a +nonzero status). +@cindex @code{-e} (shell flag) + +@cindex @code{-MM} (to GNU compiler) +With the GNU C compiler, you may wish to use the @samp{-MM} flag instead +of @samp{-M}. This omits prerequisites on system header files. +@xref{Preprocessor Options, , Options Controlling the Preprocessor, +gcc.info, Using GNU CC}, for details. + +@cindex @code{sed} (shell command) +The purpose of the @code{sed} command is to translate (for example): + +@example +main.o : main.c defs.h +@end example + +@noindent +into: + +@example +main.o main.d : main.c defs.h +@end example + +@noindent +@cindex @code{.d} +This makes each @samp{.d} file depend on all the source and header files +that the corresponding @samp{.o} file depends on. @code{make} then +knows it must regenerate the prerequisites whenever any of the source or +header files changes. + +Once you've defined the rule to remake the @samp{.d} files, +you then use the @code{include} directive to read them all in. +@xref{Include}. For example: + +@example +@group +sources = foo.c bar.c + +include $(sources:.c=.d) +@end group +@end example + +@noindent +(This example uses a substitution variable reference to translate the +list of source files @samp{foo.c bar.c} into a list of prerequisite +makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full +information on substitution references.) Since the @samp{.d} files are +makefiles like any others, @code{make} will remake them as necessary +with no further work from you. @xref{Remaking Makefiles}. + +Note that the @samp{.d} files contain target definitions; you should +be sure to place the @code{include} directive @emph{after} the first, +default goal in your makefiles or run the risk of having a random +object file become the default goal. +@xref{How Make Works}. + +@node Recipes, Using Variables, Rules, Top +@chapter Writing Recipes in Rules +@cindex recipes +@cindex recipes, how to write +@cindex writing recipes + +The recipe of a rule consists of one or more shell command lines to +be executed, one at a time, in the order they appear. Typically, the +result of executing these commands is that the target of the rule is +brought up to date. + +Users use many different shell programs, but recipes in makefiles are +always interpreted by @file{/bin/sh} unless the makefile specifies +otherwise. @xref{Execution, ,Recipe Execution}. + +@menu +* Recipe Syntax:: Recipe syntax features and pitfalls. +* Echoing:: How to control when recipes are echoed. +* Execution:: How recipes are executed. +* Parallel:: How recipes can be executed in parallel. +* Errors:: What happens after a recipe execution error. +* Interrupts:: What happens when a recipe is interrupted. +* Recursion:: Invoking @code{make} from makefiles. +* Canned Recipes:: Defining canned recipes. +* Empty Recipes:: Defining useful, do-nothing recipes. +@end menu + +@node Recipe Syntax, Echoing, Recipes, Recipes +@section Recipe Syntax +@cindex recipe syntax +@cindex syntax of recipe + +Makefiles have the unusual property that there are really two distinct +syntaxes in one file. Most of the makefile uses @code{make} syntax +(@pxref{Makefiles, ,Writing Makefiles}). However, recipes are meant +to be interpreted by the shell and so they are written using shell +syntax. The @code{make} program does not try to understand shell +syntax: it performs only a very few specific translations on the +content of the recipe before handing it to the shell. + +Each line in the recipe must start with a tab (or the first character +in the value of the @code{.RECIPEPREFIX} variable; @pxref{Special +Variables}), except that the first recipe line may be attached to the +target-and-prerequisites line with a semicolon in between. @emph{Any} +line in the makefile that begins with a tab and appears in a ``rule +context'' (that is, after a rule has been started until another rule +or variable definition) will be considered part of a recipe for that +rule. Blank lines and lines of just comments may appear among the +recipe lines; they are ignored. + +Some consequences of these rules include: + +@itemize @bullet +@item +A blank line that begins with a tab is not blank: it's an empty +recipe (@pxref{Empty Recipes}). + +@cindex comments, in recipes +@cindex recipes, comments in +@cindex @code{#} (comments), in recipes +@item +A comment in a recipe is not a @code{make} comment; it will be +passed to the shell as-is. Whether the shell treats it as a comment +or not depends on your shell. + +@item +A variable definition in a ``rule context'' which is indented by a tab +as the first character on the line, will be considered part of a +recipe, not a @code{make} variable definition, and passed to the +shell. + +@item +A conditional expression (@code{ifdef}, @code{ifeq}, +etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule +context'' which is indented by a tab as the first character on the +line, will be considered part of a recipe and be passed to the shell. + +@end itemize + +@menu +* Splitting Lines:: Breaking long recipe lines for readability. +* Variables in Recipes:: Using @code{make} variables in recipes. +@end menu + +@node Splitting Lines, Variables in Recipes, Recipe Syntax, Recipe Syntax +@subsection Splitting Recipe Lines +@cindex recipes, splitting +@cindex splitting recipes +@cindex recipes, backslash (@code{\}) in +@cindex recipes, quoting newlines in +@cindex backslash (@code{\}), in recipes +@cindex @code{\} (backslash), in recipes +@cindex quoting newline, in recipes +@cindex newline, quoting, in recipes + +One of the few ways in which @code{make} does interpret recipes is +checking for a backslash just before the newline. As in normal +makefile syntax, a single logical recipe line can be split into +multiple physical lines in the makefile by placing a backslash before +each newline. A sequence of lines like this is considered a single +recipe line, and one instance of the shell will be invoked to run it. + +However, in contrast to how they are treated in other places in a +makefile, backslash-newline pairs are @emph{not} removed from the +recipe. Both the backslash and the newline characters are preserved +and passed to the shell. How the backslash-newline is interpreted +depends on your shell. If the first character of the next line after +the backslash-newline is the recipe prefix character (a tab by +default; @pxref{Special Variables}), then that character (and only +that character) is removed. Whitespace is never added to the recipe. + +For example, the recipe for the all target in this makefile: + +@example +@group +all : + @@echo no\ +space + @@echo no\ + space + @@echo one \ + space + @@echo one\ + space +@end group +@end example + +@noindent +consists of four separate shell commands where the output is: + +@example +@group +nospace +nospace +one space +one space +@end group +@end example + +As a more complex example, this makefile: + +@example +@group +all : ; @@echo 'hello \ + world' ; echo "hello \ + world" +@end group +@end example + +@noindent +will invoke one shell with a command of: + +@example +@group +echo 'hello \ +world' ; echo "hello \ + world" +@end group +@end example + +@noindent +which, according to shell quoting rules, will yield the following output: + +@example +@group +hello \ +world +hello world +@end group +@end example + +@noindent +Notice how the backslash/newline pair was removed inside the string +quoted with double quotes (@code{"@dots{}"}), but not from the string +quoted with single quotes (@code{'@dots{}'}). This is the way the +default shell (@file{/bin/sh}) handles backslash/newline pairs. If +you specify a different shell in your makefiles it may treat them +differently. + +Sometimes you want to split a long line inside of single quotes, but +you don't want the backslash-newline to appear in the quoted content. +This is often the case when passing scripts to languages such as Perl, +where extraneous backslashes inside the script can change its meaning +or even be a syntax error. One simple way of handling this is to +place the quoted string, or even the entire command, into a +@code{make} variable then use the variable in the recipe. In this +situation the newline quoting rules for makefiles will be used, and +the backslash-newline will be removed. If we rewrite our example +above using this method: + +@example +@group +HELLO = 'hello \ +world' + +all : ; @@echo $(HELLO) +@end group +@end example + +@noindent +we will get output like this: + +@example +@group +hello world +@end group +@end example + +If you like, you can also use target-specific variables +(@pxref{Target-specific, ,Target-specific Variable Values}) to obtain +a tighter correspondence between the variable and the recipe that +uses it. + +@node Variables in Recipes, , Splitting Lines, Recipe Syntax +@subsection Using Variables in Recipes +@cindex variable references in recipes +@cindex recipes, using variables in + +The other way in which @code{make} processes recipes is by expanding +any variable references in them (@pxref{Reference,Basics of Variable +References}). This occurs after make has finished reading all the +makefiles and the target is determined to be out of date; so, the +recipes for targets which are not rebuilt are never expanded. + +Variable and function references in recipes have identical syntax and +semantics to references elsewhere in the makefile. They also have the +same quoting rules: if you want a dollar sign to appear in your +recipe, you must double it (@samp{$$}). For shells like the default +shell, that use dollar signs to introduce variables, it's important to +keep clear in your mind whether the variable you want to reference is +a @code{make} variable (use a single dollar sign) or a shell variable +(use two dollar signs). For example: + +@example +@group +LIST = one two three +all: + for i in $(LIST); do \ + echo $$i; \ + done +@end group +@end example + +@noindent +results in the following command being passed to the shell: + +@example +@group +for i in one two three; do \ + echo $i; \ +done +@end group +@end example + +@noindent +which generates the expected result: + +@example +@group +one +two +three +@end group +@end example + +@node Echoing, Execution, Recipe Syntax, Recipes +@section Recipe Echoing +@cindex echoing of recipes +@cindex silent operation +@cindex @code{@@} (in recipes) +@cindex recipes, echoing +@cindex printing of recipes + +Normally @code{make} prints each line of the recipe before it is +executed. We call this @dfn{echoing} because it gives the appearance +that you are typing the lines yourself. + +When a line starts with @samp{@@}, the echoing of that line is suppressed. +The @samp{@@} is discarded before the line is passed to the shell. +Typically you would use this for a command whose only effect is to print +something, such as an @code{echo} command to indicate progress through +the makefile: + +@example +@@echo About to make distribution files +@end example + +@cindex @code{-n} +@cindex @code{--just-print} +@cindex @code{--dry-run} +@cindex @code{--recon} +When @code{make} is given the flag @samp{-n} or @samp{--just-print} it +only echoes most recipes, without executing them. @xref{Options +Summary, ,Summary of Options}. In this case even the recipe lines +starting with @samp{@@} are printed. This flag is useful for finding +out which recipes @code{make} thinks are necessary without actually +doing them. + +@cindex @code{-s} +@cindex @code{--silent} +@cindex @code{--quiet} +@findex .SILENT +The @samp{-s} or @samp{--silent} +flag to @code{make} prevents all echoing, as if all recipes +started with @samp{@@}. A rule in the makefile for the special target +@code{.SILENT} without prerequisites has the same effect +(@pxref{Special Targets, ,Special Built-in Target Names}). +@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill + +@node Execution, Parallel, Echoing, Recipes +@section Recipe Execution +@cindex recipe, execution +@cindex execution, of recipes +@vindex @code{SHELL} @r{(recipe execution)} + +When it is time to execute recipes to update a target, they are +executed by invoking a new subshell for each line of the recipe, +unless the @code{.ONESHELL} special target is in effect +(@pxref{One Shell, ,Using One Shell}) (In practice, @code{make} may +take shortcuts that do not affect the results.) + +@cindex @code{cd} (shell command) +@cindex shell variables, setting in recipes +@cindex recipes setting shell variables +@strong{Please note:} this implies that setting shell variables and +invoking shell commands such as @code{cd} that set a context local to +each process will not affect the following lines in the recipe.@footnote{On +MS-DOS, the value of current working directory is @strong{global}, so +changing it @emph{will} affect the following recipe lines on those +systems.} If you want to use @code{cd} to affect the next statement, +put both statements in a single recipe line. Then @code{make} will +invoke one shell to run the entire line, and the shell will execute +the statements in sequence. For example: + +@example +foo : bar/lose + cd $(@@D) && gobble $(@@F) > ../$@@ +@end example + +@noindent +Here we use the shell AND operator (@code{&&}) so that if the +@code{cd} command fails, the script will fail without trying to invoke +the @code{gobble} command in the wrong directory, which could cause +problems (in this case it would certainly cause @file{../foo} to be +truncated, at least). + +@menu +* One Shell:: One shell for all lines in a recipe +* Choosing the Shell:: How @code{make} chooses the shell used + to run recipes. +@end menu + +@node One Shell, Choosing the Shell, Execution, Execution +@subsection Using One Shell +@cindex recipe lines, single shell +@cindex @code{.ONESHELL}, use of +@findex .ONESHELL + +Sometimes you would prefer that all the lines in the recipe be passed +to a single invocation of the shell. There are generally two +situations where this is useful: first, it can improve performance in +makefiles where recipes consist of many command lines, by avoiding +extra processes. Second, you might want newlines to be included in +your recipe command (for example perhaps you are using a very +different interpreter as your @code{SHELL}). If the @code{.ONESHELL} +special target appears anywhere in the makefile then @emph{all} +recipe lines for each target will be provided to a single invocation +of the shell. Newlines between recipe lines will be preserved. For +example: + +@example +.ONESHELL: +foo : bar/lose + cd $(@@D) + gobble $(@@F) > ../$@@ +@end example + +@noindent +would now work as expected even though the commands are on different +recipe lines. + +If @code{.ONESHELL} is provided, then only the first line of the +recipe will be checked for the special prefix characters (@samp{@@}, +@samp{-}, and @samp{+}). Subsequent lines will include the special +characters in the recipe line when the @code{SHELL} is invoked. If +you want your recipe to start with one of these special characters +you'll need to arrange for them to not be the first characters on the +first line, perhaps by adding a comment or similar. For example, this +would be a syntax error in Perl because the first @samp{@@} is removed +by make: + +@example +.ONESHELL: +SHELL = /usr/bin/perl +.SHELLFLAGS = -e +show : + @@f = qw(a b c); + print "@@f\n"; +@end example + +@noindent +However, either of these alternatives would work properly: + +@example +.ONESHELL: +SHELL = /usr/bin/perl +.SHELLFLAGS = -e +show : + # Make sure "@@" is not the first character on the first line + @@f = qw(a b c); + print "@@f\n"; +@end example + +@noindent +or + +@example +.ONESHELL: +SHELL = /usr/bin/perl +.SHELLFLAGS = -e +show : + my @@f = qw(a b c); + print "@@f\n"; +@end example + +As a special feature, if @code{SHELL} is determined to be a +POSIX-style shell, the special prefix characters in ``internal'' +recipe lines will @emph{removed} before the recipe is processed. This +feature is intended to allow existing makefiles to add the +@code{.ONESHELL} special target and still run properly without +extensive modifications. Since the special prefix characters are not +legal at the beginning of a line in a POSIX shell script this is not a +loss in functionality. For example, this works as expected: + +@example +.ONESHELL: +foo : bar/lose + @@cd $(@@D) + @@gobble $(@@F) > ../$@@ +@end example + +Even with this special feature, however, makefiles with +@code{.ONESHELL} will behave differently in ways that could be +noticeable. For example, normally if any line in the recipe fails, +that causes the rule to fail and no more recipe lines are processed. +Under @code{.ONESHELL} a failure of any but the final recipe line will +not be noticed by @code{make}. You can modify @code{.SHELLFLAGS} to +add the @code{-e} option to the shell which will cause any failure +anywhere in the command line to cause the shell to fail, but this +could itself cause your recipe to behave differently. Ultimately you +may need to harden your recipe lines to allow them to work with +@code{.ONESHELL}. + +@node Choosing the Shell, , One Shell, Execution +@subsection Choosing the Shell +@cindex shell, choosing the +@cindex @code{SHELL}, value of +@cindex @code{.SHELLFLAGS}, value of + +@vindex SHELL +@vindex .SHELLFLAGS +The program used as the shell is taken from the variable @code{SHELL}. +If this variable is not set in your makefile, the program +@file{/bin/sh} is used as the shell. The argument(s) passed to the +shell are taken from the variable @code{.SHELLFLAGS}. The default +value of @code{.SHELLFLAGS} is @code{-c} normally, or @code{-ec} in +POSIX-conforming mode. + +@cindex environment, @code{SHELL} in +Unlike most variables, the variable @code{SHELL} is never set from the +environment. This is because the @code{SHELL} environment variable is +used to specify your personal choice of shell program for interactive +use. It would be very bad for personal choices like this to affect the +functioning of makefiles. @xref{Environment, ,Variables from the +Environment}. + +Furthermore, when you do set @code{SHELL} in your makefile that value +is @emph{not} exported in the environment to recipe lines that +@code{make} invokes. Instead, the value inherited from the user's +environment, if any, is exported. You can override this behavior by +explicitly exporting @code{SHELL} (@pxref{Variables/Recursion, +,Communicating Variables to a Sub-@code{make}}), forcing it to be +passed in the environment to recipe lines. + +@vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})} +However, on MS-DOS and MS-Windows the value of @code{SHELL} in the +environment @strong{is} used, since on those systems most users do not +set this variable, and therefore it is most likely set specifically to +be used by @code{make}. On MS-DOS, if the setting of @code{SHELL} is +not suitable for @code{make}, you can set the variable +@code{MAKESHELL} to the shell that @code{make} should use; if set it +will be used as the shell instead of the value of @code{SHELL}. + +@subsubheading Choosing a Shell in DOS and Windows +@cindex shell, in DOS and Windows +@cindex DOS, choosing a shell in +@cindex Windows, choosing a shell in + +Choosing a shell in MS-DOS and MS-Windows is much more complex than on +other systems. + +@vindex COMSPEC +On MS-DOS, if @code{SHELL} is not set, the value of the variable +@code{COMSPEC} (which is always set) is used instead. + +@cindex @code{SHELL}, MS-DOS specifics +The processing of lines that set the variable @code{SHELL} in Makefiles +is different on MS-DOS. The stock shell, @file{command.com}, is +ridiculously limited in its functionality and many users of @code{make} +tend to install a replacement shell. Therefore, on MS-DOS, @code{make} +examines the value of @code{SHELL}, and changes its behavior based on +whether it points to a Unix-style or DOS-style shell. This allows +reasonable functionality even if @code{SHELL} points to +@file{command.com}. + +If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS +additionally checks whether that shell can indeed be found; if not, it +ignores the line that sets @code{SHELL}. In MS-DOS, GNU @code{make} +searches for the shell in the following places: + +@enumerate +@item +In the precise place pointed to by the value of @code{SHELL}. For +example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make} +will look in the directory @file{/bin} on the current drive. + +@item +In the current directory. + +@item +In each of the directories in the @code{PATH} variable, in order. + +@end enumerate + +In every directory it examines, @code{make} will first look for the +specific file (@file{sh} in the example above). If this is not found, +it will also look in that directory for that file with one of the known +extensions which identify executable files. For example @file{.exe}, +@file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others. + +If any of these attempts is successful, the value of @code{SHELL} will +be set to the full pathname of the shell as found. However, if none of +these is found, the value of @code{SHELL} will not be changed, and thus +the line that sets it will be effectively ignored. This is so +@code{make} will only support features specific to a Unix-style shell if +such a shell is actually installed on the system where @code{make} runs. + +Note that this extended search for the shell is limited to the cases +where @code{SHELL} is set from the Makefile; if it is set in the +environment or command line, you are expected to set it to the full +pathname of the shell, exactly as things are on Unix. + +The effect of the above DOS-specific processing is that a Makefile that +contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work +on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some +directory along your @code{PATH}. + +@vindex SHELL +@vindex .SHELLFLAGS + +@node Parallel, Errors, Execution, Recipes +@section Parallel Execution +@cindex recipes, execution in parallel +@cindex parallel execution +@cindex execution, in parallel +@cindex job slots +@cindex @code{-j} +@cindex @code{--jobs} + +GNU @code{make} knows how to execute several recipes at once. +Normally, @code{make} will execute only one recipe at a time, waiting +for it to finish before executing the next. However, the @samp{-j} or +@samp{--jobs} option tells @code{make} to execute many recipes +simultaneously. You can inhibit parallelism in a particular makefile +with the @code{.NOTPARALLEL} pseudo-target (@pxref{Special +Targets,Special Built-in Target Names}).@refill + +On MS-DOS, the @samp{-j} option has no effect, since that system doesn't +support multi-processing. + +If the @samp{-j} option is followed by an integer, this is the number of +recipes to execute at once; this is called the number of @dfn{job slots}. +If there is nothing looking like an integer after the @samp{-j} option, +there is no limit on the number of job slots. The default number of job +slots is one, which means serial execution (one thing at a time). + +One unpleasant consequence of running several recipes simultaneously is +that output generated by the recipes appears whenever each recipe +sends it, so messages from different recipes may be interspersed. + +Another problem is that two processes cannot both take input from the +same device; so to make sure that only one recipe tries to take input +from the terminal at once, @code{make} will invalidate the standard +input streams of all but one running recipe. This means that +attempting to read from standard input will usually be a fatal error (a +@samp{Broken pipe} signal) for most child processes if there are +several. +@cindex broken pipe +@cindex standard input + +It is unpredictable which recipe will have a valid standard input stream +(which will come from the terminal, or wherever you redirect the standard +input of @code{make}). The first recipe run will always get it first, and +the first recipe started after that one finishes will get it next, and so +on. + +We will change how this aspect of @code{make} works if we find a better +alternative. In the mean time, you should not rely on any recipe using +standard input at all if you are using the parallel execution feature; but +if you are not using this feature, then standard input works normally in +all recipes. + +Finally, handling recursive @code{make} invocations raises issues. For +more information on this, see +@ref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. + +If a recipe fails (is killed by a signal or exits with a nonzero +status), and errors are not ignored for that recipe +(@pxref{Errors, ,Errors in Recipes}), +the remaining recipe lines to remake the same target will not be run. +If a recipe fails and the @samp{-k} or @samp{--keep-going} +option was not given +(@pxref{Options Summary, ,Summary of Options}), +@code{make} aborts execution. If make +terminates for any reason (including a signal) with child processes +running, it waits for them to finish before actually exiting.@refill + +@cindex load average +@cindex limiting jobs based on load +@cindex jobs, limiting based on load +@cindex @code{-l} (load average) +@cindex @code{--max-load} +@cindex @code{--load-average} +When the system is heavily loaded, you will probably want to run fewer jobs +than when it is lightly loaded. You can use the @samp{-l} option to tell +@code{make} to limit the number of jobs to run at once, based on the load +average. The @samp{-l} or @samp{--max-load} +option is followed by a floating-point number. For +example, + +@example +-l 2.5 +@end example + +@noindent +will not let @code{make} start more than one job if the load average is +above 2.5. The @samp{-l} option with no following number removes the +load limit, if one was given with a previous @samp{-l} option.@refill + +More precisely, when @code{make} goes to start up a job, and it already has +at least one job running, it checks the current load average; if it is not +lower than the limit given with @samp{-l}, @code{make} waits until the load +average goes below that limit, or until all the other jobs finish. + +By default, there is no load limit. + +@node Errors, Interrupts, Parallel, Recipes +@section Errors in Recipes +@cindex errors (in recipes) +@cindex recipes, errors in +@cindex exit status (errors) + +After each shell invocation returns, @code{make} looks at its exit +status. If the shell completed successfully (the exit status is +zero), the next line in the recipe is executed in a new shell; after +the last line is finished, the rule is finished. + +If there is an error (the exit status is nonzero), @code{make} gives up on +the current rule, and perhaps on all rules. + +Sometimes the failure of a certain recipe line does not indicate a problem. +For example, you may use the @code{mkdir} command to ensure that a +directory exists. If the directory already exists, @code{mkdir} will +report an error, but you probably want @code{make} to continue regardless. + +@cindex @code{-} (in recipes) +To ignore errors in a recipe line, write a @samp{-} at the beginning +of the line's text (after the initial tab). The @samp{-} is discarded +before the line is passed to the shell for execution. + +For example, + +@example +@group +clean: + -rm -f *.o +@end group +@end example +@cindex @code{rm} (shell command) + +@noindent +This causes @code{make} to continue even if @code{rm} is unable to +remove a file. + +@cindex @code{-i} +@cindex @code{--ignore-errors} +@findex .IGNORE +When you run @code{make} with the @samp{-i} or @samp{--ignore-errors} +flag, errors are ignored in all recipes of all rules. A rule in the +makefile for the special target @code{.IGNORE} has the same effect, if +there are no prerequisites. These ways of ignoring errors are obsolete +because @samp{-} is more flexible. + +When errors are to be ignored, because of either a @samp{-} or the +@samp{-i} flag, @code{make} treats an error return just like success, +except that it prints out a message that tells you the status code +the shell exited with, and says that the error has been ignored. + +When an error happens that @code{make} has not been told to ignore, +it implies that the current target cannot be correctly remade, and neither +can any other that depends on it either directly or indirectly. No further +recipes will be executed for these targets, since their preconditions +have not been achieved. + + +@cindex @code{-k} +@cindex @code{--keep-going} +Normally @code{make} gives up immediately in this circumstance, returning a +nonzero status. However, if the @samp{-k} or @samp{--keep-going} +flag is specified, @code{make} +continues to consider the other prerequisites of the pending targets, +remaking them if necessary, before it gives up and returns nonzero status. +For example, after an error in compiling one object file, @samp{make -k} +will continue compiling other object files even though it already knows +that linking them will be impossible. @xref{Options Summary, ,Summary of Options}. + +The usual behavior assumes that your purpose is to get the specified +targets up to date; once @code{make} learns that this is impossible, it +might as well report the failure immediately. The @samp{-k} option says +that the real purpose is to test as many of the changes made in the +program as possible, perhaps to find several independent problems so +that you can correct them all before the next attempt to compile. This +is why Emacs' @code{compile} command passes the @samp{-k} flag by +default. +@cindex Emacs (@code{M-x compile}) + +@findex .DELETE_ON_ERROR +@cindex deletion of target files +@cindex removal of target files +@cindex target, deleting on error +Usually when a recipe line fails, if it has changed the target file at all, +the file is corrupted and cannot be used---or at least it is not +completely updated. Yet the file's time stamp says that it is now up to +date, so the next time @code{make} runs, it will not try to update that +file. The situation is just the same as when the shell is killed by a +signal; @pxref{Interrupts}. So generally the right thing to do is to +delete the target file if the recipe fails after beginning to change +the file. @code{make} will do this if @code{.DELETE_ON_ERROR} appears +as a target. This is almost always what you want @code{make} to do, but +it is not historical practice; so for compatibility, you must explicitly +request it. + +@node Interrupts, Recursion, Errors, Recipes +@section Interrupting or Killing @code{make} +@cindex interrupt +@cindex signal +@cindex deletion of target files +@cindex removal of target files +@cindex target, deleting on interrupt +@cindex killing (interruption) + +If @code{make} gets a fatal signal while a shell is executing, it may +delete the target file that the recipe was supposed to update. This is +done if the target file's last-modification time has changed since +@code{make} first checked it. + +The purpose of deleting the target is to make sure that it is remade from +scratch when @code{make} is next run. Why is this? Suppose you type +@kbd{Ctrl-c} while a compiler is running, and it has begun to write an +object file @file{foo.o}. The @kbd{Ctrl-c} kills the compiler, resulting +in an incomplete file whose last-modification time is newer than the source +file @file{foo.c}. But @code{make} also receives the @kbd{Ctrl-c} signal +and deletes this incomplete file. If @code{make} did not do this, the next +invocation of @code{make} would think that @file{foo.o} did not require +updating---resulting in a strange error message from the linker when it +tries to link an object file half of which is missing. + +@findex .PRECIOUS +You can prevent the deletion of a target file in this way by making the +special target @code{.PRECIOUS} depend on it. Before remaking a target, +@code{make} checks to see whether it appears on the prerequisites of +@code{.PRECIOUS}, and thereby decides whether the target should be deleted +if a signal happens. Some reasons why you might do this are that the +target is updated in some atomic fashion, or exists only to record a +modification-time (its contents do not matter), or must exist at all +times to prevent other sorts of trouble. + +@node Recursion, Canned Recipes, Interrupts, Recipes +@section Recursive Use of @code{make} +@cindex recursion +@cindex subdirectories, recursion for + +Recursive use of @code{make} means using @code{make} as a command in a +makefile. This technique is useful when you want separate makefiles for +various subsystems that compose a larger system. For example, suppose you +have a subdirectory @file{subdir} which has its own makefile, and you would +like the containing directory's makefile to run @code{make} on the +subdirectory. You can do it by writing this: + +@example +subsystem: + cd subdir && $(MAKE) +@end example + +@noindent +or, equivalently, this (@pxref{Options Summary, ,Summary of Options}): + +@example +subsystem: + $(MAKE) -C subdir +@end example +@cindex @code{-C} +@cindex @code{--directory} + +You can write recursive @code{make} commands just by copying this example, +but there are many things to know about how they work and why, and about +how the sub-@code{make} relates to the top-level @code{make}. You may +also find it useful to declare targets that invoke recursive +@code{make} commands as @samp{.PHONY} (for more discussion on when +this is useful, see @ref{Phony Targets}). + +@vindex @code{CURDIR} +For your convenience, when GNU @code{make} starts (after it has +processed any @code{-C} options) it sets the variable @code{CURDIR} to +the pathname of the current working directory. This value is never +touched by @code{make} again: in particular note that if you include +files from other directories the value of @code{CURDIR} does not +change. The value has the same precedence it would have if it were +set in the makefile (by default, an environment variable @code{CURDIR} +will not override this value). Note that setting this variable has no +impact on the operation of @code{make} (it does not cause @code{make} +to change its working directory, for example). + +@menu +* MAKE Variable:: The special effects of using @samp{$(MAKE)}. +* Variables/Recursion:: How to communicate variables to a sub-@code{make}. +* Options/Recursion:: How to communicate options to a sub-@code{make}. +* -w Option:: How the @samp{-w} or @samp{--print-directory} option + helps debug use of recursive @code{make} commands. +@end menu + +@node MAKE Variable, Variables/Recursion, Recursion, Recursion +@subsection How the @code{MAKE} Variable Works +@vindex MAKE +@cindex recursion, and @code{MAKE} variable + +Recursive @code{make} commands should always use the variable @code{MAKE}, +not the explicit command name @samp{make}, as shown here: + +@example +@group +subsystem: + cd subdir && $(MAKE) +@end group +@end example + +The value of this variable is the file name with which @code{make} was +invoked. If this file name was @file{/bin/make}, then the recipe executed +is @samp{cd subdir && /bin/make}. If you use a special version of +@code{make} to run the top-level makefile, the same special version will be +executed for recursive invocations. +@cindex @code{cd} (shell command) + +@cindex +, and recipes +As a special feature, using the variable @code{MAKE} in the recipe of +a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n} +(@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option. +Using the @code{MAKE} variable has the same effect as using a @samp{+} +character at the beginning of the recipe line. @xref{Instead of +Execution, ,Instead of Executing the Recipes}. This special feature +is only enabled if the @code{MAKE} variable appears directly in the +recipe: it does not apply if the @code{MAKE} variable is referenced +through expansion of another variable. In the latter case you must +use the @samp{+} token to get these special effects.@refill + +Consider the command @samp{make -t} in the above example. (The +@samp{-t} option marks targets as up to date without actually running +any recipes; see @ref{Instead of Execution}.) Following the usual +definition of @samp{-t}, a @samp{make -t} command in the example would +create a file named @file{subsystem} and do nothing else. What you +really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but +that would require executing the recipe, and @samp{-t} says not to +execute recipes.@refill +@cindex @code{-t}, and recursion +@cindex recursion, and @code{-t} +@cindex @code{--touch}, and recursion + +The special feature makes this do what you want: whenever a recipe +line of a rule contains the variable @code{MAKE}, the flags @samp{-t}, +@samp{-n} and @samp{-q} do not apply to that line. Recipe lines +containing @code{MAKE} are executed normally despite the presence of a +flag that causes most recipes not to be run. The usual +@code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make} +(@pxref{Options/Recursion, ,Communicating Options to a +Sub-@code{make}}), so your request to touch the files, or print the +recipes, is propagated to the subsystem.@refill + +@node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion +@subsection Communicating Variables to a Sub-@code{make} +@cindex sub-@code{make} +@cindex environment, and recursion +@cindex exporting variables +@cindex variables, environment +@cindex variables, exporting +@cindex recursion, and environment +@cindex recursion, and variables + +Variable values of the top-level @code{make} can be passed to the +sub-@code{make} through the environment by explicit request. These +variables are defined in the sub-@code{make} as defaults, but do not +override what is specified in the makefile used by the sub-@code{make} +makefile unless you use the @samp{-e} switch (@pxref{Options Summary, +,Summary of Options}).@refill + +To pass down, or @dfn{export}, a variable, @code{make} adds the +variable and its value to the environment for running each line of the +recipe. The sub-@code{make}, in turn, uses the environment to +initialize its table of variable values. @xref{Environment, +,Variables from the Environment}. + +Except by explicit request, @code{make} exports a variable only if it +is either defined in the environment initially or set on the command +line, and if its name consists only of letters, numbers, and underscores. +Some shells cannot cope with environment variable names consisting of +characters other than letters, numbers, and underscores. + +@cindex SHELL, exported value +The value of the @code{make} variable @code{SHELL} is not exported. +Instead, the value of the @code{SHELL} variable from the invoking +environment is passed to the sub-@code{make}. You can force +@code{make} to export its value for @code{SHELL} by using the +@code{export} directive, described below. @xref{Choosing the Shell}. + +The special variable @code{MAKEFLAGS} is always exported (unless you +unexport it). @code{MAKEFILES} is exported if you set it to anything. + +@code{make} automatically passes down variable values that were defined +on the command line, by putting them in the @code{MAKEFLAGS} variable. +@iftex +See the next section. +@end iftex +@ifnottex +@xref{Options/Recursion}. +@end ifnottex + +Variables are @emph{not} normally passed down if they were created by +default by @code{make} (@pxref{Implicit Variables, ,Variables Used by +Implicit Rules}). The sub-@code{make} will define these for +itself.@refill + +@findex export +If you want to export specific variables to a sub-@code{make}, use the +@code{export} directive, like this: + +@example +export @var{variable} @dots{} +@end example + +@noindent +@findex unexport +If you want to @emph{prevent} a variable from being exported, use the +@code{unexport} directive, like this: + +@example +unexport @var{variable} @dots{} +@end example + +@noindent +In both of these forms, the arguments to @code{export} and +@code{unexport} are expanded, and so could be variables or functions +which expand to a (list of) variable names to be (un)exported. + +As a convenience, you can define a variable and export it at the same +time by doing: + +@example +export @var{variable} = value +@end example + +@noindent +has the same result as: + +@example +@var{variable} = value +export @var{variable} +@end example + +@noindent +and + +@example +export @var{variable} := value +@end example + +@noindent +has the same result as: + +@example +@var{variable} := value +export @var{variable} +@end example + +Likewise, + +@example +export @var{variable} += value +@end example + +@noindent +is just like: + +@example +@var{variable} += value +export @var{variable} +@end example + +@noindent +@xref{Appending, ,Appending More Text to Variables}. + +You may notice that the @code{export} and @code{unexport} directives +work in @code{make} in the same way they work in the shell, @code{sh}. + +If you want all variables to be exported by default, you can use +@code{export} by itself: + +@example +export +@end example + +@noindent +This tells @code{make} that variables which are not explicitly mentioned +in an @code{export} or @code{unexport} directive should be exported. +Any variable given in an @code{unexport} directive will still @emph{not} +be exported. If you use @code{export} by itself to export variables by +default, variables whose names contain characters other than +alphanumerics and underscores will not be exported unless specifically +mentioned in an @code{export} directive.@refill + +@findex .EXPORT_ALL_VARIABLES +The behavior elicited by an @code{export} directive by itself was the +default in older versions of GNU @code{make}. If your makefiles depend +on this behavior and you want to be compatible with old versions of +@code{make}, you can write a rule for the special target +@code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive. +This will be ignored by old @code{make}s, while the @code{export} +directive will cause a syntax error.@refill +@cindex compatibility in exporting + +Likewise, you can use @code{unexport} by itself to tell @code{make} +@emph{not} to export variables by default. Since this is the default +behavior, you would only need to do this if @code{export} had been used +by itself earlier (in an included makefile, perhaps). You +@strong{cannot} use @code{export} and @code{unexport} by themselves to +have variables exported for some recipes and not for others. The last +@code{export} or @code{unexport} directive that appears by itself +determines the behavior for the entire run of @code{make}.@refill + +@vindex MAKELEVEL +@cindex recursion, level of +As a special feature, the variable @code{MAKELEVEL} is changed when it +is passed down from level to level. This variable's value is a string +which is the depth of the level as a decimal number. The value is +@samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make}, +@samp{2} for a sub-sub-@code{make}, and so on. The incrementation +happens when @code{make} sets up the environment for a recipe.@refill + +The main use of @code{MAKELEVEL} is to test it in a conditional +directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this +way you can write a makefile that behaves one way if run recursively and +another way if run directly by you.@refill + +@vindex MAKEFILES +You can use the variable @code{MAKEFILES} to cause all sub-@code{make} +commands to use additional makefiles. The value of @code{MAKEFILES} is +a whitespace-separated list of file names. This variable, if defined in +the outer-level makefile, is passed down through the environment; then +it serves as a list of extra makefiles for the sub-@code{make} to read +before the usual or specified ones. @xref{MAKEFILES Variable, ,The +Variable @code{MAKEFILES}}.@refill + +@node Options/Recursion, -w Option, Variables/Recursion, Recursion +@subsection Communicating Options to a Sub-@code{make} +@cindex options, and recursion +@cindex recursion, and options + +@vindex MAKEFLAGS +Flags such as @samp{-s} and @samp{-k} are passed automatically to the +sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is +set up automatically by @code{make} to contain the flag letters that +@code{make} received. Thus, if you do @w{@samp{make -ks}} then +@code{MAKEFLAGS} gets the value @samp{ks}.@refill + +As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS} +in its environment. In response, it takes the flags from that value and +processes them as if they had been given as arguments. +@xref{Options Summary, ,Summary of Options}. + +@cindex command line variable definitions, and recursion +@cindex variables, command line, and recursion +@cindex recursion, and command line variable definitions +Likewise variables defined on the command line are passed to the +sub-@code{make} through @code{MAKEFLAGS}. Words in the value of +@code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable +definitions just as if they appeared on the command line. +@xref{Overriding, ,Overriding Variables}. + +@cindex @code{-C}, and recursion +@cindex @code{-f}, and recursion +@cindex @code{-o}, and recursion +@cindex @code{-W}, and recursion +@cindex @code{--directory}, and recursion +@cindex @code{--file}, and recursion +@cindex @code{--old-file}, and recursion +@cindex @code{--assume-old}, and recursion +@cindex @code{--assume-new}, and recursion +@cindex @code{--new-file}, and recursion +@cindex recursion, and @code{-C} +@cindex recursion, and @code{-f} +@cindex recursion, and @code{-o} +@cindex recursion, and @code{-W} +The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put +into @code{MAKEFLAGS}; these options are not passed down.@refill + +@cindex @code{-j}, and recursion +@cindex @code{--jobs}, and recursion +@cindex recursion, and @code{-j} +@cindex job slots, and recursion +The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}). +If you set it to some numeric value @samp{N} and your operating system +supports it (most any UNIX system will; others typically won't), the +parent @code{make} and all the sub-@code{make}s will communicate to +ensure that there are only @samp{N} jobs running at the same time +between them all. Note that any job that is marked recursive +(@pxref{Instead of Execution, ,Instead of Executing Recipes}) +doesn't count against the total jobs (otherwise we could get @samp{N} +sub-@code{make}s running and have no slots left over for any real work!) + +If your operating system doesn't support the above communication, then +@samp{-j 1} is always put into @code{MAKEFLAGS} instead of the value you +specified. This is because if the @w{@samp{-j}} option were passed down +to sub-@code{make}s, you would get many more jobs running in parallel +than you asked for. If you give @samp{-j} with no numeric argument, +meaning to run as many jobs as possible in parallel, this is passed +down, since multiple infinities are no more than one.@refill + +If you do not want to pass the other flags down, you must change the +value of @code{MAKEFLAGS}, like this: + +@example +subsystem: + cd subdir && $(MAKE) MAKEFLAGS= +@end example + +@vindex MAKEOVERRIDES +The command line variable definitions really appear in the variable +@code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this +variable. If you do want to pass flags down normally, but don't want to +pass down the command line variable definitions, you can reset +@code{MAKEOVERRIDES} to empty, like this: + +@example +MAKEOVERRIDES = +@end example + +@noindent +@cindex Arg list too long +@cindex E2BIG +This is not usually useful to do. However, some systems have a small +fixed limit on the size of the environment, and putting so much +information into the value of @code{MAKEFLAGS} can exceed it. If you +see the error message @samp{Arg list too long}, this may be the problem. +@findex .POSIX +@cindex POSIX.2 +(For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does +not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears +in the makefile. You probably do not care about this.) + +@vindex MFLAGS +A similar variable @code{MFLAGS} exists also, for historical +compatibility. It has the same value as @code{MAKEFLAGS} except that it +does not contain the command line variable definitions, and it always +begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a +hyphen only when it begins with an option that has no single-letter +version, such as @samp{--warn-undefined-variables}). @code{MFLAGS} was +traditionally used explicitly in the recursive @code{make} command, like +this: + +@example +subsystem: + cd subdir && $(MAKE) $(MFLAGS) +@end example + +@noindent +but now @code{MAKEFLAGS} makes this usage redundant. If you want your +makefiles to be compatible with old @code{make} programs, use this +technique; it will work fine with more modern @code{make} versions too. + +@cindex setting options from environment +@cindex options, setting from environment +@cindex setting options in makefiles +@cindex options, setting in makefiles +The @code{MAKEFLAGS} variable can also be useful if you want to have +certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of +Options}), set each time you run @code{make}. You simply put a value for +@code{MAKEFLAGS} in your environment. You can also set @code{MAKEFLAGS} in +a makefile, to specify additional flags that should also be in effect for +that makefile. (Note that you cannot use @code{MFLAGS} this way. That +variable is set only for compatibility; @code{make} does not interpret a +value you set for it in any way.) + +When @code{make} interprets the value of @code{MAKEFLAGS} (either from the +environment or from a makefile), it first prepends a hyphen if the value +does not already begin with one. Then it chops the value into words +separated by blanks, and parses these words as if they were options given +on the command line (except that @samp{-C}, @samp{-f}, @samp{-h}, +@samp{-o}, @samp{-W}, and their long-named versions are ignored; and there +is no error for an invalid option). + +If you do put @code{MAKEFLAGS} in your environment, you should be sure not +to include any options that will drastically affect the actions of +@code{make} and undermine the purpose of makefiles and of @code{make} +itself. For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if +put in one of these variables, could have disastrous consequences and would +certainly have at least surprising and probably annoying effects.@refill + +@node -w Option, , Options/Recursion, Recursion +@subsection The @samp{--print-directory} Option +@cindex directories, printing them +@cindex printing directories +@cindex recursion, and printing directories + +If you use several levels of recursive @code{make} invocations, the +@samp{-w} or @w{@samp{--print-directory}} option can make the output a +lot easier to understand by showing each directory as @code{make} +starts processing it and as @code{make} finishes processing it. For +example, if @samp{make -w} is run in the directory @file{/u/gnu/make}, +@code{make} will print a line of the form:@refill + +@example +make: Entering directory `/u/gnu/make'. +@end example + +@noindent +before doing anything else, and a line of the form: + +@example +make: Leaving directory `/u/gnu/make'. +@end example + +@noindent +when processing is completed. + +@cindex @code{-C}, and @code{-w} +@cindex @code{--directory}, and @code{--print-directory} +@cindex recursion, and @code{-w} +@cindex @code{-w}, and @code{-C} +@cindex @code{-w}, and recursion +@cindex @code{--print-directory}, and @code{--directory} +@cindex @code{--print-directory}, and recursion +@cindex @code{--no-print-directory} +@cindex @code{--print-directory}, disabling +@cindex @code{-w}, disabling +Normally, you do not need to specify this option because @samp{make} +does it for you: @samp{-w} is turned on automatically when you use the +@samp{-C} option, and in sub-@code{make}s. @code{make} will not +automatically turn on @samp{-w} if you also use @samp{-s}, which says to +be silent, or if you use @samp{--no-print-directory} to explicitly +disable it. + +@node Canned Recipes, Empty Recipes, Recursion, Recipes +@section Defining Canned Recipes +@cindex canned recipes +@cindex recipes, canned +@cindex sequences of commands +@cindex commands, sequences of + +When the same sequence of commands is useful in making various +targets, you can define it as a canned sequence with the @code{define} +directive, and refer to the canned sequence from the recipes for those +targets. The canned sequence is actually a variable, so the name must +not conflict with other variable names. + +Here is an example of defining a canned recipe: + +@example +define run-yacc = +yacc $(firstword $^) +mv y.tab.c $@@ +endef +@end example +@cindex @code{yacc} + +@noindent +Here @code{run-yacc} is the name of the variable being defined; +@code{endef} marks the end of the definition; the lines in between are the +commands. The @code{define} directive does not expand variable references +and function calls in the canned sequence; the @samp{$} characters, +parentheses, variable names, and so on, all become part of the value of the +variable you are defining. +@xref{Multi-Line, ,Defining Multi-Line Variables}, +for a complete explanation of @code{define}. + +The first command in this example runs Yacc on the first prerequisite of +whichever rule uses the canned sequence. The output file from Yacc is +always named @file{y.tab.c}. The second command moves the output to the +rule's target file name. + +To use the canned sequence, substitute the variable into the recipe of a +rule. You can substitute it like any other variable +(@pxref{Reference, ,Basics of Variable References}). +Because variables defined by @code{define} are recursively expanded +variables, all the variable references you wrote inside the @code{define} +are expanded now. For example: + +@example +foo.c : foo.y + $(run-yacc) +@end example + +@noindent +@samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in +@code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill + +This is a realistic example, but this particular one is not needed in +practice because @code{make} has an implicit rule to figure out these +commands based on the file names involved +(@pxref{Implicit Rules, ,Using Implicit Rules}). + +@cindex @@, and @code{define} +@cindex -, and @code{define} +@cindex +, and @code{define} +In recipe execution, each line of a canned sequence is treated just as +if the line appeared on its own in the rule, preceded by a tab. In +particular, @code{make} invokes a separate subshell for each line. You +can use the special prefix characters that affect command lines +(@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence. +@xref{Recipes, ,Writing Recipes in Rules}. +For example, using this canned sequence: + +@example +define frobnicate = +@@echo "frobnicating target $@@" +frob-step-1 $< -o $@@-step-1 +frob-step-2 $@@-step-1 -o $@@ +endef +@end example + +@noindent +@code{make} will not echo the first line, the @code{echo} command. +But it @emph{will} echo the following two recipe lines. + +On the other hand, prefix characters on the recipe line that refers to +a canned sequence apply to every line in the sequence. So the rule: + +@example +frob.out: frob.in + @@$(frobnicate) +@end example + +@noindent +does not echo @emph{any} recipe lines. +(@xref{Echoing, ,Recipe Echoing}, for a full explanation of @samp{@@}.) + +@node Empty Recipes, , Canned Recipes, Recipes +@section Using Empty Recipes +@cindex empty recipes +@cindex recipes, empty + +It is sometimes useful to define recipes which do nothing. This is done +simply by giving a recipe that consists of nothing but whitespace. For +example: + +@example +target: ; +@end example + +@noindent +defines an empty recipe for @file{target}. You could also use a line +beginning with a recipe prefix character to define an empty recipe, +but this would be confusing because such a line looks empty. + +@findex .DEFAULT@r{, and empty recipes} +You may be wondering why you would want to define a recipe that +does nothing. The only reason this is useful is to prevent a target +from getting implicit recipes (from implicit rules or the +@code{.DEFAULT} special target; @pxref{Implicit Rules} and +@pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill + +@c !!! another reason is for canonical stamp files: +@ignore +@example +foo: stamp-foo ; +stamp-foo: foo.in + create foo frm foo.in + touch $@ +@end example +@end ignore + +You may be inclined to define empty recipes for targets that are +not actual files, but only exist so that their prerequisites can be +remade. However, this is not the best way to do that, because the +prerequisites may not be remade properly if the target file actually does exist. +@xref{Phony Targets, ,Phony Targets}, for a better way to do this. + +@node Using Variables, Conditionals, Recipes, Top +@chapter How to Use Variables +@cindex variable +@cindex value +@cindex recursive variable expansion +@cindex simple variable expansion + +A @dfn{variable} is a name defined in a makefile to represent a string +of text, called the variable's @dfn{value}. These values are +substituted by explicit request into targets, prerequisites, recipes, +and other parts of the makefile. (In some other versions of @code{make}, +variables are called @dfn{macros}.) +@cindex macro + +Variables and functions in all parts of a makefile are expanded when +read, except for in recipes, the right-hand sides of variable +definitions using @samp{=}, and the bodies of variable definitions +using the @code{define} directive.@refill + +Variables can represent lists of file names, options to pass to compilers, +programs to run, directories to look in for source files, directories to +write output in, or anything else you can imagine. + +A variable name may be any sequence of characters not containing @samp{:}, +@samp{#}, @samp{=}, or leading or trailing whitespace. However, +variable names containing characters other than letters, numbers, and +underscores should be avoided, as they may be given special meanings in the +future, and with some shells they cannot be passed through the environment to a +sub-@code{make} +(@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}). + +Variable names are case-sensitive. The names @samp{foo}, @samp{FOO}, +and @samp{Foo} all refer to different variables. + +It is traditional to use upper case letters in variable names, but we +recommend using lower case letters for variable names that serve internal +purposes in the makefile, and reserving upper case for parameters that +control implicit rules or for parameters that the user should override with +command options (@pxref{Overriding, ,Overriding Variables}). + +A few variables have names that are a single punctuation character or +just a few characters. These are the @dfn{automatic variables}, and +they have particular specialized uses. @xref{Automatic Variables}. + +@menu +* Reference:: How to use the value of a variable. +* Flavors:: Variables come in two flavors. +* Advanced:: Advanced features for referencing a variable. +* Values:: All the ways variables get their values. +* Setting:: How to set a variable in the makefile. +* Appending:: How to append more text to the old value + of a variable. +* Override Directive:: How to set a variable in the makefile even if + the user has set it with a command argument. +* Multi-Line:: An alternate way to set a variable + to a multi-line string. +* Undefine Directive:: How to undefine a variable so that it appears + as if it was never set. +* Environment:: Variable values can come from the environment. +* Target-specific:: Variable values can be defined on a per-target + basis. +* Pattern-specific:: Target-specific variable values can be applied + to a group of targets that match a pattern. +* Suppressing Inheritance:: Suppress inheritance of variables. +* Special Variables:: Variables with special meaning or behavior. +@end menu + +@node Reference, Flavors, Using Variables, Using Variables +@section Basics of Variable References +@cindex variables, how to reference +@cindex reference to variables +@cindex @code{$}, in variable reference +@cindex dollar sign (@code{$}), in variable reference + +To substitute a variable's value, write a dollar sign followed by the name +of the variable in parentheses or braces: either @samp{$(foo)} or +@samp{$@{foo@}} is a valid reference to the variable @code{foo}. This +special significance of @samp{$} is why you must write @samp{$$} to have +the effect of a single dollar sign in a file name or recipe. + +Variable references can be used in any context: targets, prerequisites, +recipes, most directives, and new variable values. Here is an +example of a common case, where a variable holds the names of all the +object files in a program: + +@example +@group +objects = program.o foo.o utils.o +program : $(objects) + cc -o program $(objects) + +$(objects) : defs.h +@end group +@end example + +Variable references work by strict textual substitution. Thus, the rule + +@example +@group +foo = c +prog.o : prog.$(foo) + $(foo)$(foo) -$(foo) prog.$(foo) +@end group +@end example + +@noindent +could be used to compile a C program @file{prog.c}. Since spaces before +the variable value are ignored in variable assignments, the value of +@code{foo} is precisely @samp{c}. (Don't actually write your makefiles +this way!) + +A dollar sign followed by a character other than a dollar sign, +open-parenthesis or open-brace treats that single character as the +variable name. Thus, you could reference the variable @code{x} with +@samp{$x}. However, this practice is strongly discouraged, except in +the case of the automatic variables (@pxref{Automatic Variables}). + +@node Flavors, Advanced, Reference, Using Variables +@section The Two Flavors of Variables +@cindex flavors of variables +@cindex recursive variable expansion +@cindex variables, flavors +@cindex recursively expanded variables +@cindex variables, recursively expanded + +There are two ways that a variable in GNU @code{make} can have a value; +we call them the two @dfn{flavors} of variables. The two flavors are +distinguished in how they are defined and in what they do when expanded. + +@cindex = +The first flavor of variable is a @dfn{recursively expanded} variable. +Variables of this sort are defined by lines using @samp{=} +(@pxref{Setting, ,Setting Variables}) or by the @code{define} directive +(@pxref{Multi-Line, ,Defining Multi-Line Variables}). The value you specify +is installed verbatim; if it contains references to other variables, +these references are expanded whenever this variable is substituted (in +the course of expanding some other string). When this happens, it is +called @dfn{recursive expansion}.@refill + +For example, + +@example +foo = $(bar) +bar = $(ugh) +ugh = Huh? + +all:;echo $(foo) +@end example + +@noindent +will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which +expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill + +This flavor of variable is the only sort supported by other versions of +@code{make}. It has its advantages and its disadvantages. An advantage +(most would say) is that: + +@example +CFLAGS = $(include_dirs) -O +include_dirs = -Ifoo -Ibar +@end example + +@noindent +will do what was intended: when @samp{CFLAGS} is expanded in a recipe, +it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you +cannot append something on the end of a variable, as in + +@example +CFLAGS = $(CFLAGS) -O +@end example + +@noindent +because it will cause an infinite loop in the variable expansion. +(Actually @code{make} detects the infinite loop and reports an error.) +@cindex loops in variable expansion +@cindex variables, loops in expansion + +Another disadvantage is that any functions +(@pxref{Functions, ,Functions for Transforming Text}) +referenced in the definition will be executed every time the variable is +expanded. This makes @code{make} run slower; worse, it causes the +@code{wildcard} and @code{shell} functions to give unpredictable results +because you cannot easily control when they are called, or even how many +times. + +To avoid all the problems and inconveniences of recursively expanded +variables, there is another flavor: simply expanded variables. + +@cindex simply expanded variables +@cindex variables, simply expanded +@cindex := +@dfn{Simply expanded variables} are defined by lines using @samp{:=} +(@pxref{Setting, ,Setting Variables}). +The value of a simply expanded variable is scanned +once and for all, expanding any references to other variables and +functions, when the variable is defined. The actual value of the simply +expanded variable is the result of expanding the text that you write. +It does not contain any references to other variables; it contains their +values @emph{as of the time this variable was defined}. Therefore, + +@example +x := foo +y := $(x) bar +x := later +@end example + +@noindent +is equivalent to + +@example +y := foo bar +x := later +@end example + +When a simply expanded variable is referenced, its value is substituted +verbatim. + +Here is a somewhat more complicated example, illustrating the use of +@samp{:=} in conjunction with the @code{shell} function. +(@xref{Shell Function, , The @code{shell} Function}.) This example +also shows use of the variable @code{MAKELEVEL}, which is changed +when it is passed down from level to level. +(@xref{Variables/Recursion, , Communicating Variables to a +Sub-@code{make}}, for information about @code{MAKELEVEL}.) + +@vindex MAKELEVEL +@vindex MAKE +@example +@group +ifeq (0,$@{MAKELEVEL@}) +whoami := $(shell whoami) +host-type := $(shell arch) +MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@} +endif +@end group +@end example + +@noindent +An advantage of this use of @samp{:=} is that a typical +`descend into a directory' recipe then looks like this: + +@example +@group +$@{subdirs@}: + $@{MAKE@} -C $@@ all +@end group +@end example + +Simply expanded variables generally make complicated makefile programming +more predictable because they work like variables in most programming +languages. They allow you to redefine a variable using its own value (or +its value processed in some way by one of the expansion functions) and to +use the expansion functions much more efficiently +(@pxref{Functions, ,Functions for Transforming Text}). + +@cindex spaces, in variable values +@cindex whitespace, in variable values +@cindex variables, spaces in values +You can also use them to introduce controlled leading whitespace into +variable values. Leading whitespace characters are discarded from your +input before substitution of variable references and function calls; +this means you can include leading spaces in a variable value by +protecting them with variable references, like this: + +@example +nullstring := +space := $(nullstring) # end of the line +@end example + +@noindent +Here the value of the variable @code{space} is precisely one space. The +comment @w{@samp{# end of the line}} is included here just for clarity. +Since trailing space characters are @emph{not} stripped from variable +values, just a space at the end of the line would have the same effect +(but be rather hard to read). If you put whitespace at the end of a +variable value, it is a good idea to put a comment like that at the end +of the line to make your intent clear. Conversely, if you do @emph{not} +want any whitespace characters at the end of your variable value, you +must remember not to put a random comment on the end of the line after +some whitespace, such as this: + +@example +dir := /foo/bar # directory to put the frobs in +@end example + +@noindent +Here the value of the variable @code{dir} is @w{@samp{/foo/bar }} +(with four trailing spaces), which was probably not the intention. +(Imagine something like @w{@samp{$(dir)/file}} with this definition!) + +@cindex conditional variable assignment +@cindex variables, conditional assignment +@cindex ?= +There is another assignment operator for variables, @samp{?=}. This +is called a conditional variable assignment operator, because it only +has an effect if the variable is not yet defined. This statement: + +@example +FOO ?= bar +@end example + +@noindent +is exactly equivalent to this +(@pxref{Origin Function, ,The @code{origin} Function}): + +@example +ifeq ($(origin FOO), undefined) + FOO = bar +endif +@end example + +Note that a variable set to an empty value is still defined, so +@samp{?=} will not set that variable. + +@node Advanced, Values, Flavors, Using Variables +@section Advanced Features for Reference to Variables +@cindex reference to variables + +This section describes some advanced features you can use to reference +variables in more flexible ways. + +@menu +* Substitution Refs:: Referencing a variable with + substitutions on the value. +* Computed Names:: Computing the name of the variable to refer to. +@end menu + +@node Substitution Refs, Computed Names, Advanced, Advanced +@subsection Substitution References +@cindex modified variable reference +@cindex substitution variable reference +@cindex variables, modified reference +@cindex variables, substitution reference + +@cindex variables, substituting suffix in +@cindex suffix, substituting in variables +A @dfn{substitution reference} substitutes the value of a variable with +alterations that you specify. It has the form +@samp{$(@var{var}:@var{a}=@var{b})} (or +@samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value +of the variable @var{var}, replace every @var{a} at the end of a word with +@var{b} in that value, and substitute the resulting string. + +When we say ``at the end of a word'', we mean that @var{a} must appear +either followed by whitespace or at the end of the value in order to be +replaced; other occurrences of @var{a} in the value are unaltered. For +example:@refill + +@example +foo := a.o b.o c.o +bar := $(foo:.o=.c) +@end example + +@noindent +sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}. + +A substitution reference is actually an abbreviation for use of the +@code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide +substitution references as well as @code{patsubst} for compatibility with +other implementations of @code{make}. + +@findex patsubst +Another type of substitution reference lets you use the full power of +the @code{patsubst} function. It has the same form +@samp{$(@var{var}:@var{a}=@var{b})} described above, except that now +@var{a} must contain a single @samp{%} character. This case is +equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}. +@xref{Text Functions, ,Functions for String Substitution and Analysis}, +for a description of the @code{patsubst} function.@refill + +@example +@group +@exdent For example: + +foo := a.o b.o c.o +bar := $(foo:%.o=%.c) +@end group +@end example + +@noindent +sets @samp{bar} to @samp{a.c b.c c.c}. + +@node Computed Names, , Substitution Refs, Advanced +@subsection Computed Variable Names +@cindex nested variable reference +@cindex computed variable name +@cindex variables, computed names +@cindex variables, nested references +@cindex variables, @samp{$} in name +@cindex @code{$}, in variable name +@cindex dollar sign (@code{$}), in variable name + +Computed variable names are a complicated concept needed only for +sophisticated makefile programming. For most purposes you need not +consider them, except to know that making a variable with a dollar sign +in its name might have strange results. However, if you are the type +that wants to understand everything, or you are actually interested in +what they do, read on. + +Variables may be referenced inside the name of a variable. This is +called a @dfn{computed variable name} or a @dfn{nested variable +reference}. For example, + +@example +x = y +y = z +a := $($(x)) +@end example + +@noindent +defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands +to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands +to @samp{z}. Here the name of the variable to reference is not stated +explicitly; it is computed by expansion of @samp{$(x)}. The reference +@samp{$(x)} here is nested within the outer variable reference. + +The previous example shows two levels of nesting, but any number of levels +is possible. For example, here are three levels: + +@example +x = y +y = z +z = u +a := $($($(x))) +@end example + +@noindent +Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))} +expands to @samp{$(y)} which in turn expands to @samp{z}; now we have +@samp{$(z)}, which becomes @samp{u}. + +References to recursively-expanded variables within a variable name are +reexpanded in the usual fashion. For example: + +@example +x = $(y) +y = z +z = Hello +a := $($(x)) +@end example + +@noindent +defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))} +which becomes @samp{$(z)} which becomes @samp{Hello}. + +Nested variable references can also contain modified references and +function invocations (@pxref{Functions, ,Functions for Transforming Text}), +just like any other reference. +For example, using the @code{subst} function +(@pxref{Text Functions, ,Functions for String Substitution and Analysis}): + +@example +@group +x = variable1 +variable2 := Hello +y = $(subst 1,2,$(x)) +z = y +a := $($($(z))) +@end group +@end example + +@noindent +eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone +would ever want to write a nested reference as convoluted as this one, but +it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes +@samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from +@code{x} and changes it by substitution to @samp{variable2}, so that the +entire string becomes @samp{$(variable2)}, a simple variable reference +whose value is @samp{Hello}.@refill + +A computed variable name need not consist entirely of a single variable +reference. It can contain several variable references, as well as some +invariant text. For example, + +@example +@group +a_dirs := dira dirb +1_dirs := dir1 dir2 +@end group + +@group +a_files := filea fileb +1_files := file1 file2 +@end group + +@group +ifeq "$(use_a)" "yes" +a1 := a +else +a1 := 1 +endif +@end group + +@group +ifeq "$(use_dirs)" "yes" +df := dirs +else +df := files +endif + +dirs := $($(a1)_$(df)) +@end group +@end example + +@noindent +will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs}, +@code{a_files} or @code{1_files} depending on the settings of @code{use_a} +and @code{use_dirs}.@refill + +Computed variable names can also be used in substitution references: + +@example +@group +a_objects := a.o b.o c.o +1_objects := 1.o 2.o 3.o + +sources := $($(a1)_objects:.o=.c) +@end group +@end example + +@noindent +defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c}, +depending on the value of @code{a1}. + +The only restriction on this sort of use of nested variable references +is that they cannot specify part of the name of a function to be called. +This is because the test for a recognized function name is done before +the expansion of nested references. For example, + +@example +@group +ifdef do_sort +func := sort +else +func := strip +endif +@end group + +@group +bar := a d b g q c +@end group + +@group +foo := $($(func) $(bar)) +@end group +@end example + +@noindent +attempts to give @samp{foo} the value of the variable @samp{sort a d b g +q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c} +as the argument to either the @code{sort} or the @code{strip} function. +This restriction could be removed in the future if that change is shown +to be a good idea. + +You can also use computed variable names in the left-hand side of a +variable assignment, or in a @code{define} directive, as in: + +@example +dir = foo +$(dir)_sources := $(wildcard $(dir)/*.c) +define $(dir)_print = +lpr $($(dir)_sources) +endef +@end example + +@noindent +This example defines the variables @samp{dir}, @samp{foo_sources}, and +@samp{foo_print}. + +Note that @dfn{nested variable references} are quite different from +@dfn{recursively expanded variables} +(@pxref{Flavors, ,The Two Flavors of Variables}), though both are +used together in complex ways when doing makefile programming.@refill + +@node Values, Setting, Advanced, Using Variables +@section How Variables Get Their Values +@cindex variables, how they get their values +@cindex value, how a variable gets it + +Variables can get values in several different ways: + +@itemize @bullet +@item +You can specify an overriding value when you run @code{make}. +@xref{Overriding, ,Overriding Variables}. + +@item +You can specify a value in the makefile, either +with an assignment (@pxref{Setting, ,Setting Variables}) or with a +verbatim definition (@pxref{Multi-Line, ,Defining Multi-Line Variables}).@refill + +@item +Variables in the environment become @code{make} variables. +@xref{Environment, ,Variables from the Environment}. + +@item +Several @dfn{automatic} variables are given new values for each rule. +Each of these has a single conventional use. +@xref{Automatic Variables}. + +@item +Several variables have constant initial values. +@xref{Implicit Variables, ,Variables Used by Implicit Rules}. +@end itemize + +@node Setting, Appending, Values, Using Variables +@section Setting Variables +@cindex setting variables +@cindex variables, setting +@cindex = +@cindex := +@cindex ?= + +To set a variable from the makefile, write a line starting with the +variable name followed by @samp{=} or @samp{:=}. Whatever follows the +@samp{=} or @samp{:=} on the line becomes the value. For example, + +@example +objects = main.o foo.o bar.o utils.o +@end example + +@noindent +defines a variable named @code{objects}. Whitespace around the variable +name and immediately after the @samp{=} is ignored. + +Variables defined with @samp{=} are @dfn{recursively expanded} variables. +Variables defined with @samp{:=} are @dfn{simply expanded} variables; these +definitions can contain variable references which will be expanded before +the definition is made. @xref{Flavors, ,The Two Flavors of Variables}. + +The variable name may contain function and variable references, which +are expanded when the line is read to find the actual variable name to use. + +There is no limit on the length of the value of a variable except the +amount of swapping space on the computer. When a variable definition is +long, it is a good idea to break it into several lines by inserting +backslash-newline at convenient places in the definition. This will not +affect the functioning of @code{make}, but it will make the makefile easier +to read. + +Most variable names are considered to have the empty string as a value if +you have never set them. Several variables have built-in initial values +that are not empty, but you can set them in the usual ways +(@pxref{Implicit Variables, ,Variables Used by Implicit Rules}). +Several special variables are set +automatically to a new value for each rule; these are called the +@dfn{automatic} variables (@pxref{Automatic Variables}). + +If you'd like a variable to be set to a value only if it's not already +set, then you can use the shorthand operator @samp{?=} instead of +@samp{=}. These two settings of the variable @samp{FOO} are identical +(@pxref{Origin Function, ,The @code{origin} Function}): + +@example +FOO ?= bar +@end example + +@noindent +and + +@example +ifeq ($(origin FOO), undefined) +FOO = bar +endif +@end example + +@node Appending, Override Directive, Setting, Using Variables +@section Appending More Text to Variables +@cindex += +@cindex appending to variables +@cindex variables, appending to + +Often it is useful to add more text to the value of a variable already defined. +You do this with a line containing @samp{+=}, like this: + +@example +objects += another.o +@end example + +@noindent +This takes the value of the variable @code{objects}, and adds the text +@samp{another.o} to it (preceded by a single space). Thus: + +@example +objects = main.o foo.o bar.o utils.o +objects += another.o +@end example + +@noindent +sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}. + +Using @samp{+=} is similar to: + +@example +objects = main.o foo.o bar.o utils.o +objects := $(objects) another.o +@end example + +@noindent +but differs in ways that become important when you use more complex values. + +When the variable in question has not been defined before, @samp{+=} +acts just like normal @samp{=}: it defines a recursively-expanded +variable. However, when there @emph{is} a previous definition, exactly +what @samp{+=} does depends on what flavor of variable you defined +originally. @xref{Flavors, ,The Two Flavors of Variables}, for an +explanation of the two flavors of variables. + +When you add to a variable's value with @samp{+=}, @code{make} acts +essentially as if you had included the extra text in the initial +definition of the variable. If you defined it first with @samp{:=}, +making it a simply-expanded variable, @samp{+=} adds to that +simply-expanded definition, and expands the new text before appending it +to the old value just as @samp{:=} does +(see @ref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}). +In fact, + +@example +variable := value +variable += more +@end example + +@noindent +is exactly equivalent to: + +@noindent +@example +variable := value +variable := $(variable) more +@end example + +On the other hand, when you use @samp{+=} with a variable that you defined +first to be recursively-expanded using plain @samp{=}, @code{make} does +something a bit different. Recall that when you define a +recursively-expanded variable, @code{make} does not expand the value you set +for variable and function references immediately. Instead it stores the text +verbatim, and saves these variable and function references to be expanded +later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors +of Variables}). When you use @samp{+=} on a recursively-expanded variable, +it is this unexpanded text to which @code{make} appends the new text you +specify. + +@example +@group +variable = value +variable += more +@end group +@end example + +@noindent +is roughly equivalent to: + +@example +@group +temp = value +variable = $(temp) more +@end group +@end example + +@noindent +except that of course it never defines a variable called @code{temp}. +The importance of this comes when the variable's old value contains +variable references. Take this common example: + +@example +CFLAGS = $(includes) -O +@dots{} +CFLAGS += -pg # enable profiling +@end example + +@noindent +The first line defines the @code{CFLAGS} variable with a reference to another +variable, @code{includes}. (@code{CFLAGS} is used by the rules for C +compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.) +Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded +variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when +@code{make} processes the definition of @code{CFLAGS}. Thus, @code{includes} +need not be defined yet for its value to take effect. It only has to be +defined before any reference to @code{CFLAGS}. If we tried to append to the +value of @code{CFLAGS} without using @samp{+=}, we might do it like this: + +@example +CFLAGS := $(CFLAGS) -pg # enable profiling +@end example + +@noindent +This is pretty close, but not quite what we want. Using @samp{:=} +redefines @code{CFLAGS} as a simply-expanded variable; this means +@code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the +variable. If @code{includes} is not yet defined, we get @w{@samp{ -O +-pg}}, and a later definition of @code{includes} will have no effect. +Conversely, by using @samp{+=} we set @code{CFLAGS} to the +@emph{unexpanded} value @w{@samp{$(includes) -O -pg}}. Thus we preserve +the reference to @code{includes}, so if that variable gets defined at +any later point, a reference like @samp{$(CFLAGS)} still uses its +value. + +@node Override Directive, Multi-Line, Appending, Using Variables +@section The @code{override} Directive +@findex override +@cindex overriding with @code{override} +@cindex variables, overriding + +If a variable has been set with a command argument +(@pxref{Overriding, ,Overriding Variables}), +then ordinary assignments in the makefile are ignored. If you want to set +the variable in the makefile even though it was set with a command +argument, you can use an @code{override} directive, which is a line that +looks like this:@refill + +@example +override @var{variable} = @var{value} +@end example + +@noindent +or + +@example +override @var{variable} := @var{value} +@end example + +To append more text to a variable defined on the command line, use: + +@example +override @var{variable} += @var{more text} +@end example + +@noindent +@xref{Appending, ,Appending More Text to Variables}. + +Variable assignments marked with the @code{override} flag have a +higher priority than all other assignments, except another +@code{override}. Subsequent assignments or appends to this variable +which are not marked @code{override} will be ignored. + +The @code{override} directive was not invented for escalation in the war +between makefiles and command arguments. It was invented so you can alter +and add to values that the user specifies with command arguments. + +For example, suppose you always want the @samp{-g} switch when you run the +C compiler, but you would like to allow the user to specify the other +switches with a command argument just as usual. You could use this +@code{override} directive: + +@example +override CFLAGS += -g +@end example + +You can also use @code{override} directives with @code{define} directives. +This is done as you might expect: + +@example +override define foo = +bar +endef +@end example + +@noindent +@iftex +See the next section for information about @code{define}. +@end iftex +@ifnottex +@xref{Multi-Line, ,Defining Multi-Line Variables}. +@end ifnottex + +@node Multi-Line, Undefine Directive, Override Directive, Using Variables +@section Defining Multi-Line Variables +@findex define +@findex endef +@cindex multi-line variable definition +@cindex variables, multi-line +@cindex verbatim variable definition +@cindex defining variables verbatim +@cindex variables, defining verbatim + +Another way to set the value of a variable is to use the @code{define} +directive. This directive has an unusual syntax which allows newline +characters to be included in the value, which is convenient for +defining both canned sequences of commands (@pxref{Canned Recipes, +,Defining Canned Recipes}), and also sections of makefile syntax to +use with @code{eval} (@pxref{Eval Function}).@refill + +The @code{define} directive is followed on the same line by the name +of the variable being defined and an (optional) assignment operator, +and nothing more. The value to give the variable appears on the +following lines. The end of the value is marked by a line containing +just the word @code{endef}. Aside from this difference in syntax, +@code{define} works just like any other variable definition. The +variable name may contain function and variable references, which are +expanded when the directive is read to find the actual variable name +to use. + +You may omit the variable assignment operator if you prefer. If +omitted, @code{make} assumes it to be @samp{=} and creates a +recursively-expanded variable (@pxref{Flavors, ,The Two Flavors of Variables}). +When using a @samp{+=} operator, the value is appended to the previous +value as with any other append operation: with a single space +separating the old and new values. + +You may nest @code{define} directives: @code{make} will keep track of +nested directives and report an error if they are not all properly +closed with @code{endef}. Note that lines beginning with the recipe +prefix character are considered part of a recipe, so any @code{define} +or @code{endef} strings appearing on such a line will not be +considered @code{make} directives. + +@example +define two-lines = +echo foo +echo $(bar) +endef +@end example + +The value in an ordinary assignment cannot contain a newline; but the +newlines that separate the lines of the value in a @code{define} become +part of the variable's value (except for the final newline which precedes +the @code{endef} and is not considered part of the value).@refill + +@need 800 +When used in a recipe, the previous example is functionally equivalent +to this: + +@example +two-lines = echo foo; echo $(bar) +@end example + +@noindent +since two commands separated by semicolon behave much like two separate +shell commands. However, note that using two separate lines means +@code{make} will invoke the shell twice, running an independent subshell +for each line. @xref{Execution, ,Recipe Execution}. + +If you want variable definitions made with @code{define} to take +precedence over command-line variable definitions, you can use the +@code{override} directive together with @code{define}: + +@example +override define two-lines = +foo +$(bar) +endef +@end example + +@noindent +@xref{Override Directive, ,The @code{override} Directive}. + +@node Undefine Directive, Environment, Multi-Line, Using Variables +@section Undefining Variables +@findex undefine +@cindex undefining variable + +If you want to clear a variable, setting its value to empty is usually +sufficient. Expanding such a variable will yield the same result (empty +string) regardless of whether it was set or not. However, if you are +using the @code{flavor} (@pxref{Flavor Function}) and +@code{origin} (@pxref{Origin Function}) functions, there is a difference +between a variable that was never set and a variable with an empty value. +In such situations you may want to use the @code{undefine} directive to +make a variable appear as if it was never set. For example: + +@example +foo := foo +bar = bar + +undefine foo +undefine bar + +$(info $(origin foo)) +$(info $(flavor bar)) +@end example + +This example will print ``undefined'' for both variables. + +If you want to undefine a command-line variable definition, you can use +the @code{override} directive together with @code{undefine}, similar to +how this is done for variable definitions: + +@example +override undefine CFLAGS +@end example + +@node Environment, Target-specific, Undefine Directive, Using Variables +@section Variables from the Environment + +@cindex variables, environment +@cindex environment +Variables in @code{make} can come from the environment in which +@code{make} is run. Every environment variable that @code{make} sees +when it starts up is transformed into a @code{make} variable with the +same name and value. However, an explicit assignment in the makefile, +or with a command argument, overrides the environment. (If the +@samp{-e} flag is specified, then values from the environment override +assignments in the makefile. @xref{Options Summary, ,Summary of +Options}. But this is not recommended practice.) + +Thus, by setting the variable @code{CFLAGS} in your environment, you can +cause all C compilations in most makefiles to use the compiler switches you +prefer. This is safe for variables with standard or conventional meanings +because you know that no makefile will use them for other things. (Note +this is not totally reliable; some makefiles set @code{CFLAGS} explicitly +and therefore are not affected by the value in the environment.) + +When @code{make} runs a recipe, variables defined in the +makefile are placed into the environment of each shell. This allows +you to pass values to sub-@code{make} invocations (@pxref{Recursion, +,Recursive Use of @code{make}}). By default, only variables that came +from the environment or the command line are passed to recursive +invocations. You can use the @code{export} directive to pass other +variables. @xref{Variables/Recursion, , Communicating Variables to a +Sub-@code{make}}, for full details. + +Other use of variables from the environment is not recommended. It is not +wise for makefiles to depend for their functioning on environment variables +set up outside their control, since this would cause different users to get +different results from the same makefile. This is against the whole +purpose of most makefiles. + +@cindex SHELL, import from environment +Such problems would be especially likely with the variable +@code{SHELL}, which is normally present in the environment to specify +the user's choice of interactive shell. It would be very undesirable +for this choice to affect @code{make}; so, @code{make} handles the +@code{SHELL} environment variable in a special way; see @ref{Choosing +the Shell}.@refill + +@node Target-specific, Pattern-specific, Environment, Using Variables +@section Target-specific Variable Values +@cindex target-specific variables +@cindex variables, target-specific + +Variable values in @code{make} are usually global; that is, they are the +same regardless of where they are evaluated (unless they're reset, of +course). One exception to that is automatic variables +(@pxref{Automatic Variables}). + +The other exception is @dfn{target-specific variable values}. This +feature allows you to define different values for the same variable, +based on the target that @code{make} is currently building. As with +automatic variables, these values are only available within the context +of a target's recipe (and in other target-specific assignments). + +Set a target-specific variable value like this: + +@example +@var{target} @dots{} : @var{variable-assignment} +@end example + +Target-specific variable assignments can be prefixed with any or all of the +special keywords @code{export}, @code{override}, or @code{private}; +these apply their normal behavior to this instance of the variable only. + +Multiple @var{target} values create a target-specific variable value for +each member of the target list individually. + +The @var{variable-assignment} can be any valid form of assignment; +recursive (@samp{=}), static (@samp{:=}), appending (@samp{+=}), or +conditional (@samp{?=}). All variables that appear within the +@var{variable-assignment} are evaluated within the context of the +target: thus, any previously-defined target-specific variable values +will be in effect. Note that this variable is actually distinct from +any ``global'' value: the two variables do not have to have the same +flavor (recursive vs.@: static). + +Target-specific variables have the same priority as any other makefile +variable. Variables provided on the command line (and in the +environment if the @samp{-e} option is in force) will take precedence. +Specifying the @code{override} directive will allow the target-specific +variable value to be preferred. + +There is one more special feature of target-specific variables: when +you define a target-specific variable that variable value is also in +effect for all prerequisites of this target, and all their +prerequisites, etc.@: (unless those prerequisites override that variable +with their own target-specific variable value). So, for example, a +statement like this: + +@example +prog : CFLAGS = -g +prog : prog.o foo.o bar.o +@end example + +@noindent +will set @code{CFLAGS} to @samp{-g} in the recipe for @file{prog}, but +it will also set @code{CFLAGS} to @samp{-g} in the recipes that create +@file{prog.o}, @file{foo.o}, and @file{bar.o}, and any recipes which +create their prerequisites. + +Be aware that a given prerequisite will only be built once per +invocation of make, at most. If the same file is a prerequisite of +multiple targets, and each of those targets has a different value for +the same target-specific variable, then the first target to be built +will cause that prerequisite to be built and the prerequisite will +inherit the target-specific value from the first target. It will +ignore the target-specific values from any other targets. + +@node Pattern-specific, Suppressing Inheritance, Target-specific, Using Variables +@section Pattern-specific Variable Values +@cindex pattern-specific variables +@cindex variables, pattern-specific + +In addition to target-specific variable values +(@pxref{Target-specific, ,Target-specific Variable Values}), GNU +@code{make} supports pattern-specific variable values. In this form, +the variable is defined for any target that matches the pattern +specified. + +Set a pattern-specific variable value like this: + +@example +@var{pattern} @dots{} : @var{variable-assignment} +@end example +where @var{pattern} is a %-pattern. As with target-specific variable +values, multiple @var{pattern} values create a pattern-specific variable +value for each pattern individually. The @var{variable-assignment} can +be any valid form of assignment. Any command line variable setting will +take precedence, unless @code{override} is specified. + +For example: + +@example +%.o : CFLAGS = -O +@end example + +@noindent +will assign @code{CFLAGS} the value of @samp{-O} for all targets +matching the pattern @code{%.o}. + +If a target matches more than one pattern, the matching pattern-specific +variables with longer stems are interpreted first. This results in more +specific variables taking precedence over the more generic ones, for +example: + +@example +%.o: %.c + $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@ + +lib/%.o: CFLAGS := -fPIC -g +%.o: CFLAGS := -g + +all: foo.o lib/bar.o +@end example + +In this example the first definition of the @code{CFLAGS} variable +will be used to update @file{lib/bar.o} even though the second one +also applies to this target. Pattern-specific variables which result +in the same stem length are considered in the order in which they +were defined in the makefile. + +Pattern-specific variables are searched after any target-specific +variables defined explicitly for that target, and before target-specific +variables defined for the parent target. + +@node Suppressing Inheritance, Special Variables, Pattern-specific, Using Variables +@section Suppressing Inheritance +@findex private +@cindex suppressing inheritance +@cindex inheritance, suppressing + +As described in previous sections, @code{make} variables are inherited +by prerequisites. This capability allows you to modify the behavior +of a prerequisite based on which targets caused it to be rebuilt. For +example, you might set a target-specific variable on a @code{debug} +target, then running @samp{make debug} will cause that variable to be +inherited by all prerequisites of @code{debug}, while just running +@samp{make all} (for example) would not have that assignment. + +Sometimes, however, you may not want a variable to be inherited. For +these situations, @code{make} provides the @code{private} modifier. +Although this modifier can be used with any variable assignment, it +makes the most sense with target- and pattern-specific variables. Any +variable marked @code{private} will be visible to its local target but +will not be inherited by prerequisites of that target. A global +variable marked @code{private} will be visible in the global scope but +will not be inherited by any target, and hence will not be visible +in any recipe. + +As an example, consider this makefile: +@example +EXTRA_CFLAGS = + +prog: private EXTRA_CFLAGS = -L/usr/local/lib +prog: a.o b.o +@end example + +Due to the @code{private} modifier, @code{a.o} and @code{b.o} will not +inherit the @code{EXTRA_CFLAGS} variable assignment from the +@code{progs} target. + +@node Special Variables, , Suppressing Inheritance, Using Variables +@comment node-name, next, previous, up +@section Other Special Variables +@cindex makefiles, and special variables +@cindex special variables + +GNU @code{make} supports some variables that have special properties. + +@table @code + +@vindex MAKEFILE_LIST @r{(list of parsed makefiles)} +@cindex makefiles, and @code{MAKEFILE_LIST} variable +@cindex including (@code{MAKEFILE_LIST} variable) +@item MAKEFILE_LIST +Contains the name of each makefile that is parsed by @code{make}, in +the order in which it was parsed. The name is appended just +before @code{make} begins to parse the makefile. Thus, if the first +thing a makefile does is examine the last word in this variable, it +will be the name of the current makefile. Once the current makefile +has used @code{include}, however, the last word will be the +just-included makefile. + +If a makefile named @code{Makefile} has this content: + +@example +@group +name1 := $(lastword $(MAKEFILE_LIST)) + +include inc.mk + +name2 := $(lastword $(MAKEFILE_LIST)) + +all: + @@echo name1 = $(name1) + @@echo name2 = $(name2) +@end group +@end example + +@noindent +then you would expect to see this output: + +@example +@group +name1 = Makefile +name2 = inc.mk +@end group +@end example + +@vindex .DEFAULT_GOAL @r{(define default goal)} +@item .DEFAULT_GOAL +Sets the default goal to be used if no targets were specified on the +command line (@pxref{Goals, , Arguments to Specify the Goals}). The +@code{.DEFAULT_GOAL} variable allows you to discover the current +default goal, restart the default goal selection algorithm by clearing +its value, or to explicitly set the default goal. The following +example illustrates these cases: + +@example +@group +# Query the default goal. +ifeq ($(.DEFAULT_GOAL),) + $(warning no default goal is set) +endif + +.PHONY: foo +foo: ; @@echo $@@ + +$(warning default goal is $(.DEFAULT_GOAL)) + +# Reset the default goal. +.DEFAULT_GOAL := + +.PHONY: bar +bar: ; @@echo $@@ + +$(warning default goal is $(.DEFAULT_GOAL)) + +# Set our own. +.DEFAULT_GOAL := foo +@end group +@end example + +This makefile prints: + +@example +@group +no default goal is set +default goal is foo +default goal is bar +foo +@end group +@end example + +Note that assigning more than one target name to @code{.DEFAULT_GOAL} is +illegal and will result in an error. + +@vindex MAKE_RESTARTS @r{(number of times @code{make} has restarted)} +@item MAKE_RESTARTS +This variable is set only if this instance of @code{make} has +restarted (@pxref{Remaking Makefiles, , How Makefiles Are Remade}): it +will contain the number of times this instance has restarted. Note +this is not the same as recursion (counted by the @code{MAKELEVEL} +variable). You should not set, modify, or export this variable. + +@vindex .RECIPEPREFIX @r{(change the recipe prefix character)} +@item .RECIPEPREFIX +The first character of the value of this variable is used as the +character make assumes is introducing a recipe line. If the variable +is empty (as it is by default) that character is the standard tab +character. For example, this is a valid makefile: + +@example +@group +.RECIPEPREFIX = > +all: +> @@echo Hello, world +@end group +@end example + +The value of @code{.RECIPEPREFIX} can be changed multiple times; once set +it stays in effect for all rules parsed until it is modified. + +@vindex .VARIABLES @r{(list of variables)} +@item .VARIABLES +Expands to a list of the @emph{names} of all global variables defined +so far. This includes variables which have empty values, as well as +built-in variables (@pxref{Implicit Variables, , Variables Used by +Implicit Rules}), but does not include any variables which are only +defined in a target-specific context. Note that any value you assign +to this variable will be ignored; it will always return its special +value. + +@c @vindex .TARGETS @r{(list of targets)} +@c @item .TARGETS +@c The second special variable is @code{.TARGETS}. When expanded, the +@c value consists of a list of all targets defined in all makefiles read +@c up until that point. Note it's not enough for a file to be simply +@c mentioned in the makefile to be listed in this variable, even if it +@c would match an implicit rule and become an ``implicit target''. The +@c file must appear as a target, on the left-hand side of a ``:'', to be +@c considered a target for the purposes of this variable. + +@vindex .FEATURES @r{(list of supported features)} +@item .FEATURES +Expands to a list of special features supported by this version of +@code{make}. Possible values include: + +@table @samp + +@item archives +Supports @code{ar} (archive) files using special filename syntax. +@xref{Archives, ,Using @code{make} to Update Archive Files}. + +@item check-symlink +Supports the @code{-L} (@code{--check-symlink-times}) flag. +@xref{Options Summary, ,Summary of Options}. + +@item else-if +Supports ``else if'' non-nested conditionals. @xref{Conditional +Syntax, ,Syntax of Conditionals}. + +@item jobserver +Supports ``job server'' enhanced parallel builds. @xref{Parallel, +,Parallel Execution}. + +@item second-expansion +Supports secondary expansion of prerequisite lists. + +@item order-only +Supports order-only prerequisites. @xref{Prerequisite Types, ,Types +of Prerequisites}. + +@item target-specific +Supports target-specific and pattern-specific variable assignments. +@xref{Target-specific, ,Target-specific Variable Values}. + +@end table + +@vindex .INCLUDE_DIRS @r{(list of include directories)} +@item .INCLUDE_DIRS +Expands to a list of directories that @code{make} searches for +included makefiles (@pxref{Include, , Including Other Makefiles}). + +@end table + +@node Conditionals, Functions, Using Variables, Top +@chapter Conditional Parts of Makefiles + +@cindex conditionals +A @dfn{conditional} directive causes part of a makefile to be obeyed +or ignored depending on the values of variables. Conditionals can +compare the value of one variable to another, or the value of a +variable to a constant string. Conditionals control what @code{make} +actually ``sees'' in the makefile, so they @emph{cannot} be used to +control recipes at the time of execution.@refill + +@menu +* Conditional Example:: Example of a conditional +* Conditional Syntax:: The syntax of conditionals. +* Testing Flags:: Conditionals that test flags. +@end menu + +@node Conditional Example, Conditional Syntax, Conditionals, Conditionals +@section Example of a Conditional + +The following example of a conditional tells @code{make} to use one +set of libraries if the @code{CC} variable is @samp{gcc}, and a +different set of libraries otherwise. It works by controlling which +of two recipe lines will be used for the rule. The result is that +@samp{CC=gcc} as an argument to @code{make} changes not only which +compiler is used but also which libraries are linked. + +@example +libs_for_gcc = -lgnu +normal_libs = + +foo: $(objects) +ifeq ($(CC),gcc) + $(CC) -o foo $(objects) $(libs_for_gcc) +else + $(CC) -o foo $(objects) $(normal_libs) +endif +@end example + +This conditional uses three directives: one @code{ifeq}, one @code{else} +and one @code{endif}. + +The @code{ifeq} directive begins the conditional, and specifies the +condition. It contains two arguments, separated by a comma and surrounded +by parentheses. Variable substitution is performed on both arguments and +then they are compared. The lines of the makefile following the +@code{ifeq} are obeyed if the two arguments match; otherwise they are +ignored. + +The @code{else} directive causes the following lines to be obeyed if the +previous conditional failed. In the example above, this means that the +second alternative linking command is used whenever the first alternative +is not used. It is optional to have an @code{else} in a conditional. + +The @code{endif} directive ends the conditional. Every conditional must +end with an @code{endif}. Unconditional makefile text follows. + +As this example illustrates, conditionals work at the textual level: +the lines of the conditional are treated as part of the makefile, or +ignored, according to the condition. This is why the larger syntactic +units of the makefile, such as rules, may cross the beginning or the +end of the conditional. + +When the variable @code{CC} has the value @samp{gcc}, the above example has +this effect: + +@example +foo: $(objects) + $(CC) -o foo $(objects) $(libs_for_gcc) +@end example + +@noindent +When the variable @code{CC} has any other value, the effect is this: + +@example +foo: $(objects) + $(CC) -o foo $(objects) $(normal_libs) +@end example + +Equivalent results can be obtained in another way by conditionalizing a +variable assignment and then using the variable unconditionally: + +@example +libs_for_gcc = -lgnu +normal_libs = + +ifeq ($(CC),gcc) + libs=$(libs_for_gcc) +else + libs=$(normal_libs) +endif + +foo: $(objects) + $(CC) -o foo $(objects) $(libs) +@end example + +@node Conditional Syntax, Testing Flags, Conditional Example, Conditionals +@section Syntax of Conditionals +@findex ifdef +@findex ifeq +@findex ifndef +@findex ifneq +@findex else +@findex endif + +The syntax of a simple conditional with no @code{else} is as follows: + +@example +@var{conditional-directive} +@var{text-if-true} +endif +@end example + +@noindent +The @var{text-if-true} may be any lines of text, to be considered as part +of the makefile if the condition is true. If the condition is false, no +text is used instead. + +The syntax of a complex conditional is as follows: + +@example +@var{conditional-directive} +@var{text-if-true} +else +@var{text-if-false} +endif +@end example + +or: + +@example +@var{conditional-directive} +@var{text-if-one-is-true} +else @var{conditional-directive} +@var{text-if-true} +else +@var{text-if-false} +endif +@end example + +@noindent +There can be as many ``@code{else} @var{conditional-directive}'' +clauses as necessary. Once a given condition is true, +@var{text-if-true} is used and no other clause is used; if no +condition is true then @var{text-if-false} is used. The +@var{text-if-true} and @var{text-if-false} can be any number of lines +of text. + +The syntax of the @var{conditional-directive} is the same whether the +conditional is simple or complex; after an @code{else} or not. There +are four different directives that test different conditions. Here is +a table of them: + +@table @code +@item ifeq (@var{arg1}, @var{arg2}) +@itemx ifeq '@var{arg1}' '@var{arg2}' +@itemx ifeq "@var{arg1}" "@var{arg2}" +@itemx ifeq "@var{arg1}" '@var{arg2}' +@itemx ifeq '@var{arg1}' "@var{arg2}" +Expand all variable references in @var{arg1} and @var{arg2} and +compare them. If they are identical, the @var{text-if-true} is +effective; otherwise, the @var{text-if-false}, if any, is effective. + +Often you want to test if a variable has a non-empty value. When the +value results from complex expansions of variables and functions, +expansions you would consider empty may actually contain whitespace +characters and thus are not seen as empty. However, you can use the +@code{strip} function (@pxref{Text Functions}) to avoid interpreting +whitespace as a non-empty value. For example: + +@example +@group +ifeq ($(strip $(foo)),) +@var{text-if-empty} +endif +@end group +@end example + +@noindent +will evaluate @var{text-if-empty} even if the expansion of +@code{$(foo)} contains whitespace characters. + +@item ifneq (@var{arg1}, @var{arg2}) +@itemx ifneq '@var{arg1}' '@var{arg2}' +@itemx ifneq "@var{arg1}" "@var{arg2}" +@itemx ifneq "@var{arg1}" '@var{arg2}' +@itemx ifneq '@var{arg1}' "@var{arg2}" +Expand all variable references in @var{arg1} and @var{arg2} and +compare them. If they are different, the @var{text-if-true} is +effective; otherwise, the @var{text-if-false}, if any, is effective. + +@item ifdef @var{variable-name} +The @code{ifdef} form takes the @emph{name} of a variable as its +argument, not a reference to a variable. The value of that variable +has a non-empty value, the @var{text-if-true} is effective; otherwise, +the @var{text-if-false}, if any, is effective. Variables that have +never been defined have an empty value. The text @var{variable-name} +is expanded, so it could be a variable or function that expands +to the name of a variable. For example: + +@example +bar = true +foo = bar +ifdef $(foo) +frobozz = yes +endif +@end example + +The variable reference @code{$(foo)} is expanded, yielding @code{bar}, +which is considered to be the name of a variable. The variable +@code{bar} is not expanded, but its value is examined to determine if +it is non-empty. + +Note that @code{ifdef} only tests whether a variable has a value. It +does not expand the variable to see if that value is nonempty. +Consequently, tests using @code{ifdef} return true for all definitions +except those like @code{foo =}. To test for an empty value, use +@w{@code{ifeq ($(foo),)}}. For example, + +@example +bar = +foo = $(bar) +ifdef foo +frobozz = yes +else +frobozz = no +endif +@end example + +@noindent +sets @samp{frobozz} to @samp{yes}, while: + +@example +foo = +ifdef foo +frobozz = yes +else +frobozz = no +endif +@end example + +@noindent +sets @samp{frobozz} to @samp{no}. + +@item ifndef @var{variable-name} +If the variable @var{variable-name} has an empty value, the +@var{text-if-true} is effective; otherwise, the @var{text-if-false}, +if any, is effective. The rules for expansion and testing of +@var{variable-name} are identical to the @code{ifdef} directive. +@end table + +Extra spaces are allowed and ignored at the beginning of the +conditional directive line, but a tab is not allowed. (If the line +begins with a tab, it will be considered part of a recipe for a rule.) +Aside from this, extra spaces or tabs may be inserted with no effect +anywhere except within the directive name or within an argument. A +comment starting with @samp{#} may appear at the end of the line. + +The other two directives that play a part in a conditional are @code{else} +and @code{endif}. Each of these directives is written as one word, with no +arguments. Extra spaces are allowed and ignored at the beginning of the +line, and spaces or tabs at the end. A comment starting with @samp{#} may +appear at the end of the line. + +Conditionals affect which lines of the makefile @code{make} uses. If +the condition is true, @code{make} reads the lines of the +@var{text-if-true} as part of the makefile; if the condition is false, +@code{make} ignores those lines completely. It follows that syntactic +units of the makefile, such as rules, may safely be split across the +beginning or the end of the conditional.@refill + +@code{make} evaluates conditionals when it reads a makefile. +Consequently, you cannot use automatic variables in the tests of +conditionals because they are not defined until recipes are run +(@pxref{Automatic Variables}). + +To prevent intolerable confusion, it is not permitted to start a +conditional in one makefile and end it in another. However, you may +write an @code{include} directive within a conditional, provided you do +not attempt to terminate the conditional inside the included file. + +@node Testing Flags, , Conditional Syntax, Conditionals +@section Conditionals that Test Flags + +You can write a conditional that tests @code{make} command flags such as +@samp{-t} by using the variable @code{MAKEFLAGS} together with the +@code{findstring} function +(@pxref{Text Functions, , Functions for String Substitution and Analysis}). +This is useful when @code{touch} is not enough to make a file appear up +to date. + +The @code{findstring} function determines whether one string appears as a +substring of another. If you want to test for the @samp{-t} flag, +use @samp{t} as the first string and the value of @code{MAKEFLAGS} as +the other. + +For example, here is how to arrange to use @samp{ranlib -t} to finish +marking an archive file up to date: + +@example +archive.a: @dots{} +ifneq (,$(findstring t,$(MAKEFLAGS))) + +touch archive.a + +ranlib -t archive.a +else + ranlib archive.a +endif +@end example + +@noindent +The @samp{+} prefix marks those recipe lines as ``recursive'' so that +they will be executed despite use of the @samp{-t} flag. +@xref{Recursion, ,Recursive Use of @code{make}}. + +@node Functions, Running, Conditionals, Top +@chapter Functions for Transforming Text +@cindex functions + +@dfn{Functions} allow you to do text processing in the makefile to +compute the files to operate on or the commands to use in recipes. +You use a function in a @dfn{function call}, where you give the name +of the function and some text (the @dfn{arguments}) for the function +to operate on. The result of the function's processing is substituted +into the makefile at the point of the call, just as a variable might +be substituted. + +@menu +* Syntax of Functions:: How to write a function call. +* Text Functions:: General-purpose text manipulation functions. +* File Name Functions:: Functions for manipulating file names. +* Conditional Functions:: Functions that implement conditions. +* Foreach Function:: Repeat some text with controlled variation. +* Call Function:: Expand a user-defined function. +* Value Function:: Return the un-expanded value of a variable. +* Eval Function:: Evaluate the arguments as makefile syntax. +* Origin Function:: Find where a variable got its value. +* Flavor Function:: Find out the flavor of a variable. +* Shell Function:: Substitute the output of a shell command. +* Make Control Functions:: Functions that control how make runs. +@end menu + +@node Syntax of Functions, Text Functions, Functions, Functions +@section Function Call Syntax +@cindex @code{$}, in function call +@cindex dollar sign (@code{$}), in function call +@cindex arguments of functions +@cindex functions, syntax of + +A function call resembles a variable reference. It looks like this: + +@example +$(@var{function} @var{arguments}) +@end example + +@noindent +or like this: + +@example +$@{@var{function} @var{arguments}@} +@end example + +Here @var{function} is a function name; one of a short list of names +that are part of @code{make}. You can also essentially create your own +functions by using the @code{call} builtin function. + +The @var{arguments} are the arguments of the function. They are +separated from the function name by one or more spaces or tabs, and if +there is more than one argument, then they are separated by commas. +Such whitespace and commas are not part of an argument's value. The +delimiters which you use to surround the function call, whether +parentheses or braces, can appear in an argument only in matching pairs; +the other kind of delimiters may appear singly. If the arguments +themselves contain other function calls or variable references, it is +wisest to use the same kind of delimiters for all the references; write +@w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}. This +is because it is clearer, and because only one type of delimiter is +matched to find the end of the reference. + +The text written for each argument is processed by substitution of +variables and function calls to produce the argument value, which +is the text on which the function acts. The substitution is done in the +order in which the arguments appear. + +Commas and unmatched parentheses or braces cannot appear in the text of an +argument as written; leading spaces cannot appear in the text of the first +argument as written. These characters can be put into the argument value +by variable substitution. First define variables @code{comma} and +@code{space} whose values are isolated comma and space characters, then +substitute these variables where such characters are wanted, like this: + +@example +@group +comma:= , +empty:= +space:= $(empty) $(empty) +foo:= a b c +bar:= $(subst $(space),$(comma),$(foo)) +# @r{bar is now `a,b,c'.} +@end group +@end example + +@noindent +Here the @code{subst} function replaces each space with a comma, through +the value of @code{foo}, and substitutes the result. + +@node Text Functions, File Name Functions, Syntax of Functions, Functions +@section Functions for String Substitution and Analysis +@cindex functions, for text + +Here are some functions that operate on strings: + +@table @code +@item $(subst @var{from},@var{to},@var{text}) +@findex subst +Performs a textual replacement on the text @var{text}: each occurrence +of @var{from} is replaced by @var{to}. The result is substituted for +the function call. For example, + +@example +$(subst ee,EE,feet on the street) +@end example + +substitutes the string @samp{fEEt on the strEEt}. + +@item $(patsubst @var{pattern},@var{replacement},@var{text}) +@findex patsubst +Finds whitespace-separated words in @var{text} that match +@var{pattern} and replaces them with @var{replacement}. Here +@var{pattern} may contain a @samp{%} which acts as a wildcard, +matching any number of any characters within a word. If +@var{replacement} also contains a @samp{%}, the @samp{%} is replaced +by the text that matched the @samp{%} in @var{pattern}. Only the first +@samp{%} in the @var{pattern} and @var{replacement} is treated this +way; any subsequent @samp{%} is unchanged.@refill + +@cindex @code{%}, quoting in @code{patsubst} +@cindex @code{%}, quoting with @code{\} (backslash) +@cindex @code{\} (backslash), to quote @code{%} +@cindex backslash (@code{\}), to quote @code{%} +@cindex quoting @code{%}, in @code{patsubst} +@samp{%} characters in @code{patsubst} function invocations can be +quoted with preceding backslashes (@samp{\}). Backslashes that would +otherwise quote @samp{%} characters can be quoted with more backslashes. +Backslashes that quote @samp{%} characters or other backslashes are +removed from the pattern before it is compared file names or has a stem +substituted into it. Backslashes that are not in danger of quoting +@samp{%} characters go unmolested. For example, the pattern +@file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the +operative @samp{%} character, and @samp{pattern\\} following it. The +final two backslashes are left alone because they cannot affect any +@samp{%} character.@refill + +Whitespace between words is folded into single space characters; +leading and trailing whitespace is discarded. + +For example, + +@example +$(patsubst %.c,%.o,x.c.c bar.c) +@end example + +@noindent +produces the value @samp{x.c.o bar.o}. + +Substitution references (@pxref{Substitution Refs, ,Substitution +References}) are a simpler way to get the effect of the @code{patsubst} +function: + +@example +$(@var{var}:@var{pattern}=@var{replacement}) +@end example + +@noindent +is equivalent to + +@example +$(patsubst @var{pattern},@var{replacement},$(@var{var})) +@end example + +The second shorthand simplifies one of the most common uses of +@code{patsubst}: replacing the suffix at the end of file names. + +@example +$(@var{var}:@var{suffix}=@var{replacement}) +@end example + +@noindent +is equivalent to + +@example +$(patsubst %@var{suffix},%@var{replacement},$(@var{var})) +@end example + +@noindent +For example, you might have a list of object files: + +@example +objects = foo.o bar.o baz.o +@end example + +@noindent +To get the list of corresponding source files, you could simply write: + +@example +$(objects:.o=.c) +@end example + +@noindent +instead of using the general form: + +@example +$(patsubst %.o,%.c,$(objects)) +@end example + +@item $(strip @var{string}) +@cindex stripping whitespace +@cindex whitespace, stripping +@cindex spaces, stripping +@findex strip +Removes leading and trailing whitespace from @var{string} and replaces +each internal sequence of one or more whitespace characters with a +single space. Thus, @samp{$(strip a b c )} results in @w{@samp{a b c}}. + +The function @code{strip} can be very useful when used in conjunction +with conditionals. When comparing something with the empty string +@samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of +just whitespace to match the empty string (@pxref{Conditionals}). + +Thus, the following may fail to have the desired results: + +@example +.PHONY: all +ifneq "$(needs_made)" "" +all: $(needs_made) +else +all:;@@echo 'Nothing to make!' +endif +@end example + +@noindent +Replacing the variable reference @w{@samp{$(needs_made)}} with the +function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq} +directive would make it more robust.@refill + +@item $(findstring @var{find},@var{in}) +@findex findstring +@cindex searching for strings +@cindex finding strings +@cindex strings, searching for +Searches @var{in} for an occurrence of @var{find}. If it occurs, the +value is @var{find}; otherwise, the value is empty. You can use this +function in a conditional to test for the presence of a specific +substring in a given string. Thus, the two examples, + +@example +$(findstring a,a b c) +$(findstring a,b c) +@end example + +@noindent +produce the values @samp{a} and @samp{} (the empty string), +respectively. @xref{Testing Flags}, for a practical application of +@code{findstring}.@refill + +@need 750 +@findex filter +@cindex filtering words +@cindex words, filtering +@item $(filter @var{pattern}@dots{},@var{text}) +Returns all whitespace-separated words in @var{text} that @emph{do} match +any of the @var{pattern} words, removing any words that @emph{do not} +match. The patterns are written using @samp{%}, just like the patterns +used in the @code{patsubst} function above.@refill + +The @code{filter} function can be used to separate out different types +of strings (such as file names) in a variable. For example: + +@example +sources := foo.c bar.c baz.s ugh.h +foo: $(sources) + cc $(filter %.c %.s,$(sources)) -o foo +@end example + +@noindent +says that @file{foo} depends of @file{foo.c}, @file{bar.c}, +@file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and +@file{baz.s} should be specified in the command to the +compiler.@refill + +@item $(filter-out @var{pattern}@dots{},@var{text}) +@findex filter-out +@cindex filtering out words +@cindex words, filtering out +Returns all whitespace-separated words in @var{text} that @emph{do not} +match any of the @var{pattern} words, removing the words that @emph{do} +match one or more. This is the exact opposite of the @code{filter} +function.@refill + +For example, given: + +@example +@group +objects=main1.o foo.o main2.o bar.o +mains=main1.o main2.o +@end group +@end example + +@noindent +the following generates a list which contains all the object files not +in @samp{mains}: + +@example +$(filter-out $(mains),$(objects)) +@end example + +@need 1500 +@findex sort +@cindex sorting words +@item $(sort @var{list}) +Sorts the words of @var{list} in lexical order, removing duplicate +words. The output is a list of words separated by single spaces. +Thus, + +@example +$(sort foo bar lose) +@end example + +@noindent +returns the value @samp{bar foo lose}. + +@cindex removing duplicate words +@cindex duplicate words, removing +@cindex words, removing duplicates +Incidentally, since @code{sort} removes duplicate words, you can use +it for this purpose even if you don't care about the sort order. + +@item $(word @var{n},@var{text}) +@findex word +@cindex word, selecting a +@cindex selecting a word +Returns the @var{n}th word of @var{text}. The legitimate values of +@var{n} start from 1. If @var{n} is bigger than the number of words +in @var{text}, the value is empty. For example, + +@example +$(word 2, foo bar baz) +@end example + +@noindent +returns @samp{bar}. + +@item $(wordlist @var{s},@var{e},@var{text}) +@findex wordlist +@cindex words, selecting lists of +@cindex selecting word lists +Returns the list of words in @var{text} starting with word @var{s} and +ending with word @var{e} (inclusive). The legitimate values of @var{s} +start from 1; @var{e} may start from 0. If @var{s} is bigger than the +number of words in @var{text}, the value is empty. If @var{e} is +bigger than the number of words in @var{text}, words up to the end of +@var{text} are returned. If @var{s} is greater than @var{e}, nothing +is returned. For example, + +@example +$(wordlist 2, 3, foo bar baz) +@end example + +@noindent +returns @samp{bar baz}. + +@c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92 +@item $(words @var{text}) +@findex words +@cindex words, finding number +Returns the number of words in @var{text}. +Thus, the last word of @var{text} is +@w{@code{$(word $(words @var{text}),@var{text})}}.@refill + +@item $(firstword @var{names}@dots{}) +@findex firstword +@cindex words, extracting first +The argument @var{names} is regarded as a series of names, separated +by whitespace. The value is the first name in the series. The rest +of the names are ignored. + +For example, + +@example +$(firstword foo bar) +@end example + +@noindent +produces the result @samp{foo}. Although @code{$(firstword +@var{text})} is the same as @code{$(word 1,@var{text})}, the +@code{firstword} function is retained for its simplicity.@refill + + +@item $(lastword @var{names}@dots{}) +@findex lastword +@cindex words, extracting last +The argument @var{names} is regarded as a series of names, separated +by whitespace. The value is the last name in the series. + +For example, + +@example +$(lastword foo bar) +@end example + +@noindent +produces the result @samp{bar}. Although @code{$(lastword +@var{text})} is the same as @code{$(word $(words @var{text}),@var{text})}, +the @code{lastword} function was added for its simplicity and better +performance.@refill +@end table + + +Here is a realistic example of the use of @code{subst} and +@code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable +to specify a list of directories that @code{make} should search for +prerequisite files +(@pxref{General Search, , @code{VPATH} Search Path for All Prerequisites}). +This example shows how to +tell the C compiler to search for header files in the same list of +directories.@refill + +The value of @code{VPATH} is a list of directories separated by colons, +such as @samp{src:../headers}. First, the @code{subst} function is used to +change the colons to spaces: + +@example +$(subst :, ,$(VPATH)) +@end example + +@noindent +This produces @samp{src ../headers}. Then @code{patsubst} is used to turn +each directory name into a @samp{-I} flag. These can be added to the +value of the variable @code{CFLAGS}, which is passed automatically to the C +compiler, like this: + +@example +override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH))) +@end example + +@noindent +The effect is to append the text @samp{-Isrc -I../headers} to the +previously given value of @code{CFLAGS}. The @code{override} directive is +used so that the new value is assigned even if the previous value of +@code{CFLAGS} was specified with a command argument (@pxref{Override +Directive, , The @code{override} Directive}). + +@node File Name Functions, Conditional Functions, Text Functions, Functions +@section Functions for File Names +@cindex functions, for file names +@cindex file name functions + +Several of the built-in expansion functions relate specifically to +taking apart file names or lists of file names. + +Each of the following functions performs a specific transformation on a +file name. The argument of the function is regarded as a series of file +names, separated by whitespace. (Leading and trailing whitespace is +ignored.) Each file name in the series is transformed in the same way and +the results are concatenated with single spaces between them. + +@table @code +@item $(dir @var{names}@dots{}) +@findex dir +@cindex directory part +@cindex file name, directory part +Extracts the directory-part of each file name in @var{names}. The +directory-part of the file name is everything up through (and +including) the last slash in it. If the file name contains no slash, +the directory part is the string @samp{./}. For example, + +@example +$(dir src/foo.c hacks) +@end example + +@noindent +produces the result @samp{src/ ./}. + +@item $(notdir @var{names}@dots{}) +@findex notdir +@cindex file name, nondirectory part +@cindex nondirectory part +Extracts all but the directory-part of each file name in @var{names}. +If the file name contains no slash, it is left unchanged. Otherwise, +everything through the last slash is removed from it. + +A file name that ends with a slash becomes an empty string. This is +unfortunate, because it means that the result does not always have the +same number of whitespace-separated file names as the argument had; +but we do not see any other valid alternative. + +For example, + +@example +$(notdir src/foo.c hacks) +@end example + +@noindent +produces the result @samp{foo.c hacks}. + +@item $(suffix @var{names}@dots{}) +@findex suffix +@cindex suffix, function to find +@cindex file name suffix +Extracts the suffix of each file name in @var{names}. If the file name +contains a period, the suffix is everything starting with the last +period. Otherwise, the suffix is the empty string. This frequently +means that the result will be empty when @var{names} is not, and if +@var{names} contains multiple file names, the result may contain fewer +file names. + +For example, + +@example +$(suffix src/foo.c src-1.0/bar.c hacks) +@end example + +@noindent +produces the result @samp{.c .c}. + +@item $(basename @var{names}@dots{}) +@findex basename +@cindex basename +@cindex file name, basename of +Extracts all but the suffix of each file name in @var{names}. If the +file name contains a period, the basename is everything starting up to +(and not including) the last period. Periods in the directory part are +ignored. If there is no period, the basename is the entire file name. +For example, + +@example +$(basename src/foo.c src-1.0/bar hacks) +@end example + +@noindent +produces the result @samp{src/foo src-1.0/bar hacks}. + +@c plural convention with dots (be consistent) +@item $(addsuffix @var{suffix},@var{names}@dots{}) +@findex addsuffix +@cindex suffix, adding +@cindex file name suffix, adding +The argument @var{names} is regarded as a series of names, separated +by whitespace; @var{suffix} is used as a unit. The value of +@var{suffix} is appended to the end of each individual name and the +resulting larger names are concatenated with single spaces between +them. For example, + +@example +$(addsuffix .c,foo bar) +@end example + +@noindent +produces the result @samp{foo.c bar.c}. + +@item $(addprefix @var{prefix},@var{names}@dots{}) +@findex addprefix +@cindex prefix, adding +@cindex file name prefix, adding +The argument @var{names} is regarded as a series of names, separated +by whitespace; @var{prefix} is used as a unit. The value of +@var{prefix} is prepended to the front of each individual name and the +resulting larger names are concatenated with single spaces between +them. For example, + +@example +$(addprefix src/,foo bar) +@end example + +@noindent +produces the result @samp{src/foo src/bar}. + +@item $(join @var{list1},@var{list2}) +@findex join +@cindex joining lists of words +@cindex words, joining lists +Concatenates the two arguments word by word: the two first words (one +from each argument) concatenated form the first word of the result, the +two second words form the second word of the result, and so on. So the +@var{n}th word of the result comes from the @var{n}th word of each +argument. If one argument has more words that the other, the extra +words are copied unchanged into the result. + +For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}. + +Whitespace between the words in the lists is not preserved; it is +replaced with a single space. + +This function can merge the results of the @code{dir} and +@code{notdir} functions, to produce the original list of files which +was given to those two functions.@refill + +@item $(wildcard @var{pattern}) +@findex wildcard +@cindex wildcard, function +The argument @var{pattern} is a file name pattern, typically containing +wildcard characters (as in shell file name patterns). The result of +@code{wildcard} is a space-separated list of the names of existing files +that match the pattern. +@xref{Wildcards, ,Using Wildcard Characters in File Names}. + +@item $(realpath @var{names}@dots{}) +@findex realpath +@cindex realpath +@cindex file name, realpath of +For each file name in @var{names} return the canonical absolute name. +A canonical name does not contain any @code{.} or @code{..} components, +nor any repeated path separators (@code{/}) or symlinks. In case of a +failure the empty string is returned. Consult the @code{realpath(3)} +documentation for a list of possible failure causes. + +@item $(abspath @var{names}@dots{}) +@findex abspath +@cindex abspath +@cindex file name, abspath of +For each file name in @var{names} return an absolute name that does +not contain any @code{.} or @code{..} components, nor any repeated path +separators (@code{/}). Note that, in contrast to @code{realpath} +function, @code{abspath} does not resolve symlinks and does not require +the file names to refer to an existing file or directory. Use the +@code{wildcard} function to test for existence. +@end table + +@node Conditional Functions, Foreach Function, File Name Functions, Functions +@section Functions for Conditionals +@findex if +@cindex conditional expansion +There are three functions that provide conditional expansion. A key +aspect of these functions is that not all of the arguments are +expanded initially. Only those arguments which need to be expanded, +will be expanded. + +@table @code +@item $(if @var{condition},@var{then-part}[,@var{else-part}]) +@findex if +The @code{if} function provides support for conditional expansion in a +functional context (as opposed to the GNU @code{make} makefile +conditionals such as @code{ifeq} (@pxref{Conditional Syntax, ,Syntax of +Conditionals}). + +The first argument, @var{condition}, first has all preceding and +trailing whitespace stripped, then is expanded. If it expands to any +non-empty string, then the condition is considered to be true. If it +expands to an empty string, the condition is considered to be false. + +If the condition is true then the second argument, @var{then-part}, is +evaluated and this is used as the result of the evaluation of the entire +@code{if} function. + +If the condition is false then the third argument, @var{else-part}, is +evaluated and this is the result of the @code{if} function. If there is +no third argument, the @code{if} function evaluates to nothing (the +empty string). + +Note that only one of the @var{then-part} or the @var{else-part} will be +evaluated, never both. Thus, either can contain side-effects (such as +@code{shell} function calls, etc.) + +@item $(or @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]]) +@findex or +The @code{or} function provides a ``short-circuiting'' OR operation. +Each argument is expanded, in order. If an argument expands to a +non-empty string the processing stops and the result of the expansion +is that string. If, after all arguments are expanded, all of them are +false (empty), then the result of the expansion is the empty string. + +@item $(and @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]]) +@findex and +The @code{and} function provides a ``short-circuiting'' AND operation. +Each argument is expanded, in order. If an argument expands to an +empty string the processing stops and the result of the expansion is +the empty string. If all arguments expand to a non-empty string then +the result of the expansion is the expansion of the last argument. + +@end table + +@node Foreach Function, Call Function, Conditional Functions, Functions +@section The @code{foreach} Function +@findex foreach +@cindex words, iterating over + +The @code{foreach} function is very different from other functions. It +causes one piece of text to be used repeatedly, each time with a different +substitution performed on it. It resembles the @code{for} command in the +shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}. + +The syntax of the @code{foreach} function is: + +@example +$(foreach @var{var},@var{list},@var{text}) +@end example + +@noindent +The first two arguments, @var{var} and @var{list}, are expanded before +anything else is done; note that the last argument, @var{text}, is +@strong{not} expanded at the same time. Then for each word of the expanded +value of @var{list}, the variable named by the expanded value of @var{var} +is set to that word, and @var{text} is expanded. Presumably @var{text} +contains references to that variable, so its expansion will be different +each time. + +The result is that @var{text} is expanded as many times as there are +whitespace-separated words in @var{list}. The multiple expansions of +@var{text} are concatenated, with spaces between them, to make the result +of @code{foreach}. + +This simple example sets the variable @samp{files} to the list of all files +in the directories in the list @samp{dirs}: + +@example +dirs := a b c d +files := $(foreach dir,$(dirs),$(wildcard $(dir)/*)) +@end example + +Here @var{text} is @samp{$(wildcard $(dir)/*)}. The first repetition +finds the value @samp{a} for @code{dir}, so it produces the same result +as @samp{$(wildcard a/*)}; the second repetition produces the result +of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}. + +This example has the same result (except for setting @samp{dirs}) as +the following example: + +@example +files := $(wildcard a/* b/* c/* d/*) +@end example + +When @var{text} is complicated, you can improve readability by giving it +a name, with an additional variable: + +@example +find_files = $(wildcard $(dir)/*) +dirs := a b c d +files := $(foreach dir,$(dirs),$(find_files)) +@end example + +@noindent +Here we use the variable @code{find_files} this way. We use plain @samp{=} +to define a recursively-expanding variable, so that its value contains an +actual function call to be reexpanded under the control of @code{foreach}; +a simply-expanded variable would not do, since @code{wildcard} would be +called only once at the time of defining @code{find_files}. + +The @code{foreach} function has no permanent effect on the variable +@var{var}; its value and flavor after the @code{foreach} function call are +the same as they were beforehand. The other values which are taken from +@var{list} are in effect only temporarily, during the execution of +@code{foreach}. The variable @var{var} is a simply-expanded variable +during the execution of @code{foreach}. If @var{var} was undefined +before the @code{foreach} function call, it is undefined after the call. +@xref{Flavors, ,The Two Flavors of Variables}.@refill + +You must take care when using complex variable expressions that result in +variable names because many strange things are valid variable names, but +are probably not what you intended. For example, + +@smallexample +files := $(foreach Esta escrito en espanol!,b c ch,$(find_files)) +@end smallexample + +@noindent +might be useful if the value of @code{find_files} references the variable +whose name is @samp{Esta escrito en espanol!} (es un nombre bastante largo, +no?), but it is more likely to be a mistake. + +@node Call Function, Value Function, Foreach Function, Functions +@section The @code{call} Function +@findex call +@cindex functions, user defined +@cindex user defined functions + +The @code{call} function is unique in that it can be used to create new +parameterized functions. You can write a complex expression as the +value of a variable, then use @code{call} to expand it with different +values. + +The syntax of the @code{call} function is: + +@example +$(call @var{variable},@var{param},@var{param},@dots{}) +@end example + +When @code{make} expands this function, it assigns each @var{param} to +temporary variables @code{$(1)}, @code{$(2)}, etc. The variable +@code{$(0)} will contain @var{variable}. There is no maximum number of +parameter arguments. There is no minimum, either, but it doesn't make +sense to use @code{call} with no parameters. + +Then @var{variable} is expanded as a @code{make} variable in the context +of these temporary assignments. Thus, any reference to @code{$(1)} in +the value of @var{variable} will resolve to the first @var{param} in the +invocation of @code{call}. + +Note that @var{variable} is the @emph{name} of a variable, not a +@emph{reference} to that variable. Therefore you would not normally use +a @samp{$} or parentheses when writing it. (You can, however, use a +variable reference in the name if you want the name not to be a +constant.) + +If @var{variable} is the name of a builtin function, the builtin function +is always invoked (even if a @code{make} variable by that name also +exists). + +The @code{call} function expands the @var{param} arguments before +assigning them to temporary variables. This means that @var{variable} +values containing references to builtin functions that have special +expansion rules, like @code{foreach} or @code{if}, may not work as you +expect. + +Some examples may make this clearer. + +This macro simply reverses its arguments: + +@smallexample +reverse = $(2) $(1) + +foo = $(call reverse,a,b) +@end smallexample + +@noindent +Here @var{foo} will contain @samp{b a}. + +This one is slightly more interesting: it defines a macro to search for +the first instance of a program in @code{PATH}: + +@smallexample +pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH))))) + +LS := $(call pathsearch,ls) +@end smallexample + +@noindent +Now the variable LS contains @code{/bin/ls} or similar. + +The @code{call} function can be nested. Each recursive invocation gets +its own local values for @code{$(1)}, etc.@: that mask the values of +higher-level @code{call}. For example, here is an implementation of a +@dfn{map} function: + +@smallexample +map = $(foreach a,$(2),$(call $(1),$(a))) +@end smallexample + +Now you can @var{map} a function that normally takes only one argument, +such as @code{origin}, to multiple values in one step: + +@smallexample +o = $(call map,origin,o map MAKE) +@end smallexample + +and end up with @var{o} containing something like @samp{file file default}. + +A final caution: be careful when adding whitespace to the arguments to +@code{call}. As with other functions, any whitespace contained in the +second and subsequent arguments is kept; this can cause strange +effects. It's generally safest to remove all extraneous whitespace when +providing parameters to @code{call}. + +@node Value Function, Eval Function, Call Function, Functions +@comment node-name, next, previous, up +@section The @code{value} Function +@findex value +@cindex variables, unexpanded value + +The @code{value} function provides a way for you to use the value of a +variable @emph{without} having it expanded. Please note that this +does not undo expansions which have already occurred; for example if +you create a simply expanded variable its value is expanded during the +definition; in that case the @code{value} function will return the +same result as using the variable directly. + +The syntax of the @code{value} function is: + +@example +$(value @var{variable}) +@end example + +Note that @var{variable} is the @emph{name} of a variable; not a +@emph{reference} to that variable. Therefore you would not normally +use a @samp{$} or parentheses when writing it. (You can, however, use +a variable reference in the name if you want the name not to be a +constant.) + +The result of this function is a string containing the value of +@var{variable}, without any expansion occurring. For example, in this +makefile: + +@example +@group +FOO = $PATH + +all: + @@echo $(FOO) + @@echo $(value FOO) +@end group +@end example + +@noindent +The first output line would be @code{ATH}, since the ``$P'' would be +expanded as a @code{make} variable, while the second output line would +be the current value of your @code{$PATH} environment variable, since +the @code{value} function avoided the expansion. + +The @code{value} function is most often used in conjunction with the +@code{eval} function (@pxref{Eval Function}). + +@node Eval Function, Origin Function, Value Function, Functions +@comment node-name, next, previous, up +@section The @code{eval} Function +@findex eval +@cindex evaluating makefile syntax +@cindex makefile syntax, evaluating + +The @code{eval} function is very special: it allows you to define new +makefile constructs that are not constant; which are the result of +evaluating other variables and functions. The argument to the +@code{eval} function is expanded, then the results of that expansion +are parsed as makefile syntax. The expanded results can define new +@code{make} variables, targets, implicit or explicit rules, etc. + +The result of the @code{eval} function is always the empty string; +thus, it can be placed virtually anywhere in a makefile without +causing syntax errors. + +It's important to realize that the @code{eval} argument is expanded +@emph{twice}; first by the @code{eval} function, then the results of +that expansion are expanded again when they are parsed as makefile +syntax. This means you may need to provide extra levels of escaping +for ``$'' characters when using @code{eval}. The @code{value} +function (@pxref{Value Function}) can sometimes be useful in these +situations, to circumvent unwanted expansions. + +Here is an example of how @code{eval} can be used; this example +combines a number of concepts and other functions. Although it might +seem overly complex to use @code{eval} in this example, rather than +just writing out the rules, consider two things: first, the template +definition (in @code{PROGRAM_template}) could need to be much more +complex than it is here; and second, you might put the complex, +``generic'' part of this example into another makefile, then include +it in all the individual makefiles. Now your individual makefiles are +quite straightforward. + +@example +@group +PROGRAMS = server client + +server_OBJS = server.o server_priv.o server_access.o +server_LIBS = priv protocol + +client_OBJS = client.o client_api.o client_mem.o +client_LIBS = protocol + +# Everything after this is generic + +.PHONY: all +all: $(PROGRAMS) + +define PROGRAM_template = + $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%) + ALL_OBJS += $$($(1)_OBJS) +endef + +$(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog)))) + +$(PROGRAMS): + $(LINK.o) $^ $(LDLIBS) -o $@@ + +clean: + rm -f $(ALL_OBJS) $(PROGRAMS) +@end group +@end example + +@node Origin Function, Flavor Function, Eval Function, Functions +@section The @code{origin} Function +@findex origin +@cindex variables, origin of +@cindex origin of variable + +The @code{origin} function is unlike most other functions in that it does +not operate on the values of variables; it tells you something @emph{about} +a variable. Specifically, it tells you where it came from. + +The syntax of the @code{origin} function is: + +@example +$(origin @var{variable}) +@end example + +Note that @var{variable} is the @emph{name} of a variable to inquire about; +not a @emph{reference} to that variable. Therefore you would not normally +use a @samp{$} or parentheses when writing it. (You can, however, use a +variable reference in the name if you want the name not to be a constant.) + +The result of this function is a string telling you how the variable +@var{variable} was defined: + +@table @samp +@item undefined + +if @var{variable} was never defined. + +@item default + +if @var{variable} has a default definition, as is usual with @code{CC} +and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. +Note that if you have redefined a default variable, the @code{origin} +function will return the origin of the later definition. + +@item environment + +if @var{variable} was inherited from the environment provided to +@code{make}. + +@item environment override + +if @var{variable} was inherited from the environment provided to +@code{make}, and is overriding a setting for @var{variable} in the +makefile as a result of the @w{@samp{-e}} option (@pxref{Options +Summary, ,Summary of Options}).@refill + +@item file + +if @var{variable} was defined in a makefile. + +@item command line + +if @var{variable} was defined on the command line. + +@item override + +if @var{variable} was defined with an @code{override} directive in a +makefile (@pxref{Override Directive, ,The @code{override} Directive}). + +@item automatic + +if @var{variable} is an automatic variable defined for the execution +of the recipe for each rule (@pxref{Automatic Variables}). +@end table + +This information is primarily useful (other than for your curiosity) to +determine if you want to believe the value of a variable. For example, +suppose you have a makefile @file{foo} that includes another makefile +@file{bar}. You want a variable @code{bletch} to be defined in @file{bar} +if you run the command @w{@samp{make -f bar}}, even if the environment contains +a definition of @code{bletch}. However, if @file{foo} defined +@code{bletch} before including @file{bar}, you do not want to override that +definition. This could be done by using an @code{override} directive in +@file{foo}, giving that definition precedence over the later definition in +@file{bar}; unfortunately, the @code{override} directive would also +override any command line definitions. So, @file{bar} could +include:@refill + +@example +@group +ifdef bletch +ifeq "$(origin bletch)" "environment" +bletch = barf, gag, etc. +endif +endif +@end group +@end example + +@noindent +If @code{bletch} has been defined from the environment, this will redefine +it. + +If you want to override a previous definition of @code{bletch} if it came +from the environment, even under @samp{-e}, you could instead write: + +@example +@group +ifneq "$(findstring environment,$(origin bletch))" "" +bletch = barf, gag, etc. +endif +@end group +@end example + +Here the redefinition takes place if @samp{$(origin bletch)} returns either +@samp{environment} or @samp{environment override}. +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@node Flavor Function, Shell Function, Origin Function, Functions +@section The @code{flavor} Function +@findex flavor +@cindex variables, flavor of +@cindex flavor of variable + +The @code{flavor} function is unlike most other functions (and like +@code{origin} function) in that it does not operate on the values of +variables; it tells you something @emph{about} a variable. +Specifically, it tells you the flavor of a variable (@pxref{Flavors, +,The Two Flavors of Variables}). + +The syntax of the @code{flavor} function is: + +@example +$(flavor @var{variable}) +@end example + +Note that @var{variable} is the @emph{name} of a variable to inquire about; +not a @emph{reference} to that variable. Therefore you would not normally +use a @samp{$} or parentheses when writing it. (You can, however, use a +variable reference in the name if you want the name not to be a constant.) + +The result of this function is a string that identifies the flavor of the +variable @var{variable}: + +@table @samp +@item undefined + +if @var{variable} was never defined. + +@item recursive + +if @var{variable} is a recursively expanded variable. + +@item simple + +if @var{variable} is a simply expanded variable. + +@end table + + +@node Shell Function, Make Control Functions, Flavor Function, Functions +@section The @code{shell} Function +@findex shell +@cindex command expansion +@cindex backquotes +@cindex shell command, function for + +The @code{shell} function is unlike any other function other than the +@code{wildcard} function +(@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it +communicates with the world outside of @code{make}. + +The @code{shell} function performs the same function that backquotes +(@samp{`}) perform in most shells: it does @dfn{command expansion}. +This means that it takes as an argument a shell command and evaluates +to the output of the command. The only processing @code{make} does on +the result is to convert each newline (or carriage-return / newline +pair) to a single space. If there is a trailing (carriage-return +and) newline it will simply be removed.@refill + +The commands run by calls to the @code{shell} function are run when the +function calls are expanded (@pxref{Reading Makefiles, , How +@code{make} Reads a Makefile}). Because this function involves +spawning a new shell, you should carefully consider the performance +implications of using the @code{shell} function within recursively +expanded variables vs.@: simply expanded variables (@pxref{Flavors, ,The +Two Flavors of Variables}). + +Here are some examples of the use of the @code{shell} function: + +@example +contents := $(shell cat foo) +@end example + +@noindent +sets @code{contents} to the contents of the file @file{foo}, with a space +(rather than a newline) separating each line. + +@example +files := $(shell echo *.c) +@end example + +@noindent +sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is +using a very strange shell, this has the same result as +@w{@samp{$(wildcard *.c)}} (as long as at least one @samp{.c} file +exists).@refill + +@node Make Control Functions, , Shell Function, Functions +@section Functions That Control Make +@cindex functions, for controlling make +@cindex controlling make + +These functions control the way make runs. Generally, they are used to +provide information to the user of the makefile or to cause make to stop +if some sort of environmental error is detected. + +@table @code +@item $(error @var{text}@dots{}) +@findex error +@cindex error, stopping on +@cindex stopping make +Generates a fatal error where the message is @var{text}. Note that +the error is generated whenever this function is evaluated. So, if +you put it inside a recipe or on the right side of a recursive +variable assignment, it won't be evaluated until later. The +@var{text} will be expanded before the error is generated. + +For example, + +@example +ifdef ERROR1 +$(error error is $(ERROR1)) +endif +@end example + +@noindent +will generate a fatal error during the read of the makefile if the +@code{make} variable @code{ERROR1} is defined. Or, + +@example +ERR = $(error found an error!) + +.PHONY: err +err: ; $(ERR) +@end example + +@noindent +will generate a fatal error while @code{make} is running, if the +@code{err} target is invoked. + +@item $(warning @var{text}@dots{}) +@findex warning +@cindex warnings, printing +@cindex printing user warnings +This function works similarly to the @code{error} function, above, +except that @code{make} doesn't exit. Instead, @var{text} is expanded +and the resulting message is displayed, but processing of the makefile +continues. + +The result of the expansion of this function is the empty string. + +@item $(info @var{text}@dots{}) +@findex info +@cindex printing messages +This function does nothing more than print its (expanded) argument(s) +to standard output. No makefile name or line number is added. The +result of the expansion of this function is the empty string. +@end table + +@node Running, Implicit Rules, Functions, Top +@chapter How to Run @code{make} + +A makefile that says how to recompile a program can be used in more +than one way. The simplest use is to recompile every file that is out +of date. Usually, makefiles are written so that if you run +@code{make} with no arguments, it does just that. + +But you might want to update only some of the files; you might want to use +a different compiler or different compiler options; you might want just to +find out which files are out of date without changing them. + +By giving arguments when you run @code{make}, you can do any of these +things and many others. + +@cindex exit status of make +The exit status of @code{make} is always one of three values: +@table @code +@item 0 +The exit status is zero if @code{make} is successful. +@item 2 +The exit status is two if @code{make} encounters any errors. +It will print messages describing the particular errors. +@item 1 +The exit status is one if you use the @samp{-q} flag and @code{make} +determines that some target is not already up to date. +@xref{Instead of Execution, ,Instead of Executing Recipes}. +@end table + +@menu +* Makefile Arguments:: How to specify which makefile to use. +* Goals:: How to use goal arguments to specify which + parts of the makefile to use. +* Instead of Execution:: How to use mode flags to specify what + kind of thing to do with the recipes + in the makefile other than simply + execute them. +* Avoiding Compilation:: How to avoid recompiling certain files. +* Overriding:: How to override a variable to specify + an alternate compiler and other things. +* Testing:: How to proceed past some errors, to + test compilation. +* Options Summary:: Summary of Options +@end menu + +@node Makefile Arguments, Goals, Running, Running +@section Arguments to Specify the Makefile +@cindex @code{--file} +@cindex @code{--makefile} +@cindex @code{-f} + +The way to specify the name of the makefile is with the @samp{-f} or +@samp{--file} option (@samp{--makefile} also works). For example, +@samp{-f altmake} says to use the file @file{altmake} as the makefile. + +If you use the @samp{-f} flag several times and follow each @samp{-f} +with an argument, all the specified files are used jointly as +makefiles. + +If you do not use the @samp{-f} or @samp{--file} flag, the default is +to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in +that order, and use the first of these three which exists or can be made +(@pxref{Makefiles, ,Writing Makefiles}).@refill + +@node Goals, Instead of Execution, Makefile Arguments, Running +@section Arguments to Specify the Goals +@cindex goal, how to specify + +The @dfn{goals} are the targets that @code{make} should strive ultimately +to update. Other targets are updated as well if they appear as +prerequisites of goals, or prerequisites of prerequisites of goals, etc. + +By default, the goal is the first target in the makefile (not counting +targets that start with a period). Therefore, makefiles are usually +written so that the first target is for compiling the entire program or +programs they describe. If the first rule in the makefile has several +targets, only the first target in the rule becomes the default goal, not +the whole list. You can manage the selection of the default goal from +within your makefile using the @code{.DEFAULT_GOAL} variable +(@pxref{Special Variables, , Other Special Variables}). + +You can also specify a different goal or goals with command line +arguments to @code{make}. Use the name of the goal as an argument. +If you specify several goals, @code{make} processes each of them in +turn, in the order you name them. + +Any target in the makefile may be specified as a goal (unless it +starts with @samp{-} or contains an @samp{=}, in which case it will be +parsed as a switch or variable definition, respectively). Even +targets not in the makefile may be specified, if @code{make} can find +implicit rules that say how to make them. + +@vindex MAKECMDGOALS +@code{Make} will set the special variable @code{MAKECMDGOALS} to the +list of goals you specified on the command line. If no goals were given +on the command line, this variable is empty. Note that this variable +should be used only in special circumstances. + +An example of appropriate use is to avoid including @file{.d} files +during @code{clean} rules (@pxref{Automatic Prerequisites}), so +@code{make} won't create them only to immediately remove them +again:@refill + +@example +@group +sources = foo.c bar.c + +ifneq ($(MAKECMDGOALS),clean) +include $(sources:.c=.d) +endif +@end group +@end example + +One use of specifying a goal is if you want to compile only a part of +the program, or only one of several programs. Specify as a goal each +file that you wish to remake. For example, consider a directory containing +several programs, with a makefile that starts like this: + +@example +.PHONY: all +all: size nm ld ar as +@end example + +If you are working on the program @code{size}, you might want to say +@w{@samp{make size}} so that only the files of that program are recompiled. + +Another use of specifying a goal is to make files that are not normally +made. For example, there may be a file of debugging output, or a +version of the program that is compiled specially for testing, which has +a rule in the makefile but is not a prerequisite of the default goal. + +Another use of specifying a goal is to run the recipe associated with +a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty +Targets, ,Empty Target Files to Record Events}). Many makefiles contain +a phony target named @file{clean} which deletes everything except source +files. Naturally, this is done only if you request it explicitly with +@w{@samp{make clean}}. Following is a list of typical phony and empty +target names. @xref{Standard Targets}, for a detailed list of all the +standard target names which GNU software packages use. + +@table @file +@item all +@cindex @code{all} @r{(standard target)} +Make all the top-level targets the makefile knows about. + +@item clean +@cindex @code{clean} @r{(standard target)} +Delete all files that are normally created by running @code{make}. + +@item mostlyclean +@cindex @code{mostlyclean} @r{(standard target)} +Like @samp{clean}, but may refrain from deleting a few files that people +normally don't want to recompile. For example, the @samp{mostlyclean} +target for GCC does not delete @file{libgcc.a}, because recompiling it +is rarely necessary and takes a lot of time. + +@item distclean +@cindex @code{distclean} @r{(standard target)} +@itemx realclean +@cindex @code{realclean} @r{(standard target)} +@itemx clobber +@cindex @code{clobber} @r{(standard target)} +Any of these targets might be defined to delete @emph{more} files than +@samp{clean} does. For example, this would delete configuration files +or links that you would normally create as preparation for compilation, +even if the makefile itself cannot create these files. + +@item install +@cindex @code{install} @r{(standard target)} +Copy the executable file into a directory that users typically search +for commands; copy any auxiliary files that the executable uses into +the directories where it will look for them. + +@item print +@cindex @code{print} @r{(standard target)} +Print listings of the source files that have changed. + +@item tar +@cindex @code{tar} @r{(standard target)} +Create a tar file of the source files. + +@item shar +@cindex @code{shar} @r{(standard target)} +Create a shell archive (shar file) of the source files. + +@item dist +@cindex @code{dist} @r{(standard target)} +Create a distribution file of the source files. This might +be a tar file, or a shar file, or a compressed version of one of the +above, or even more than one of the above. + +@item TAGS +@cindex @code{TAGS} @r{(standard target)} +Update a tags table for this program. + +@item check +@cindex @code{check} @r{(standard target)} +@itemx test +@cindex @code{test} @r{(standard target)} +Perform self tests on the program this makefile builds. +@end table + +@node Instead of Execution, Avoiding Compilation, Goals, Running +@section Instead of Executing Recipes +@cindex execution, instead of +@cindex recipes, instead of executing + +The makefile tells @code{make} how to tell whether a target is up to date, +and how to update each target. But updating the targets is not always +what you want. Certain options specify other activities for @code{make}. + +@comment Extra blank lines make it print better. +@table @samp +@item -n +@itemx --just-print +@itemx --dry-run +@itemx --recon +@cindex @code{--just-print} +@cindex @code{--dry-run} +@cindex @code{--recon} +@cindex @code{-n} + +``No-op''. The activity is to print what recipe would be used to make +the targets up to date, but not actually execute it. Some recipes are +still executed, even with this flag (@pxref{MAKE Variable, ,How the @code{MAKE} Variable Works}). + +@item -t +@itemx --touch +@cindex @code{--touch} +@cindex touching files +@cindex target, touching +@cindex @code{-t} + +``Touch''. The activity is to mark the targets as up to date without +actually changing them. In other words, @code{make} pretends to compile +the targets but does not really change their contents. + +@item -q +@itemx --question +@cindex @code{--question} +@cindex @code{-q} +@cindex question mode + +``Question''. The activity is to find out silently whether the targets +are up to date already; but execute no recipe in either case. In other +words, neither compilation nor output will occur. + +@item -W @var{file} +@itemx --what-if=@var{file} +@itemx --assume-new=@var{file} +@itemx --new-file=@var{file} +@cindex @code{--what-if} +@cindex @code{-W} +@cindex @code{--assume-new} +@cindex @code{--new-file} +@cindex what if +@cindex files, assuming new + +``What if''. Each @samp{-W} flag is followed by a file name. The given +files' modification times are recorded by @code{make} as being the present +time, although the actual modification times remain the same. +You can use the @samp{-W} flag in conjunction with the @samp{-n} flag +to see what would happen if you were to modify specific files.@refill +@end table + +With the @samp{-n} flag, @code{make} prints the recipe that it would +normally execute but usually does not execute it. + +With the @samp{-t} flag, @code{make} ignores the recipes in the rules +and uses (in effect) the command @code{touch} for each target that needs to +be remade. The @code{touch} command is also printed, unless @samp{-s} or +@code{.SILENT} is used. For speed, @code{make} does not actually invoke +the program @code{touch}. It does the work directly. + +With the @samp{-q} flag, @code{make} prints nothing and executes no +recipes, but the exit status code it returns is zero if and only if the +targets to be considered are already up to date. If the exit status is +one, then some updating needs to be done. If @code{make} encounters an +error, the exit status is two, so you can distinguish an error from a +target that is not up to date. + +It is an error to use more than one of these three flags in the same +invocation of @code{make}. + +@cindex +, and recipe execution +The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect recipe +lines that begin with @samp{+} characters or contain the strings +@samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing +the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} +is run regardless of these options. Other lines in the same rule are +not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or +@samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.) + +@cindex phony targets and recipe execution +The @samp{-t} flag prevents phony targets (@pxref{Phony Targets}) from +being updated, unless there are recipe lines beginning with @samp{+} +or containing @samp{$(MAKE)} or @samp{$@{MAKE@}}. + +The @samp{-W} flag provides two features: + +@itemize @bullet +@item +If you also use the @samp{-n} or @samp{-q} flag, you can see what +@code{make} would do if you were to modify some files. + +@item +Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually +executing recipes, the @samp{-W} flag can direct @code{make} to act as +if some files had been modified, without actually running the recipes +for those files.@refill +@end itemize + +Note that the options @samp{-p} and @samp{-v} allow you to obtain other +information about @code{make} or about the makefiles in use +(@pxref{Options Summary, ,Summary of Options}).@refill + +@node Avoiding Compilation, Overriding, Instead of Execution, Running +@section Avoiding Recompilation of Some Files +@cindex @code{-o} +@cindex @code{--old-file} +@cindex @code{--assume-old} +@cindex files, assuming old +@cindex files, avoiding recompilation of +@cindex recompilation, avoiding + +Sometimes you may have changed a source file but you do not want to +recompile all the files that depend on it. For example, suppose you add +a macro or a declaration to a header file that many other files depend +on. Being conservative, @code{make} assumes that any change in the +header file requires recompilation of all dependent files, but you know +that they do not need to be recompiled and you would rather not waste +the time waiting for them to compile. + +If you anticipate the problem before changing the header file, you can +use the @samp{-t} flag. This flag tells @code{make} not to run the +recipes in the rules, but rather to mark the target up to date by +changing its last-modification date. You would follow this procedure: + +@enumerate +@item +Use the command @samp{make} to recompile the source files that really +need recompilation, ensuring that the object files are up-to-date +before you begin. + +@item +Make the changes in the header files. + +@item +Use the command @samp{make -t} to mark all the object files as +up to date. The next time you run @code{make}, the changes in the +header files will not cause any recompilation. +@end enumerate + +If you have already changed the header file at a time when some files +do need recompilation, it is too late to do this. Instead, you can +use the @w{@samp{-o @var{file}}} flag, which marks a specified file as +``old'' (@pxref{Options Summary, ,Summary of Options}). This means +that the file itself will not be remade, and nothing else will be +remade on its account. Follow this procedure: + +@enumerate +@item +Recompile the source files that need compilation for reasons independent +of the particular header file, with @samp{make -o @var{headerfile}}. +If several header files are involved, use a separate @samp{-o} option +for each header file. + +@item +Touch all the object files with @samp{make -t}. +@end enumerate + +@node Overriding, Testing, Avoiding Compilation, Running +@section Overriding Variables +@cindex overriding variables with arguments +@cindex variables, overriding with arguments +@cindex command line variables +@cindex variables, command line + +An argument that contains @samp{=} specifies the value of a variable: +@samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}. +If you specify a value in this way, all ordinary assignments of the same +variable in the makefile are ignored; we say they have been +@dfn{overridden} by the command line argument. + +The most common way to use this facility is to pass extra flags to +compilers. For example, in a properly written makefile, the variable +@code{CFLAGS} is included in each recipe that runs the C compiler, so a +file @file{foo.c} would be compiled something like this: + +@example +cc -c $(CFLAGS) foo.c +@end example + +Thus, whatever value you set for @code{CFLAGS} affects each compilation +that occurs. The makefile probably specifies the usual value for +@code{CFLAGS}, like this: + +@example +CFLAGS=-g +@end example + +Each time you run @code{make}, you can override this value if you +wish. For example, if you say @samp{make CFLAGS='-g -O'}, each C +compilation will be done with @samp{cc -c -g -O}. (This also +illustrates how you can use quoting in the shell to enclose spaces and +other special characters in the value of a variable when you override +it.) + +The variable @code{CFLAGS} is only one of many standard variables that +exist just so that you can change them this way. @xref{Implicit +Variables, , Variables Used by Implicit Rules}, for a complete list. + +You can also program the makefile to look at additional variables of your +own, giving the user the ability to control other aspects of how the +makefile works by changing the variables. + +When you override a variable with a command line argument, you can +define either a recursively-expanded variable or a simply-expanded +variable. The examples shown above make a recursively-expanded +variable; to make a simply-expanded variable, write @samp{:=} instead +of @samp{=}. But, unless you want to include a variable reference or +function call in the @emph{value} that you specify, it makes no +difference which kind of variable you create. + +There is one way that the makefile can change a variable that you have +overridden. This is to use the @code{override} directive, which is a line +that looks like this: @samp{override @var{variable} = @var{value}} +(@pxref{Override Directive, ,The @code{override} Directive}). + +@node Testing, Options Summary, Overriding, Running +@section Testing the Compilation of a Program +@cindex testing compilation +@cindex compilation, testing + +Normally, when an error happens in executing a shell command, @code{make} +gives up immediately, returning a nonzero status. No further recipes are +executed for any target. The error implies that the goal cannot be +correctly remade, and @code{make} reports this as soon as it knows. + +When you are compiling a program that you have just changed, this is not +what you want. Instead, you would rather that @code{make} try compiling +every file that can be tried, to show you as many compilation errors +as possible. + +@cindex @code{-k} +@cindex @code{--keep-going} +On these occasions, you should use the @samp{-k} or +@samp{--keep-going} flag. This tells @code{make} to continue to +consider the other prerequisites of the pending targets, remaking them +if necessary, before it gives up and returns nonzero status. For +example, after an error in compiling one object file, @samp{make -k} +will continue compiling other object files even though it already +knows that linking them will be impossible. In addition to continuing +after failed shell commands, @samp{make -k} will continue as much as +possible after discovering that it does not know how to make a target +or prerequisite file. This will always cause an error message, but +without @samp{-k}, it is a fatal error (@pxref{Options Summary, +,Summary of Options}).@refill + +The usual behavior of @code{make} assumes that your purpose is to get the +goals up to date; once @code{make} learns that this is impossible, it might +as well report the failure immediately. The @samp{-k} flag says that the +real purpose is to test as much as possible of the changes made in the +program, perhaps to find several independent problems so that you can +correct them all before the next attempt to compile. This is why Emacs' +@kbd{M-x compile} command passes the @samp{-k} flag by default. + +@node Options Summary, , Testing, Running +@section Summary of Options +@cindex options +@cindex flags +@cindex switches + +Here is a table of all the options @code{make} understands: + +@table @samp +@item -b +@cindex @code{-b} +@itemx -m +@cindex @code{-m} +These options are ignored for compatibility with other versions of @code{make}. + +@item -B +@cindex @code{-B} +@itemx --always-make +@cindex @code{--always-make} +Consider all targets out-of-date. GNU @code{make} proceeds to +consider targets and their prerequisites using the normal algorithms; +however, all targets so considered are always remade regardless of the +status of their prerequisites. To avoid infinite recursion, if +@code{MAKE_RESTARTS} (@pxref{Special Variables, , Other Special +Variables}) is set to a number greater than 0 this option is disabled +when considering whether to remake makefiles (@pxref{Remaking +Makefiles, , How Makefiles Are Remade}). + +@item -C @var{dir} +@cindex @code{-C} +@itemx --directory=@var{dir} +@cindex @code{--directory} +Change to directory @var{dir} before reading the makefiles. If multiple +@samp{-C} options are specified, each is interpreted relative to the +previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}. +This is typically used with recursive invocations of @code{make} +(@pxref{Recursion, ,Recursive Use of @code{make}}). + +@item -d +@cindex @code{-d} +@c Extra blank line here makes the table look better. + +Print debugging information in addition to normal processing. The +debugging information says which files are being considered for +remaking, which file-times are being compared and with what results, +which files actually need to be remade, which implicit rules are +considered and which are applied---everything interesting about how +@code{make} decides what to do. The @code{-d} option is equivalent to +@samp{--debug=a} (see below). + +@item --debug[=@var{options}] +@cindex @code{--debug} +@c Extra blank line here makes the table look better. + +Print debugging information in addition to normal processing. Various +levels and types of output can be chosen. With no arguments, print the +``basic'' level of debugging. Possible arguments are below; only the +first character is considered, and values must be comma- or +space-separated. + +@table @code +@item a (@i{all}) +All types of debugging output are enabled. This is equivalent to using +@samp{-d}. + +@item b (@i{basic}) +Basic debugging prints each target that was found to be out-of-date, and +whether the build was successful or not. + +@item v (@i{verbose}) +A level above @samp{basic}; includes messages about which makefiles were +parsed, prerequisites that did not need to be rebuilt, etc. This option +also enables @samp{basic} messages. + +@item i (@i{implicit}) +Prints messages describing the implicit rule searches for each target. +This option also enables @samp{basic} messages. + +@item j (@i{jobs}) +Prints messages giving details on the invocation of specific subcommands. + +@item m (@i{makefile}) +By default, the above messages are not enabled while trying to remake +the makefiles. This option enables messages while rebuilding makefiles, +too. Note that the @samp{all} option does enable this option. This +option also enables @samp{basic} messages. +@end table + +@item -e +@cindex @code{-e} +@itemx --environment-overrides +@cindex @code{--environment-overrides} +Give variables taken from the environment precedence +over variables from makefiles. +@xref{Environment, ,Variables from the Environment}. + +@item --eval=@var{string} +@cindex @code{--eval} +@c Extra blank line here makes the table look better. + +Evaluate @var{string} as makefile syntax. This is a command-line +version of the @code{eval} function (@pxref{Eval Function}). The +evaluation is performed after the default rules and variables have +been defined, but before any makefiles are read. + +@item -f @var{file} +@cindex @code{-f} +@itemx --file=@var{file} +@cindex @code{--file} +@itemx --makefile=@var{file} +@cindex @code{--makefile} +Read the file named @var{file} as a makefile. +@xref{Makefiles, ,Writing Makefiles}. + +@item -h +@cindex @code{-h} +@itemx --help +@cindex @code{--help} +@c Extra blank line here makes the table look better. + +Remind you of the options that @code{make} understands and then exit. + +@item -i +@cindex @code{-i} +@itemx --ignore-errors +@cindex @code{--ignore-errors} +Ignore all errors in recipes executed to remake files. +@xref{Errors, ,Errors in Recipes}. + +@item -I @var{dir} +@cindex @code{-I} +@itemx --include-dir=@var{dir} +@cindex @code{--include-dir} +Specifies a directory @var{dir} to search for included makefiles. +@xref{Include, ,Including Other Makefiles}. If several @samp{-I} +options are used to specify several directories, the directories are +searched in the order specified. + +@item -j [@var{jobs}] +@cindex @code{-j} +@itemx --jobs[=@var{jobs}] +@cindex @code{--jobs} +Specifies the number of recipes (jobs) to run simultaneously. With no +argument, @code{make} runs as many recipes simultaneously as possible. +If there is more than one @samp{-j} option, the last one is effective. +@xref{Parallel, ,Parallel Execution}, for more information on how +recipes are run. Note that this option is ignored on MS-DOS. + +@item -k +@cindex @code{-k} +@itemx --keep-going +@cindex @code{--keep-going} +Continue as much as possible after an error. While the target that +failed, and those that depend on it, cannot be remade, the other +prerequisites of these targets can be processed all the same. +@xref{Testing, ,Testing the Compilation of a Program}. + +@item -l [@var{load}] +@cindex @code{-l} +@itemx --load-average[=@var{load}] +@cindex @code{--load-average} +@itemx --max-load[=@var{load}] +@cindex @code{--max-load} +Specifies that no new recipes should be started if there are other +recipes running and the load average is at least @var{load} (a +floating-point number). With no argument, removes a previous load +limit. @xref{Parallel, ,Parallel Execution}. + +@item -L +@cindex @code{-L} +@itemx --check-symlink-times +@cindex @code{--check-symlink-times} +On systems that support symbolic links, this option causes @code{make} +to consider the timestamps on any symbolic links in addition to the +timestamp on the file referenced by those links. When this option is +provided, the most recent timestamp among the file and the symbolic +links is taken as the modification time for this target file. + +@item -n +@cindex @code{-n} +@itemx --just-print +@cindex @code{--just-print} +@itemx --dry-run +@cindex @code{--dry-run} +@itemx --recon +@cindex @code{--recon} +@c Extra blank line here makes the table look better. + +Print the recipe that would be executed, but do not execute it (except +in certain circumstances). +@xref{Instead of Execution, ,Instead of Executing Recipes}. + +@item -o @var{file} +@cindex @code{-o} +@itemx --old-file=@var{file} +@cindex @code{--old-file} +@itemx --assume-old=@var{file} +@cindex @code{--assume-old} +Do not remake the file @var{file} even if it is older than its +prerequisites, and do not remake anything on account of changes in +@var{file}. Essentially the file is treated as very old and its rules +are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of +Some Files}.@refill + +@item -p +@cindex @code{-p} +@itemx --print-data-base +@cindex @code{--print-data-base} +@cindex data base of @code{make} rules +@cindex predefined rules and variables, printing +Print the data base (rules and variable values) that results from +reading the makefiles; then execute as usual or as otherwise +specified. This also prints the version information given by the +@samp{-v} switch (see below). To print the data base without trying +to remake any files, use @w{@samp{make -qp}}. To print the data base +of predefined rules and variables, use @w{@samp{make -p -f /dev/null}}. +The data base output contains filename and linenumber information for +recipe and variable definitions, so it can be a useful debugging tool +in complex environments. + +@item -q +@cindex @code{-q} +@itemx --question +@cindex @code{--question} +``Question mode''. Do not run any recipes, or print anything; just +return an exit status that is zero if the specified targets are already +up to date, one if any remaking is required, or two if an error is +encountered. @xref{Instead of Execution, ,Instead of Executing +Recipes}.@refill + +@item -r +@cindex @code{-r} +@itemx --no-builtin-rules +@cindex @code{--no-builtin-rules} +Eliminate use of the built-in implicit rules (@pxref{Implicit Rules, +,Using Implicit Rules}). You can still define your own by writing +pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern +Rules}). The @samp{-r} option also clears out the default list of +suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix +Rules}). But you can still define your own suffixes with a rule for +@code{.SUFFIXES}, and then define your own suffix rules. Note that only +@emph{rules} are affected by the @code{-r} option; default variables +remain in effect (@pxref{Implicit Variables, ,Variables Used by Implicit +Rules}); see the @samp{-R} option below. + +@item -R +@cindex @code{-R} +@itemx --no-builtin-variables +@cindex @code{--no-builtin-variables} +Eliminate use of the built-in rule-specific variables (@pxref{Implicit +Variables, ,Variables Used by Implicit Rules}). You can still define +your own, of course. The @samp{-R} option also automatically enables +the @samp{-r} option (see above), since it doesn't make sense to have +implicit rules without any definitions for the variables that they use. + +@item -s +@cindex @code{-s} +@itemx --silent +@cindex @code{--silent} +@itemx --quiet +@cindex @code{--quiet} +@c Extra blank line here makes the table look better. + +Silent operation; do not print the recipes as they are executed. +@xref{Echoing, ,Recipe Echoing}. + +@item -S +@cindex @code{-S} +@itemx --no-keep-going +@cindex @code{--no-keep-going} +@itemx --stop +@cindex @code{--stop} +@c Extra blank line here makes the table look better. + +Cancel the effect of the @samp{-k} option. This is never necessary +except in a recursive @code{make} where @samp{-k} might be inherited +from the top-level @code{make} via @code{MAKEFLAGS} +(@pxref{Recursion, ,Recursive Use of @code{make}}) +or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill + +@item -t +@cindex @code{-t} +@itemx --touch +@cindex @code{--touch} +@c Extra blank line here makes the table look better. + +Touch files (mark them up to date without really changing them) +instead of running their recipes. This is used to pretend that the +recipes were done, in order to fool future invocations of +@code{make}. @xref{Instead of Execution, ,Instead of Executing Recipes}. + +@item -v +@cindex @code{-v} +@itemx --version +@cindex @code{--version} +Print the version of the @code{make} program plus a copyright, a list +of authors, and a notice that there is no warranty; then exit. + +@item -w +@cindex @code{-w} +@itemx --print-directory +@cindex @code{--print-directory} +Print a message containing the working directory both before and after +executing the makefile. This may be useful for tracking down errors +from complicated nests of recursive @code{make} commands. +@xref{Recursion, ,Recursive Use of @code{make}}. (In practice, you +rarely need to specify this option since @samp{make} does it for you; +see @ref{-w Option, ,The @samp{--print-directory} Option}.) + +@itemx --no-print-directory +@cindex @code{--no-print-directory} +Disable printing of the working directory under @code{-w}. +This option is useful when @code{-w} is turned on automatically, +but you do not want to see the extra messages. +@xref{-w Option, ,The @samp{--print-directory} Option}. + +@item -W @var{file} +@cindex @code{-W} +@itemx --what-if=@var{file} +@cindex @code{--what-if} +@itemx --new-file=@var{file} +@cindex @code{--new-file} +@itemx --assume-new=@var{file} +@cindex @code{--assume-new} +Pretend that the target @var{file} has just been modified. When used +with the @samp{-n} flag, this shows you what would happen if you were +to modify that file. Without @samp{-n}, it is almost the same as +running a @code{touch} command on the given file before running +@code{make}, except that the modification time is changed only in the +imagination of @code{make}. +@xref{Instead of Execution, ,Instead of Executing Recipes}. + +@item --warn-undefined-variables +@cindex @code{--warn-undefined-variables} +@cindex variables, warning for undefined +@cindex undefined variables, warning message +Issue a warning message whenever @code{make} sees a reference to an +undefined variable. This can be helpful when you are trying to debug +makefiles which use variables in complex ways. +@end table + +@node Implicit Rules, Archives, Running, Top +@chapter Using Implicit Rules +@cindex implicit rule +@cindex rule, implicit + +Certain standard ways of remaking target files are used very often. For +example, one customary way to make an object file is from a C source file +using the C compiler, @code{cc}. + +@dfn{Implicit rules} tell @code{make} how to use customary techniques so +that you do not have to specify them in detail when you want to use +them. For example, there is an implicit rule for C compilation. File +names determine which implicit rules are run. For example, C +compilation typically takes a @file{.c} file and makes a @file{.o} file. +So @code{make} applies the implicit rule for C compilation when it sees +this combination of file name endings.@refill + +A chain of implicit rules can apply in sequence; for example, @code{make} +will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file. +@iftex +@xref{Chained Rules, ,Chains of Implicit Rules}. +@end iftex + +The built-in implicit rules use several variables in their recipes so +that, by changing the values of the variables, you can change the way the +implicit rule works. For example, the variable @code{CFLAGS} controls the +flags given to the C compiler by the implicit rule for C compilation. +@iftex +@xref{Implicit Variables, ,Variables Used by Implicit Rules}. +@end iftex + +You can define your own implicit rules by writing @dfn{pattern rules}. +@iftex +@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}. +@end iftex + +@dfn{Suffix rules} are a more limited way to define implicit rules. +Pattern rules are more general and clearer, but suffix rules are +retained for compatibility. +@iftex +@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. +@end iftex + +@menu +* Using Implicit:: How to use an existing implicit rule + to get the recipes for updating a file. +* Catalogue of Rules:: A list of built-in implicit rules. +* Implicit Variables:: How to change what predefined rules do. +* Chained Rules:: How to use a chain of implicit rules. +* Pattern Rules:: How to define new implicit rules. +* Last Resort:: How to define recipes for rules which + cannot find any. +* Suffix Rules:: The old-fashioned style of implicit rule. +* Implicit Rule Search:: The precise algorithm for applying + implicit rules. +@end menu + +@node Using Implicit, Catalogue of Rules, Implicit Rules, Implicit Rules +@section Using Implicit Rules +@cindex implicit rule, how to use +@cindex rule, implicit, how to use + +To allow @code{make} to find a customary method for updating a target +file, all you have to do is refrain from specifying recipes yourself. +Either write a rule with no recipe, or don't write a rule at all. +Then @code{make} will figure out which implicit rule to use based on +which kind of source file exists or can be made. + +For example, suppose the makefile looks like this: + +@example +foo : foo.o bar.o + cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) +@end example + +@noindent +Because you mention @file{foo.o} but do not give a rule for it, @code{make} +will automatically look for an implicit rule that tells how to update it. +This happens whether or not the file @file{foo.o} currently exists. + +If an implicit rule is found, it can supply both a recipe and one or +more prerequisites (the source files). You would want to write a rule +for @file{foo.o} with no recipe if you need to specify additional +prerequisites, such as header files, that the implicit rule cannot +supply. + +Each implicit rule has a target pattern and prerequisite patterns. There may +be many implicit rules with the same target pattern. For example, numerous +rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler; +another, from a @samp{.p} file with the Pascal compiler; and so on. The rule +that actually applies is the one whose prerequisites exist or can be made. +So, if you have a file @file{foo.c}, @code{make} will run the C compiler; +otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal +compiler; and so on. + +Of course, when you write the makefile, you know which implicit rule you +want @code{make} to use, and you know it will choose that one because you +know which possible prerequisite files are supposed to exist. +@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}, +for a catalogue of all the predefined implicit rules. + +Above, we said an implicit rule applies if the required prerequisites ``exist +or can be made''. A file ``can be made'' if it is mentioned explicitly in +the makefile as a target or a prerequisite, or if an implicit rule can be +recursively found for how to make it. When an implicit prerequisite is the +result of another implicit rule, we say that @dfn{chaining} is occurring. +@xref{Chained Rules, ,Chains of Implicit Rules}. + +In general, @code{make} searches for an implicit rule for each target, and +for each double-colon rule, that has no recipe. A file that is mentioned +only as a prerequisite is considered a target whose rule specifies nothing, +so implicit rule search happens for it. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the +details of how the search is done. + +Note that explicit prerequisites do not influence implicit rule search. +For example, consider this explicit rule: + +@example +foo.o: foo.p +@end example + +@noindent +The prerequisite on @file{foo.p} does not necessarily mean that +@code{make} will remake @file{foo.o} according to the implicit rule to +make an object file, a @file{.o} file, from a Pascal source file, a +@file{.p} file. For example, if @file{foo.c} also exists, the implicit +rule to make an object file from a C source file is used instead, +because it appears before the Pascal rule in the list of predefined +implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit +Rules}). + +If you do not want an implicit rule to be used for a target that has no +recipe, you can give that target an empty recipe by writing a semicolon +(@pxref{Empty Recipes, ,Defining Empty Recipes}). + +@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules +@section Catalogue of Implicit Rules +@cindex implicit rule, predefined +@cindex rule, implicit, predefined + +Here is a catalogue of predefined implicit rules which are always +available unless the makefile explicitly overrides or cancels them. +@xref{Canceling Rules, ,Canceling Implicit Rules}, for information on +canceling or overriding an implicit rule. The @samp{-r} or +@samp{--no-builtin-rules} option cancels all predefined rules. + +This manual only documents the default rules available on POSIX-based +operating systems. Other operating systems, such as VMS, Windows, +OS/2, etc. may have different sets of default rules. To see the full +list of default rules and variables available in your version of GNU +@code{make}, run @samp{make -p} in a directory with no makefile. + +Not all of these rules will always be defined, even when the @samp{-r} +option is not given. Many of the predefined implicit rules are +implemented in @code{make} as suffix rules, so which ones will be +defined depends on the @dfn{suffix list} (the list of prerequisites of +the special target @code{.SUFFIXES}). The default suffix list is: +@code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc}, +@code{.C}, @code{.cpp}, @code{.p}, @code{.f}, @code{.F}, @code{.m}, +@code{.r}, @code{.y}, @code{.l}, @code{.ym}, @code{.lm}, @code{.s}, +@code{.S}, @code{.mod}, @code{.sym}, @code{.def}, @code{.h}, +@code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo}, @code{.texi}, +@code{.txinfo}, @code{.w}, @code{.ch} @code{.web}, @code{.sh}, +@code{.elc}, @code{.el}. All of the implicit rules described below +whose prerequisites have one of these suffixes are actually suffix +rules. If you modify the suffix list, the only predefined suffix +rules in effect will be those named by one or two of the suffixes that +are on the list you specify; rules whose suffixes fail to be on the +list are disabled. @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}, +for full details on suffix rules. + +@table @asis +@item Compiling C programs +@cindex C, rule to compile +@pindex cc +@pindex gcc +@pindex .o +@pindex .c +@file{@var{n}.o} is made automatically from @file{@var{n}.c} with +a recipe of the form @samp{$(CC) $(CPPFLAGS) $(CFLAGS) -c}.@refill + +@item Compiling C++ programs +@cindex C++, rule to compile +@pindex g++ +@pindex .cc +@pindex .cpp +@pindex .C +@file{@var{n}.o} is made automatically from @file{@var{n}.cc}, +@file{@var{n}.cpp}, or @file{@var{n}.C} with a recipe of the form +@samp{$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c}. We encourage you to use the +suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill + +@item Compiling Pascal programs +@cindex Pascal, rule to compile +@pindex pc +@pindex .p +@file{@var{n}.o} is made automatically from @file{@var{n}.p} +with the recipe @samp{$(PC) $(PFLAGS) -c}.@refill + +@item Compiling Fortran and Ratfor programs +@cindex Fortran, rule to compile +@cindex Ratfor, rule to compile +@pindex f77 +@pindex .f +@pindex .r +@pindex .F +@file{@var{n}.o} is made automatically from @file{@var{n}.r}, +@file{@var{n}.F} or @file{@var{n}.f} by running the +Fortran compiler. The precise recipe used is as follows:@refill + +@table @samp +@item .f +@samp{$(FC) $(FFLAGS) -c}. +@item .F +@samp{$(FC) $(FFLAGS) $(CPPFLAGS) -c}. +@item .r +@samp{$(FC) $(FFLAGS) $(RFLAGS) -c}. +@end table + +@item Preprocessing Fortran and Ratfor programs +@file{@var{n}.f} is made automatically from @file{@var{n}.r} or +@file{@var{n}.F}. This rule runs just the preprocessor to convert a +Ratfor or preprocessable Fortran program into a strict Fortran +program. The precise recipe used is as follows:@refill + +@table @samp +@item .F +@samp{$(FC) $(CPPFLAGS) $(FFLAGS) -F}. +@item .r +@samp{$(FC) $(FFLAGS) $(RFLAGS) -F}. +@end table + +@item Compiling Modula-2 programs +@cindex Modula-2, rule to compile +@pindex m2c +@pindex .sym +@pindex .def +@pindex .mod +@file{@var{n}.sym} is made from @file{@var{n}.def} with a recipe +of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o} +is made from @file{@var{n}.mod}; the form is: +@w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill + +@need 1200 +@item Assembling and preprocessing assembler programs +@cindex assembly, rule to compile +@pindex as +@pindex .s +@file{@var{n}.o} is made automatically from @file{@var{n}.s} by +running the assembler, @code{as}. The precise recipe is +@samp{$(AS) $(ASFLAGS)}.@refill + +@pindex .S +@file{@var{n}.s} is made automatically from @file{@var{n}.S} by +running the C preprocessor, @code{cpp}. The precise recipe is +@w{@samp{$(CPP) $(CPPFLAGS)}}. + +@item Linking a single object file +@cindex linking, predefined rule for +@pindex ld +@pindex .o +@file{@var{n}} is made automatically from @file{@var{n}.o} by running +the linker (usually called @code{ld}) via the C compiler. The precise +recipe used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}. + +This rule does the right thing for a simple program with only one +source file. It will also do the right thing if there are multiple +object files (presumably coming from various other source files), one +of which has a name matching that of the executable file. Thus, + +@example +x: y.o z.o +@end example + +@noindent +when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute: + +@example +@group +cc -c x.c -o x.o +cc -c y.c -o y.o +cc -c z.c -o z.o +cc x.o y.o z.o -o x +rm -f x.o +rm -f y.o +rm -f z.o +@end group +@end example + +@noindent +In more complicated cases, such as when there is no object file whose +name derives from the executable file name, you must write an explicit +recipe for linking. + +Each kind of file automatically made into @samp{.o} object files will +be automatically linked by using the compiler (@samp{$(CC)}, +@samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to +assemble @samp{.s} files) without the @samp{-c} option. This could be +done by using the @samp{.o} object files as intermediates, but it is +faster to do the compiling and linking in one step, so that's how it's +done.@refill + +@item Yacc for C programs +@pindex yacc +@cindex Yacc, rule to run +@pindex .y +@file{@var{n}.c} is made automatically from @file{@var{n}.y} by +running Yacc with the recipe @samp{$(YACC) $(YFLAGS)}. + +@item Lex for C programs +@pindex lex +@cindex Lex, rule to run +@pindex .l +@file{@var{n}.c} is made automatically from @file{@var{n}.l} by +running Lex. The actual recipe is @samp{$(LEX) $(LFLAGS)}. + +@item Lex for Ratfor programs +@file{@var{n}.r} is made automatically from @file{@var{n}.l} by +running Lex. The actual recipe is @samp{$(LEX) $(LFLAGS)}. + +The convention of using the same suffix @samp{.l} for all Lex files +regardless of whether they produce C code or Ratfor code makes it +impossible for @code{make} to determine automatically which of the two +languages you are using in any particular case. If @code{make} is +called upon to remake an object file from a @samp{.l} file, it must +guess which compiler to use. It will guess the C compiler, because +that is more common. If you are using Ratfor, make sure @code{make} +knows this by mentioning @file{@var{n}.r} in the makefile. Or, if you +are using Ratfor exclusively, with no C files, remove @samp{.c} from +the list of implicit rule suffixes with:@refill + +@example +@group +.SUFFIXES: +.SUFFIXES: .o .r .f .l @dots{} +@end group +@end example + +@item Making Lint Libraries from C, Yacc, or Lex programs +@pindex lint +@cindex @code{lint}, rule to run +@pindex .ln +@file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}. +The precise recipe is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}. +The same recipe is used on the C code produced from +@file{@var{n}.y} or @file{@var{n}.l}.@refill + +@item @TeX{} and Web +@cindex @TeX{}, rule to run +@cindex Web, rule to run +@pindex tex +@pindex cweave +@pindex weave +@pindex tangle +@pindex ctangle +@pindex .dvi +@pindex .tex +@pindex .web +@pindex .w +@pindex .ch +@file{@var{n}.dvi} is made from @file{@var{n}.tex} with the recipe +@samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with +@samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if +it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is +made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c} +is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists +or can be made) with @samp{$(CTANGLE)}.@refill + +@item Texinfo and Info +@cindex Texinfo, rule to format +@cindex Info, rule to format +@pindex texi2dvi +@pindex makeinfo +@pindex .texinfo +@pindex .info +@pindex .texi +@pindex .txinfo +@file{@var{n}.dvi} is made from @file{@var{n}.texinfo}, +@file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the recipe +@w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}. @file{@var{n}.info} is made from +@file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with +the recipe @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}. + +@item RCS +@cindex RCS, rule to extract from +@pindex co +@pindex ,v @r{(RCS file extension)} +Any file @file{@var{n}} is extracted if necessary from an RCS file +named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise +recipe used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be +extracted from RCS if it already exists, even if the RCS file is +newer. The rules for RCS are terminal +(@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), +so RCS files cannot be generated from another source; they must +actually exist.@refill + +@item SCCS +@cindex SCCS, rule to extract from +@pindex get +@pindex s. @r{(SCCS file prefix)} +Any file @file{@var{n}} is extracted if necessary from an SCCS file +named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise +recipe used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are +terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), +so SCCS files cannot be generated from another source; they must +actually exist.@refill + +@pindex .sh +For the benefit of SCCS, a file @file{@var{n}} is copied from +@file{@var{n}.sh} and made executable (by everyone). This is for +shell scripts that are checked into SCCS. Since RCS preserves the +execution permission of a file, you do not need to use this feature +with RCS.@refill + +We recommend that you avoid using of SCCS. RCS is widely held to be +superior, and is also free. By choosing free software in place of +comparable (or inferior) proprietary software, you support the free +software movement. +@end table + +Usually, you want to change only the variables listed in the table +above, which are documented in the following section. + +However, the recipes in built-in implicit rules actually use +variables such as @code{COMPILE.c}, @code{LINK.p}, and +@code{PREPROCESS.S}, whose values contain the recipes listed above. + +@code{make} follows the convention that the rule to compile a +@file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}. +Similarly, the rule to produce an executable from a @file{.@var{x}} +file uses @code{LINK.@var{x}}; and the rule to preprocess a +@file{.@var{x}} file uses @code{PREPROCESS.@var{x}}. + +@vindex OUTPUT_OPTION +Every rule that produces an object file uses the variable +@code{OUTPUT_OPTION}. @code{make} defines this variable either to +contain @samp{-o $@@}, or to be empty, depending on a compile-time +option. You need the @samp{-o} option to ensure that the output goes +into the right file when the source file is in a different directory, +as when using @code{VPATH} (@pxref{Directory Search}). However, +compilers on some systems do not accept a @samp{-o} switch for object +files. If you use such a system, and use @code{VPATH}, some +compilations will put their output in the wrong place. +A possible workaround for this problem is to give @code{OUTPUT_OPTION} +the value @w{@samp{; mv $*.o $@@}}. + +@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules +@section Variables Used by Implicit Rules +@cindex flags for compilers + +The recipes in built-in implicit rules make liberal use of certain +predefined variables. You can alter the values of these variables in +the makefile, with arguments to @code{make}, or in the environment to +alter how the implicit rules work without redefining the rules +themselves. You can cancel all variables used by implicit rules with +the @samp{-R} or @samp{--no-builtin-variables} option. + +For example, the recipe used to compile a C source file actually says +@samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables +used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By +redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be +used for all C compilations performed by the implicit rule. By redefining +@samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to +each compilation. @emph{All} implicit rules that do C compilation use +@samp{$(CC)} to get the program name for the compiler and @emph{all} +include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill + +The variables used in implicit rules fall into two classes: those that are +names of programs (like @code{CC}) and those that contain arguments for the +programs (like @code{CFLAGS}). (The ``name of a program'' may also contain +some command arguments, but it must start with an actual executable program +name.) If a variable value contains more than one argument, separate them +with spaces. + +The following tables describe of some of the more commonly-used predefined +variables. This list is not exhaustive, and the default values shown here may +not be what @code{make} selects for your environment. To see the +complete list of predefined variables for your instance of GNU @code{make} you +can run @samp{make -p} in a directory with no makefiles. + +Here is a table of some of the more common variables used as names of +programs in built-in rules: +makefiles. + +@table @code +@item AR +@vindex AR +Archive-maintaining program; default @samp{ar}. +@pindex ar + +@item AS +@vindex AS +Program for compiling assembly files; default @samp{as}. +@pindex as + +@item CC +@vindex CC +Program for compiling C programs; default @samp{cc}. +@pindex cc + +@item CXX +@vindex CXX +Program for compiling C++ programs; default @samp{g++}. +@pindex g++ + +@item CPP +@vindex CPP +Program for running the C preprocessor, with results to standard output; +default @samp{$(CC) -E}. + +@item FC +@vindex FC +Program for compiling or preprocessing Fortran and Ratfor programs; +default @samp{f77}. +@pindex f77 + +@item M2C +@vindex M2C +Program to use to compile Modula-2 source code; default @samp{m2c}. +@pindex m2c + +@item PC +@vindex PC +Program for compiling Pascal programs; default @samp{pc}. +@pindex pc + +@item CO +@vindex CO +Program for extracting a file from RCS; default @samp{co}. +@pindex co + +@item GET +@vindex GET +Program for extracting a file from SCCS; default @samp{get}. +@pindex get + +@item LEX +@vindex LEX +Program to use to turn Lex grammars into source code; default @samp{lex}. +@pindex lex + +@item YACC +@vindex YACC +Program to use to turn Yacc grammars into source code; default @samp{yacc}. +@pindex yacc + +@item LINT +@vindex LINT +Program to use to run lint on source code; default @samp{lint}. +@pindex lint + +@item MAKEINFO +@vindex MAKEINFO +Program to convert a Texinfo source file into an Info file; default +@samp{makeinfo}. +@pindex makeinfo + +@item TEX +@vindex TEX +Program to make @TeX{} @sc{dvi} files from @TeX{} source; +default @samp{tex}. +@pindex tex + +@item TEXI2DVI +@vindex TEXI2DVI +Program to make @TeX{} @sc{dvi} files from Texinfo source; +default @samp{texi2dvi}. +@pindex texi2dvi + +@item WEAVE +@vindex WEAVE +Program to translate Web into @TeX{}; default @samp{weave}. +@pindex weave + +@item CWEAVE +@vindex CWEAVE +Program to translate C Web into @TeX{}; default @samp{cweave}. +@pindex cweave + +@item TANGLE +@vindex TANGLE +Program to translate Web into Pascal; default @samp{tangle}. +@pindex tangle + +@item CTANGLE +@vindex CTANGLE +Program to translate C Web into C; default @samp{ctangle}. +@pindex ctangle + +@item RM +@vindex RM +Command to remove a file; default @samp{rm -f}. +@pindex rm +@end table + +Here is a table of variables whose values are additional arguments for the +programs above. The default values for all of these is the empty +string, unless otherwise noted. + +@table @code +@item ARFLAGS +@vindex ARFLAGS +Flags to give the archive-maintaining program; default @samp{rv}. + +@item ASFLAGS +@vindex ASFLAGS +Extra flags to give to the assembler (when explicitly +invoked on a @samp{.s} or @samp{.S} file). + +@item CFLAGS +@vindex CFLAGS +Extra flags to give to the C compiler. + +@item CXXFLAGS +@vindex CXXFLAGS +Extra flags to give to the C++ compiler. + +@item COFLAGS +@vindex COFLAGS +Extra flags to give to the RCS @code{co} program. + +@item CPPFLAGS +@vindex CPPFLAGS +Extra flags to give to the C preprocessor and programs +that use it (the C and Fortran compilers). + +@item FFLAGS +@vindex FFLAGS +Extra flags to give to the Fortran compiler. + +@item GFLAGS +@vindex GFLAGS +Extra flags to give to the SCCS @code{get} program. + +@item LDFLAGS +@vindex LDFLAGS +Extra flags to give to compilers when they are supposed to invoke the linker, +@samp{ld}. + +@item LFLAGS +@vindex LFLAGS +Extra flags to give to Lex. + +@item YFLAGS +@vindex YFLAGS +Extra flags to give to Yacc. + +@item PFLAGS +@vindex PFLAGS +Extra flags to give to the Pascal compiler. + +@item RFLAGS +@vindex RFLAGS +Extra flags to give to the Fortran compiler for Ratfor programs. + +@item LINTFLAGS +@vindex LINTFLAGS +Extra flags to give to lint. +@end table + +@node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules +@section Chains of Implicit Rules + +@cindex chains of rules +@cindex rule, implicit, chains of +Sometimes a file can be made by a sequence of implicit rules. For example, +a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running +first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}. + +If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no +special searching is required: @code{make} finds that the object file can +be made by C compilation from @file{@var{n}.c}; later on, when considering +how to make @file{@var{n}.c}, the rule for running Yacc is +used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are +updated.@refill + +@cindex intermediate files +@cindex files, intermediate +However, even if @file{@var{n}.c} does not exist and is not mentioned, +@code{make} knows how to envision it as the missing link between +@file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is +called an @dfn{intermediate file}. Once @code{make} has decided to use the +intermediate file, it is entered in the data base as if it had been +mentioned in the makefile, along with the implicit rule that says how to +create it.@refill + +Intermediate files are remade using their rules just like all other +files. But intermediate files are treated differently in two ways. + +The first difference is what happens if the intermediate file does not +exist. If an ordinary file @var{b} does not exist, and @code{make} +considers a target that depends on @var{b}, it invariably creates +@var{b} and then updates the target from @var{b}. But if @var{b} is an +intermediate file, then @code{make} can leave well enough alone. It +won't bother updating @var{b}, or the ultimate target, unless some +prerequisite of @var{b} is newer than that target or there is some other +reason to update that target. + +The second difference is that if @code{make} @emph{does} create @var{b} +in order to update something else, it deletes @var{b} later on after it +is no longer needed. Therefore, an intermediate file which did not +exist before @code{make} also does not exist after @code{make}. +@code{make} reports the deletion to you by printing a @samp{rm -f} +command showing which file it is deleting. + +Ordinarily, a file cannot be intermediate if it is mentioned in the +makefile as a target or prerequisite. However, you can explicitly mark a +file as intermediate by listing it as a prerequisite of the special target +@code{.INTERMEDIATE}. This takes effect even if the file is mentioned +explicitly in some other way. + +@cindex intermediate files, preserving +@cindex preserving intermediate files +@cindex secondary files +You can prevent automatic deletion of an intermediate file by marking it +as a @dfn{secondary} file. To do this, list it as a prerequisite of the +special target @code{.SECONDARY}. When a file is secondary, @code{make} +will not create the file merely because it does not already exist, but +@code{make} does not automatically delete the file. Marking a file as +secondary also marks it as intermediate. + +You can list the target pattern of an implicit rule (such as @samp{%.o}) +as a prerequisite of the special target @code{.PRECIOUS} to preserve +intermediate files made by implicit rules whose target patterns match +that file's name; see @ref{Interrupts}.@refill +@cindex preserving with @code{.PRECIOUS} +@cindex @code{.PRECIOUS} intermediate files + +A chain can involve more than two implicit rules. For example, it is +possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS, +Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are +intermediate files that are deleted at the end.@refill + +No single implicit rule can appear more than once in a chain. This means +that @code{make} will not even consider such a ridiculous thing as making +@file{foo} from @file{foo.o.o} by running the linker twice. This +constraint has the added benefit of preventing any infinite loop in the +search for an implicit rule chain. + +There are some special implicit rules to optimize certain cases that would +otherwise be handled by rule chains. For example, making @file{foo} from +@file{foo.c} could be handled by compiling and linking with separate +chained rules, using @file{foo.o} as an intermediate file. But what +actually happens is that a special rule for this case does the compilation +and linking with a single @code{cc} command. The optimized rule is used in +preference to the step-by-step chain because it comes earlier in the +ordering of rules. + +@node Pattern Rules, Last Resort, Chained Rules, Implicit Rules +@section Defining and Redefining Pattern Rules + +You define an implicit rule by writing a @dfn{pattern rule}. A pattern +rule looks like an ordinary rule, except that its target contains the +character @samp{%} (exactly one of them). The target is considered a +pattern for matching file names; the @samp{%} can match any nonempty +substring, while other characters match only themselves. The prerequisites +likewise use @samp{%} to show how their names relate to the target name. + +Thus, a pattern rule @samp{%.o : %.c} says how to make any file +@file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill + +Note that expansion using @samp{%} in pattern rules occurs +@strong{after} any variable or function expansions, which take place +when the makefile is read. @xref{Using Variables, , How to Use +Variables}, and @ref{Functions, ,Functions for Transforming Text}. + +@menu +* Pattern Intro:: An introduction to pattern rules. +* Pattern Examples:: Examples of pattern rules. +* Automatic Variables:: How to use automatic variables in the + recipes of implicit rules. +* Pattern Match:: How patterns match. +* Match-Anything Rules:: Precautions you should take prior to + defining rules that can match any + target file whatever. +* Canceling Rules:: How to override or cancel built-in rules. +@end menu + +@node Pattern Intro, Pattern Examples, Pattern Rules, Pattern Rules +@subsection Introduction to Pattern Rules +@cindex pattern rule +@cindex rule, pattern + +A pattern rule contains the character @samp{%} (exactly one of them) +in the target; otherwise, it looks exactly like an ordinary rule. The +target is a pattern for matching file names; the @samp{%} matches any +nonempty substring, while other characters match only themselves. +@cindex target pattern, implicit +@cindex @code{%}, in pattern rules + +For example, @samp{%.c} as a pattern matches any file name that ends in +@samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts +with @samp{s.}, ends in @samp{.c} and is at least five characters long. +(There must be at least one character to match the @samp{%}.) The substring +that the @samp{%} matches is called the @dfn{stem}.@refill + +@samp{%} in a prerequisite of a pattern rule stands for the same stem +that was matched by the @samp{%} in the target. In order for the +pattern rule to apply, its target pattern must match the file name +under consideration and all of its prerequisites (after pattern +substitution) must name files that exist or can be made. These files +become prerequisites of the target. +@cindex prerequisite pattern, implicit + +Thus, a rule of the form + +@example +%.o : %.c ; @var{recipe}@dots{} +@end example + +@noindent +specifies how to make a file @file{@var{n}.o}, with another file +@file{@var{n}.c} as its prerequisite, provided that @file{@var{n}.c} +exists or can be made. + +There may also be prerequisites that do not use @samp{%}; such a prerequisite +attaches to every file made by this pattern rule. These unvarying +prerequisites are useful occasionally. + +A pattern rule need not have any prerequisites that contain @samp{%}, or +in fact any prerequisites at all. Such a rule is effectively a general +wildcard. It provides a way to make any file that matches the target +pattern. @xref{Last Resort}. + +More than one pattern rule may match a target. In this case +@code{make} will choose the ``best fit'' rule. @xref{Pattern Match, +,How Patterns Match}. + +@c !!! The end of of this paragraph should be rewritten. --bob +Pattern rules may have more than one target. Unlike normal rules, +this does not act as many different rules with the same prerequisites +and recipe. If a pattern rule has multiple targets, @code{make} knows +that the rule's recipe is responsible for making all of the targets. +The recipe is executed only once to make all the targets. When +searching for a pattern rule to match a target, the target patterns of +a rule other than the one that matches the target in need of a rule +are incidental: @code{make} worries only about giving a recipe and +prerequisites to the file presently in question. However, when this +file's recipe is run, the other targets are marked as having been +updated themselves. +@cindex multiple targets, in pattern rule +@cindex target, multiple in pattern rule + +@node Pattern Examples, Automatic Variables, Pattern Intro, Pattern Rules +@subsection Pattern Rule Examples + +Here are some examples of pattern rules actually predefined in +@code{make}. First, the rule that compiles @samp{.c} files into @samp{.o} +files:@refill + +@example +%.o : %.c + $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@ +@end example + +@noindent +defines a rule that can make any file @file{@var{x}.o} from +@file{@var{x}.c}. The recipe uses the automatic variables @samp{$@@} and +@samp{$<} to substitute the names of the target file and the source file +in each case where the rule applies (@pxref{Automatic Variables}).@refill + +Here is a second built-in rule: + +@example +% :: RCS/%,v + $(CO) $(COFLAGS) $< +@end example + +@noindent +defines a rule that can make any file @file{@var{x}} whatsoever from a +corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since +the target is @samp{%}, this rule will apply to any file whatever, provided +the appropriate prerequisite file exists. The double colon makes the rule +@dfn{terminal}, which means that its prerequisite may not be an intermediate +file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill + +@need 500 +This pattern rule has two targets: + +@example +@group +%.tab.c %.tab.h: %.y + bison -d $< +@end group +@end example + +@noindent +@c The following paragraph is rewritten to avoid overfull hboxes +This tells @code{make} that the recipe @samp{bison -d @var{x}.y} will +make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file +@file{foo} depends on the files @file{parse.tab.o} and @file{scan.o} +and the file @file{scan.o} depends on the file @file{parse.tab.h}, +when @file{parse.y} is changed, the recipe @samp{bison -d parse.y} +will be executed only once, and the prerequisites of both +@file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably +the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c} +and the file @file{scan.o} from @file{scan.c}, while @file{foo} is +linked from @file{parse.tab.o}, @file{scan.o}, and its other +prerequisites, and it will execute happily ever after.)@refill + +@node Automatic Variables, Pattern Match, Pattern Examples, Pattern Rules +@subsection Automatic Variables +@cindex automatic variables +@cindex variables, automatic +@cindex variables, and implicit rule + +Suppose you are writing a pattern rule to compile a @samp{.c} file into a +@samp{.o} file: how do you write the @samp{cc} command so that it operates +on the right source file name? You cannot write the name in the recipe, +because the name is different each time the implicit rule is applied. + +What you do is use a special feature of @code{make}, the @dfn{automatic +variables}. These variables have values computed afresh for each rule that +is executed, based on the target and prerequisites of the rule. In this +example, you would use @samp{$@@} for the object file name and @samp{$<} +for the source file name. + +@cindex automatic variables in prerequisites +@cindex prerequisites, and automatic variables +It's very important that you recognize the limited scope in which +automatic variable values are available: they only have values within +the recipe. In particular, you cannot use them anywhere +within the target list of a rule; they have no value there and will +expand to the empty string. Also, they cannot be accessed directly +within the prerequisite list of a rule. A common mistake is +attempting to use @code{$@@} within the prerequisites list; this will +not work. However, there is a special feature of GNU @code{make}, +secondary expansion (@pxref{Secondary Expansion}), which will allow +automatic variable values to be used in prerequisite lists. + +Here is a table of automatic variables: + +@table @code +@vindex $@@ +@vindex @@ @r{(automatic variable)} +@item $@@ +The file name of the target of the rule. If the target is an archive +member, then @samp{$@@} is the name of the archive file. In a pattern +rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to +Pattern Rules}), @samp{$@@} is the name of whichever target caused the +rule's recipe to be run. + +@vindex $% +@vindex % @r{(automatic variable)} +@item $% +The target member name, when the target is an archive member. +@xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then +@samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is +empty when the target is not an archive member. + +@vindex $< +@vindex < @r{(automatic variable)} +@item $< +The name of the first prerequisite. If the target got its recipe from +an implicit rule, this will be the first prerequisite added by the +implicit rule (@pxref{Implicit Rules}). + +@vindex $? +@vindex ? @r{(automatic variable)} +@item $? +The names of all the prerequisites that are newer than the target, with +spaces between them. For prerequisites which are archive members, only +the named member is used (@pxref{Archives}). +@cindex prerequisites, list of changed +@cindex list of changed prerequisites + +@vindex $^ +@vindex ^ @r{(automatic variable)} +@item $^ +The names of all the prerequisites, with spaces between them. For +prerequisites which are archive members, only the named member is used +(@pxref{Archives}). A target has only one prerequisite on each other file +it depends on, no matter how many times each file is listed as a +prerequisite. So if you list a prerequisite more than once for a target, +the value of @code{$^} contains just one copy of the name. This list +does @strong{not} contain any of the order-only prerequisites; for those +see the @samp{$|} variable, below. +@cindex prerequisites, list of all +@cindex list of all prerequisites + +@vindex $+ +@vindex + @r{(automatic variable)} +@item $+ +This is like @samp{$^}, but prerequisites listed more than once are +duplicated in the order they were listed in the makefile. This is +primarily useful for use in linking commands where it is meaningful to +repeat library file names in a particular order. + +@vindex $| +@vindex | @r{(automatic variable)} +@item $| +The names of all the order-only prerequisites, with spaces between +them. + +@vindex $* +@vindex * @r{(automatic variable)} +@item $* +The stem with which an implicit rule matches (@pxref{Pattern Match, ,How +Patterns Match}). If the target is @file{dir/a.foo.b} and the target +pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is +useful for constructing names of related files.@refill +@cindex stem, variable for + +In a static pattern rule, the stem is part of the file name that matched +the @samp{%} in the target pattern. + +In an explicit rule, there is no stem; so @samp{$*} cannot be determined +in that way. Instead, if the target name ends with a recognized suffix +(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to +the target name minus the suffix. For example, if the target name is +@samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a +suffix. GNU @code{make} does this bizarre thing only for compatibility +with other implementations of @code{make}. You should generally avoid +using @samp{$*} except in implicit rules or static pattern rules.@refill + +If the target name in an explicit rule does not end with a recognized +suffix, @samp{$*} is set to the empty string for that rule. +@end table + +@samp{$?} is useful even in explicit rules when you wish to operate on only +the prerequisites that have changed. For example, suppose that an archive +named @file{lib} is supposed to contain copies of several object files. +This rule copies just the changed object files into the archive: + +@example +@group +lib: foo.o bar.o lose.o win.o + ar r lib $? +@end group +@end example + +Of the variables listed above, four have values that are single file +names, and three have values that are lists of file names. These seven +have variants that get just the file's directory name or just the file +name within the directory. The variant variables' names are formed by +appending @samp{D} or @samp{F}, respectively. These variants are +semi-obsolete in GNU @code{make} since the functions @code{dir} and +@code{notdir} can be used to get a similar effect (@pxref{File Name +Functions, , Functions for File Names}). Note, however, that the +@samp{D} variants all omit the trailing slash which always appears in +the output of the @code{dir} function. Here is a table of the variants: + +@table @samp +@vindex $(@@D) +@vindex @@D @r{(automatic variable)} +@item $(@@D) +The directory part of the file name of the target, with the trailing +slash removed. If the value of @samp{$@@} is @file{dir/foo.o} then +@samp{$(@@D)} is @file{dir}. This value is @file{.} if @samp{$@@} does +not contain a slash. + +@vindex $(@@F) +@vindex @@F @r{(automatic variable)} +@item $(@@F) +The file-within-directory part of the file name of the target. If the +value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is +@file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}. + +@vindex $(*D) +@vindex *D @r{(automatic variable)} +@item $(*D) +@vindex $(*F) +@vindex *F @r{(automatic variable)} +@itemx $(*F) +The directory part and the file-within-directory +part of the stem; @file{dir} and @file{foo} in this example. + +@vindex $(%D) +@vindex %D @r{(automatic variable)} +@item $(%D) +@vindex $(%F) +@vindex %F @r{(automatic variable)} +@itemx $(%F) +The directory part and the file-within-directory part of the target +archive member name. This makes sense only for archive member targets +of the form @file{@var{archive}(@var{member})} and is useful only when +@var{member} may contain a directory name. (@xref{Archive Members, +,Archive Members as Targets}.) + +@vindex $(<D) +@vindex <D @r{(automatic variable)} +@item $(<D) +@vindex $(<F) +@vindex <F @r{(automatic variable)} +@itemx $(<F) +The directory part and the file-within-directory +part of the first prerequisite. + +@vindex $(^D) +@vindex ^D @r{(automatic variable)} +@item $(^D) +@vindex $(^F) +@vindex ^F @r{(automatic variable)} +@itemx $(^F) +Lists of the directory parts and the file-within-directory +parts of all prerequisites. + +@vindex $(+D) +@vindex +D @r{(automatic variable)} +@item $(+D) +@vindex $(+F) +@vindex +F @r{(automatic variable)} +@itemx $(+F) +Lists of the directory parts and the file-within-directory +parts of all prerequisites, including multiple instances of duplicated +prerequisites. + +@vindex $(?D) +@vindex ?D @r{(automatic variable)} +@item $(?D) +@vindex $(?F) +@vindex ?F @r{(automatic variable)} +@itemx $(?F) +Lists of the directory parts and the file-within-directory parts of +all prerequisites that are newer than the target. +@end table + +Note that we use a special stylistic convention when we talk about these +automatic variables; we write ``the value of @samp{$<}'', rather than +@w{``the variable @code{<}''} as we would write for ordinary variables +such as @code{objects} and @code{CFLAGS}. We think this convention +looks more natural in this special case. Please do not assume it has a +deep significance; @samp{$<} refers to the variable named @code{<} just +as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}. +You could just as well use @samp{$(<)} in place of @samp{$<}. + +@node Pattern Match, Match-Anything Rules, Automatic Variables, Pattern Rules +@subsection How Patterns Match + +@cindex stem +A target pattern is composed of a @samp{%} between a prefix and a suffix, +either or both of which may be empty. The pattern matches a file name only +if the file name starts with the prefix and ends with the suffix, without +overlap. The text between the prefix and the suffix is called the +@dfn{stem}. Thus, when the pattern @samp{%.o} matches the file name +@file{test.o}, the stem is @samp{test}. The pattern rule prerequisites are +turned into actual file names by substituting the stem for the character +@samp{%}. Thus, if in the same example one of the prerequisites is written +as @samp{%.c}, it expands to @samp{test.c}.@refill + +When the target pattern does not contain a slash (and it usually does +not), directory names in the file names are removed from the file name +before it is compared with the target prefix and suffix. After the +comparison of the file name to the target pattern, the directory +names, along with the slash that ends them, are added on to the +prerequisite file names generated from the pattern rule's prerequisite +patterns and the file name. The directories are ignored only for the +purpose of finding an implicit rule to use, not in the application of +that rule. Thus, @samp{e%t} matches the file name @file{src/eat}, +with @samp{src/a} as the stem. When prerequisites are turned into file +names, the directories from the stem are added at the front, while the +rest of the stem is substituted for the @samp{%}. The stem +@samp{src/a} with a prerequisite pattern @samp{c%r} gives the file name +@file{src/car}.@refill + +@cindex pattern rules, order of +@cindex order of pattern rules +A pattern rule can be used to build a given file only if there is a +target pattern that matches the file name, @emph{and} all +prerequisites in that rule either exist or can be built. The rules +you write take precedence over those that are built in. Note however, +that a rule whose prerequisites actually exist or are mentioned always +takes priority over a rule with prerequisites that must be made by +chaining other implicit rules. + +@cindex stem, shortest +It is possible that more than one pattern rule will meet these +criteria. In that case, @code{make} will choose the rule with the +shortest stem (that is, the pattern that matches most specifically). +If more than one pattern rule has the shortest stem, @code{make} will +choose the first one found in the makefile. + +This algorithm results in more specific rules being preferred over +more generic ones; for example: + +@example +%.o: %.c + $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@ + +%.o : %.f + $(COMPILE.F) $(OUTPUT_OPTION) $< + +lib/%.o: lib/%.c + $(CC) -fPIC -c $(CFLAGS) $(CPPFLAGS) $< -o $@@ +@end example + +Given these rules and asked to build @file{bar.o} where both +@file{bar.c} and @file{bar.f} exist, @code{make} will choose the first +rule and compile @file{bar.c} into @file{bar.o}. In the same +situation where @file{bar.c} does not exist, then @code{make} will +choose the second rule and compile @file{bar.f} into @file{bar.o}. + +If @code{make} is asked to build @file{lib/bar.o} and both +@file{lib/bar.c} and @file{lib/bar.f} exist, then the third rule will +be chosen since the stem for this rule (@samp{bar}) is shorter than +the stem for the first rule (@samp{lib/bar}). If @file{lib/bar.c} +does not exist then the third rule is not eligible and the second rule +will be used, even though the stem is longer. + +@node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules +@subsection Match-Anything Pattern Rules + +@cindex match-anything rule +@cindex terminal rule +When a pattern rule's target is just @samp{%}, it matches any file name +whatever. We call these rules @dfn{match-anything} rules. They are very +useful, but it can take a lot of time for @code{make} to think about them, +because it must consider every such rule for each file name listed either +as a target or as a prerequisite. + +Suppose the makefile mentions @file{foo.c}. For this target, @code{make} +would have to consider making it by linking an object file @file{foo.c.o}, +or by C compilation-and-linking in one step from @file{foo.c.c}, or by +Pascal compilation-and-linking from @file{foo.c.p}, and many other +possibilities. + +We know these possibilities are ridiculous since @file{foo.c} is a C source +file, not an executable. If @code{make} did consider these possibilities, +it would ultimately reject them, because files such as @file{foo.c.o} and +@file{foo.c.p} would not exist. But these possibilities are so +numerous that @code{make} would run very slowly if it had to consider +them.@refill + +To gain speed, we have put various constraints on the way @code{make} +considers match-anything rules. There are two different constraints that +can be applied, and each time you define a match-anything rule you must +choose one or the other for that rule. + +One choice is to mark the match-anything rule as @dfn{terminal} by defining +it with a double colon. When a rule is terminal, it does not apply unless +its prerequisites actually exist. Prerequisites that could be made with +other implicit rules are not good enough. In other words, no further +chaining is allowed beyond a terminal rule. + +For example, the built-in implicit rules for extracting sources from RCS +and SCCS files are terminal; as a result, if the file @file{foo.c,v} does +not exist, @code{make} will not even consider trying to make it as an +intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}. +RCS and SCCS files are generally ultimate source files, which should not be +remade from any other files; therefore, @code{make} can save time by not +looking for ways to remake them.@refill + +If you do not mark the match-anything rule as terminal, then it is +nonterminal. A nonterminal match-anything rule cannot apply to a file name +that indicates a specific type of data. A file name indicates a specific +type of data if some non-match-anything implicit rule target matches it. + +For example, the file name @file{foo.c} matches the target for the pattern +rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this +rule is actually applicable (which happens only if there is a file +@file{foo.y}), the fact that its target matches is enough to prevent +consideration of any nonterminal match-anything rules for the file +@file{foo.c}. Thus, @code{make} will not even consider trying to make +@file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c}, +@file{foo.c.p}, etc.@refill + +The motivation for this constraint is that nonterminal match-anything +rules are used for making files containing specific types of data (such as +executable files) and a file name with a recognized suffix indicates some +other specific type of data (such as a C source file). + +Special built-in dummy pattern rules are provided solely to recognize +certain file names so that nonterminal match-anything rules will not be +considered. These dummy rules have no prerequisites and no recipes, and +they are ignored for all other purposes. For example, the built-in +implicit rule + +@example +%.p : +@end example + +@noindent +exists to make sure that Pascal source files such as @file{foo.p} match a +specific target pattern and thereby prevent time from being wasted looking +for @file{foo.p.o} or @file{foo.p.c}. + +Dummy pattern rules such as the one for @samp{%.p} are made for every +suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}). + +@node Canceling Rules, , Match-Anything Rules, Pattern Rules +@subsection Canceling Implicit Rules + +You can override a built-in implicit rule (or one you have defined +yourself) by defining a new pattern rule with the same target and +prerequisites, but a different recipe. When the new rule is defined, the +built-in one is replaced. The new rule's position in the sequence of +implicit rules is determined by where you write the new rule. + +You can cancel a built-in implicit rule by defining a pattern rule with the +same target and prerequisites, but no recipe. For example, the following +would cancel the rule that runs the assembler: + +@example +%.o : %.s +@end example + +@node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules +@section Defining Last-Resort Default Rules +@cindex last-resort default rules +@cindex default rules, last-resort + +You can define a last-resort implicit rule by writing a terminal +match-anything pattern rule with no prerequisites (@pxref{Match-Anything +Rules}). This is just like any other pattern rule; the only thing +special about it is that it will match any target. So such a rule's +recipe is used for all targets and prerequisites that have no recipe +of their own and for which no other implicit rule applies. + +For example, when testing a makefile, you might not care if the source +files contain real data, only that they exist. Then you might do this: + +@example +%:: + touch $@@ +@end example + +@noindent +to cause all the source files needed (as prerequisites) to be created +automatically. + +@findex .DEFAULT +You can instead define a recipe to be used for targets for which there +are no rules at all, even ones which don't specify recipes. You do +this by writing a rule for the target @code{.DEFAULT}. Such a rule's +recipe is used for all prerequisites which do not appear as targets in +any explicit rule, and for which no implicit rule applies. Naturally, +there is no @code{.DEFAULT} rule unless you write one. + +If you use @code{.DEFAULT} with no recipe or prerequisites: + +@example +.DEFAULT: +@end example + +@noindent +the recipe previously stored for @code{.DEFAULT} is cleared. Then +@code{make} acts as if you had never defined @code{.DEFAULT} at all. + +If you do not want a target to get the recipe from a match-anything +pattern rule or @code{.DEFAULT}, but you also do not want any recipe +to be run for the target, you can give it an empty recipe +(@pxref{Empty Recipes, ,Defining Empty Recipes}).@refill + +You can use a last-resort rule to override part of another makefile. +@xref{Overriding Makefiles, , Overriding Part of Another Makefile}. + +@node Suffix Rules, Implicit Rule Search, Last Resort, Implicit Rules +@section Old-Fashioned Suffix Rules +@cindex old-fashioned suffix rules +@cindex suffix rule + +@dfn{Suffix rules} are the old-fashioned way of defining implicit rules for +@code{make}. Suffix rules are obsolete because pattern rules are more +general and clearer. They are supported in GNU @code{make} for +compatibility with old makefiles. They come in two kinds: +@dfn{double-suffix} and @dfn{single-suffix}.@refill + +A double-suffix rule is defined by a pair of suffixes: the target suffix +and the source suffix. It matches any file whose name ends with the +target suffix. The corresponding implicit prerequisite is made by +replacing the target suffix with the source suffix in the file name. A +two-suffix rule whose target and source suffixes are @samp{.o} and +@samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}. + +A single-suffix rule is defined by a single suffix, which is the source +suffix. It matches any file name, and the corresponding implicit +prerequisite name is made by appending the source suffix. A single-suffix +rule whose source suffix is @samp{.c} is equivalent to the pattern rule +@samp{% : %.c}. + +Suffix rule definitions are recognized by comparing each rule's target +against a defined list of known suffixes. When @code{make} sees a rule +whose target is a known suffix, this rule is considered a single-suffix +rule. When @code{make} sees a rule whose target is two known suffixes +concatenated, this rule is taken as a double-suffix rule. + +For example, @samp{.c} and @samp{.o} are both on the default list of +known suffixes. Therefore, if you define a rule whose target is +@samp{.c.o}, @code{make} takes it to be a double-suffix rule with source +suffix @samp{.c} and target suffix @samp{.o}. Here is the old-fashioned +way to define the rule for compiling a C source file:@refill + +@example +.c.o: + $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< +@end example + +Suffix rules cannot have any prerequisites of their own. If they have any, +they are treated as normal files with funny names, not as suffix rules. +Thus, the rule: + +@example +.c.o: foo.h + $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< +@end example + +@noindent +tells how to make the file @file{.c.o} from the prerequisite file +@file{foo.h}, and is not at all like the pattern rule: + +@example +%.o: %.c foo.h + $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< +@end example + +@noindent +which tells how to make @samp{.o} files from @samp{.c} files, and makes all +@samp{.o} files using this pattern rule also depend on @file{foo.h}. + +Suffix rules with no recipe are also meaningless. They do not remove +previous rules as do pattern rules with no recipe (@pxref{Canceling +Rules, , Canceling Implicit Rules}). They simply enter the suffix or +pair of suffixes concatenated as a target in the data base.@refill + +@findex .SUFFIXES +The known suffixes are simply the names of the prerequisites of the special +target @code{.SUFFIXES}. You can add your own suffixes by writing a rule +for @code{.SUFFIXES} that adds more prerequisites, as in: + +@example +.SUFFIXES: .hack .win +@end example + +@noindent +which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes. + +If you wish to eliminate the default known suffixes instead of just adding +to them, write a rule for @code{.SUFFIXES} with no prerequisites. By +special dispensation, this eliminates all existing prerequisites of +@code{.SUFFIXES}. You can then write another rule to add the suffixes you +want. For example, + +@example +@group +.SUFFIXES: # @r{Delete the default suffixes} +.SUFFIXES: .c .o .h # @r{Define our suffix list} +@end group +@end example + +The @samp{-r} or @samp{--no-builtin-rules} flag causes the default +list of suffixes to be empty. + +@vindex SUFFIXES +The variable @code{SUFFIXES} is defined to the default list of suffixes +before @code{make} reads any makefiles. You can change the list of suffixes +with a rule for the special target @code{.SUFFIXES}, but that does not alter +this variable. + +@node Implicit Rule Search, , Suffix Rules, Implicit Rules +@section Implicit Rule Search Algorithm +@cindex implicit rule, search algorithm +@cindex search algorithm, implicit rule + +Here is the procedure @code{make} uses for searching for an implicit rule +for a target @var{t}. This procedure is followed for each double-colon +rule with no recipe, for each target of ordinary rules none of which have +a recipe, and for each prerequisite that is not the target of any rule. It +is also followed recursively for prerequisites that come from implicit +rules, in the search for a chain of rules. + +Suffix rules are not mentioned in this algorithm because suffix rules are +converted to equivalent pattern rules once the makefiles have been read in. + +For an archive member target of the form +@samp{@var{archive}(@var{member})}, the following algorithm is run +twice, first using the entire target name @var{t}, and second using +@samp{(@var{member})} as the target @var{t} if the first run found no +rule.@refill + +@enumerate +@item +Split @var{t} into a directory part, called @var{d}, and the rest, +called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then +@var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill + +@item +Make a list of all the pattern rules one of whose targets matches +@var{t} or @var{n}. If the target pattern contains a slash, it is +matched against @var{t}; otherwise, against @var{n}. + +@item +If any rule in that list is @emph{not} a match-anything rule, then +remove all nonterminal match-anything rules from the list. + +@item +Remove from the list all rules with no recipe. + +@item +For each pattern rule in the list: + +@enumerate a +@item +Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n} +matched by the @samp{%} in the target pattern.@refill + +@item +Compute the prerequisite names by substituting @var{s} for @samp{%}; if +the target pattern does not contain a slash, append @var{d} to +the front of each prerequisite name.@refill + +@item +Test whether all the prerequisites exist or ought to exist. (If a +file name is mentioned in the makefile as a target or as an explicit +prerequisite, then we say it ought to exist.) + +If all prerequisites exist or ought to exist, or there are no prerequisites, +then this rule applies. +@end enumerate + +@item +If no pattern rule has been found so far, try harder. +For each pattern rule in the list: + +@enumerate a +@item +If the rule is terminal, ignore it and go on to the next rule. + +@item +Compute the prerequisite names as before. + +@item +Test whether all the prerequisites exist or ought to exist. + +@item +For each prerequisite that does not exist, follow this algorithm +recursively to see if the prerequisite can be made by an implicit +rule. + +@item +If all prerequisites exist, ought to exist, or can be +made by implicit rules, then this rule applies. +@end enumerate + +@item +If no implicit rule applies, the rule for @code{.DEFAULT}, if any, +applies. In that case, give @var{t} the same recipe that +@code{.DEFAULT} has. Otherwise, there is no recipe for @var{t}. +@end enumerate + +Once a rule that applies has been found, for each target pattern of +the rule other than the one that matched @var{t} or @var{n}, the +@samp{%} in the pattern is replaced with @var{s} and the resultant +file name is stored until the recipe to remake the target file @var{t} +is executed. After the recipe is executed, each of these stored file +names are entered into the data base and marked as having been updated +and having the same update status as the file @var{t}. + +When the recipe of a pattern rule is executed for @var{t}, the +automatic variables are set corresponding to the target and +prerequisites. @xref{Automatic Variables}. + +@node Archives, Features, Implicit Rules, Top +@chapter Using @code{make} to Update Archive Files +@cindex archive + +@dfn{Archive files} are files containing named subfiles called +@dfn{members}; they are maintained with the program @code{ar} and their +main use is as subroutine libraries for linking. + +@menu +* Archive Members:: Archive members as targets. +* Archive Update:: The implicit rule for archive member targets. +* Archive Pitfalls:: Dangers to watch out for when using archives. +* Archive Suffix Rules:: You can write a special kind of suffix rule + for updating archives. +@end menu + +@node Archive Members, Archive Update, Archives, Archives +@section Archive Members as Targets +@cindex archive member targets + +An individual member of an archive file can be used as a target or +prerequisite in @code{make}. You specify the member named @var{member} in +archive file @var{archive} as follows: + +@example +@var{archive}(@var{member}) +@end example + +@noindent +This construct is available only in targets and prerequisites, not in +recipes! Most programs that you might use in recipes do not support +this syntax and cannot act directly on archive members. Only +@code{ar} and other programs specifically designed to operate on +archives can do so. Therefore, valid recipes to update an archive +member target probably must use @code{ar}. For example, this rule +says to create a member @file{hack.o} in archive @file{foolib} by +copying the file @file{hack.o}: + +@example +foolib(hack.o) : hack.o + ar cr foolib hack.o +@end example + +In fact, nearly all archive member targets are updated in just this way +and there is an implicit rule to do it for you. @strong{Please note:} The +@samp{c} flag to @code{ar} is required if the archive file does not +already exist. + +To specify several members in the same archive, you can write all the +member names together between the parentheses. For example: + +@example +foolib(hack.o kludge.o) +@end example + +@noindent +is equivalent to: + +@example +foolib(hack.o) foolib(kludge.o) +@end example + +@cindex wildcard, in archive member +You can also use shell-style wildcards in an archive member reference. +@xref{Wildcards, ,Using Wildcard Characters in File Names}. For +example, @w{@samp{foolib(*.o)}} expands to all existing members of the +@file{foolib} archive whose names end in @samp{.o}; perhaps +@samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}. + +@node Archive Update, Archive Pitfalls, Archive Members, Archives +@section Implicit Rule for Archive Member Targets + +Recall that a target that looks like @file{@var{a}(@var{m})} stands for the +member named @var{m} in the archive file @var{a}. + +When @code{make} looks for an implicit rule for such a target, as a special +feature it considers implicit rules that match @file{(@var{m})}, as well as +those that match the actual target @file{@var{a}(@var{m})}. + +This causes one special rule whose target is @file{(%)} to match. This +rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m} +into the archive. For example, it will update the archive member target +@file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the +archive @file{foo.a} as a @emph{member} named @file{bar.o}. + +When this rule is chained with others, the result is very powerful. +Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the +@samp{(} and @samp{)} from being interpreted specially by the shell) in +the presence of a file @file{bar.c} is enough to cause the following +recipe to be run, even without a makefile: + +@example +cc -c bar.c -o bar.o +ar r foo.a bar.o +rm -f bar.o +@end example + +@noindent +Here @code{make} has envisioned the file @file{bar.o} as an intermediate +file. @xref{Chained Rules, ,Chains of Implicit Rules}. + +Implicit rules such as this one are written using the automatic variable +@samp{$%}. @xref{Automatic Variables}. + +An archive member name in an archive cannot contain a directory name, but +it may be useful in a makefile to pretend that it does. If you write an +archive member target @file{foo.a(dir/file.o)}, @code{make} will perform +automatic updating with this recipe: + +@example +ar r foo.a dir/file.o +@end example + +@noindent +which has the effect of copying the file @file{dir/file.o} into a member +named @file{file.o}. In connection with such usage, the automatic variables +@code{%D} and @code{%F} may be useful. + +@menu +* Archive Symbols:: How to update archive symbol directories. +@end menu + +@node Archive Symbols, , Archive Update, Archive Update +@subsection Updating Archive Symbol Directories +@cindex @code{__.SYMDEF} +@cindex updating archive symbol directories +@cindex archive symbol directory updating +@cindex symbol directories, updating archive +@cindex directories, updating archive symbol + +An archive file that is used as a library usually contains a special member +named @file{__.SYMDEF} that contains a directory of the external symbol +names defined by all the other members. After you update any other +members, you need to update @file{__.SYMDEF} so that it will summarize the +other members properly. This is done by running the @code{ranlib} program: + +@example +ranlib @var{archivefile} +@end example + +Normally you would put this command in the rule for the archive file, +and make all the members of the archive file prerequisites of that rule. +For example, + +@example +libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{} + ranlib libfoo.a +@end example + +@noindent +The effect of this is to update archive members @file{x.o}, @file{y.o}, +etc., and then update the symbol directory member @file{__.SYMDEF} by +running @code{ranlib}. The rules for updating the members are not shown +here; most likely you can omit them and use the implicit rule which copies +files into the archive, as described in the preceding section. + +This is not necessary when using the GNU @code{ar} program, which +updates the @file{__.SYMDEF} member automatically. + +@node Archive Pitfalls, Archive Suffix Rules, Archive Update, Archives +@section Dangers When Using Archives +@cindex archive, and parallel execution +@cindex parallel execution, and archive update +@cindex archive, and @code{-j} +@cindex @code{-j}, and archive update + +It is important to be careful when using parallel execution (the +@code{-j} switch; @pxref{Parallel, ,Parallel Execution}) and archives. +If multiple @code{ar} commands run at the same time on the same archive +file, they will not know about each other and can corrupt the file. + +Possibly a future version of @code{make} will provide a mechanism to +circumvent this problem by serializing all recipes that operate on the +same archive file. But for the time being, you must either write your +makefiles to avoid this problem in some other way, or not use @code{-j}. + +@node Archive Suffix Rules, , Archive Pitfalls, Archives +@section Suffix Rules for Archive Files +@cindex suffix rule, for archive +@cindex archive, suffix rule for +@cindex library archive, suffix rule for +@cindex @code{.a} (archives) + +You can write a special kind of suffix rule for dealing with archive +files. @xref{Suffix Rules}, for a full explanation of suffix rules. +Archive suffix rules are obsolete in GNU @code{make}, because pattern +rules for archives are a more general mechanism (@pxref{Archive +Update}). But they are retained for compatibility with other +@code{make}s. + +To write a suffix rule for archives, you simply write a suffix rule +using the target suffix @samp{.a} (the usual suffix for archive files). +For example, here is the old-fashioned suffix rule to update a library +archive from C source files: + +@example +@group +.c.a: + $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o + $(AR) r $@@ $*.o + $(RM) $*.o +@end group +@end example + +@noindent +This works just as if you had written the pattern rule: + +@example +@group +(%.o): %.c + $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o + $(AR) r $@@ $*.o + $(RM) $*.o +@end group +@end example + +In fact, this is just what @code{make} does when it sees a suffix rule +with @samp{.a} as the target suffix. Any double-suffix rule +@w{@samp{.@var{x}.a}} is converted to a pattern rule with the target +pattern @samp{(%.o)} and a prerequisite pattern of @samp{%.@var{x}}. + +Since you might want to use @samp{.a} as the suffix for some other kind +of file, @code{make} also converts archive suffix rules to pattern rules +in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule +@w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):} +@w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill + +@node Features, Missing, Archives, Top +@chapter Features of GNU @code{make} +@cindex features of GNU @code{make} +@cindex portability +@cindex compatibility + +Here is a summary of the features of GNU @code{make}, for comparison +with and credit to other versions of @code{make}. We consider the +features of @code{make} in 4.2 BSD systems as a baseline. If you are +concerned with writing portable makefiles, you should not use the +features of @code{make} listed here, nor the ones in @ref{Missing}. + +Many features come from the version of @code{make} in System V. + +@itemize @bullet +@item +The @code{VPATH} variable and its special meaning. +@xref{Directory Search, , Searching Directories for Prerequisites}. +This feature exists in System V @code{make}, but is undocumented. +It is documented in 4.3 BSD @code{make} (which says it mimics System V's +@code{VPATH} feature).@refill + +@item +Included makefiles. @xref{Include, ,Including Other Makefiles}. +Allowing multiple files to be included with a single directive is a GNU +extension. + +@item +Variables are read from and communicated via the environment. +@xref{Environment, ,Variables from the Environment}. + +@item +Options passed through the variable @code{MAKEFLAGS} to recursive +invocations of @code{make}. +@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. + +@item +The automatic variable @code{$%} is set to the member name +in an archive reference. @xref{Automatic Variables}. + +@item +The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%}, +and @code{$?} have corresponding forms like @code{$(@@F)} and +@code{$(@@D)}. We have generalized this to @code{$^} as an obvious +extension. @xref{Automatic Variables}.@refill + +@item +Substitution variable references. +@xref{Reference, ,Basics of Variable References}. + +@item +The command line options @samp{-b} and @samp{-m}, accepted and +ignored. In System V @code{make}, these options actually do something. + +@item +Execution of recursive commands to run @code{make} via the variable +@code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified. +@xref{Recursion, ,Recursive Use of @code{make}}. + +@item +Support for suffix @samp{.a} in suffix rules. @xref{Archive Suffix +Rules}. This feature is obsolete in GNU @code{make}, because the +general feature of rule chaining (@pxref{Chained Rules, ,Chains of +Implicit Rules}) allows one pattern rule for installing members in an +archive (@pxref{Archive Update}) to be sufficient. + +@item +The arrangement of lines and backslash-newline combinations in +recipes is retained when the recipes are printed, so they appear as +they do in the makefile, except for the stripping of initial +whitespace. +@end itemize + +The following features were inspired by various other versions of +@code{make}. In some cases it is unclear exactly which versions inspired +which others. + +@itemize @bullet +@item +Pattern rules using @samp{%}. +This has been implemented in several versions of @code{make}. +We're not sure who invented it first, but it's been spread around a bit. +@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill + +@item +Rule chaining and implicit intermediate files. +This was implemented by Stu Feldman in his version of @code{make} +for AT&T Eighth Edition Research Unix, and later by Andrew Hume of +AT&T Bell Labs in his @code{mk} program (where he terms it +``transitive closure''). We do not really know if +we got this from either of them or thought it up ourselves at the +same time. @xref{Chained Rules, ,Chains of Implicit Rules}. + +@item +The automatic variable @code{$^} containing a list of all prerequisites +of the current target. We did not invent this, but we have no idea who +did. @xref{Automatic Variables}. The automatic variable +@code{$+} is a simple extension of @code{$^}. + +@item +The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know) +invented by Andrew Hume in @code{mk}. +@xref{Instead of Execution, ,Instead of Executing Recipes}. + +@item +The concept of doing several things at once (parallelism) exists in +many incarnations of @code{make} and similar programs, though not in the +System V or BSD implementations. @xref{Execution, ,Recipe Execution}. + +@item +Modified variable references using pattern substitution come from +SunOS 4. @xref{Reference, ,Basics of Variable References}. +This functionality was provided in GNU @code{make} by the +@code{patsubst} function before the alternate syntax was implemented +for compatibility with SunOS 4. It is not altogether clear who +inspired whom, since GNU @code{make} had @code{patsubst} before SunOS +4 was released.@refill + +@item +The special significance of @samp{+} characters preceding recipe lines +(@pxref{Instead of Execution, ,Instead of Executing Recipes}) is +mandated by @cite{IEEE Standard 1003.2-1992} (POSIX.2). + +@item +The @samp{+=} syntax to append to the value of a variable comes from SunOS +4 @code{make}. @xref{Appending, , Appending More Text to Variables}. + +@item +The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list +multiple members in a single archive file comes from SunOS 4 @code{make}. +@xref{Archive Members}. + +@item +The @code{-include} directive to include makefiles with no error for a +nonexistent file comes from SunOS 4 @code{make}. (But note that SunOS 4 +@code{make} does not allow multiple makefiles to be specified in one +@code{-include} directive.) The same feature appears with the name +@code{sinclude} in SGI @code{make} and perhaps others. +@end itemize + +The remaining features are inventions new in GNU @code{make}: + +@itemize @bullet +@item +Use the @samp{-v} or @samp{--version} option to print version and +copyright information. + +@item +Use the @samp{-h} or @samp{--help} option to summarize the options to +@code{make}. + +@item +Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}. + +@item +Pass command line variable assignments automatically through the +variable @code{MAKE} to recursive @code{make} invocations. +@xref{Recursion, ,Recursive Use of @code{make}}. + +@item +Use the @samp{-C} or @samp{--directory} command option to change +directory. @xref{Options Summary, ,Summary of Options}. + +@item +Make verbatim variable definitions with @code{define}. +@xref{Multi-Line, ,Defining Multi-Line Variables}. + +@item +Declare phony targets with the special target @code{.PHONY}. + +Andrew Hume of AT&T Bell Labs implemented a similar feature with a +different syntax in his @code{mk} program. This seems to be a case of +parallel discovery. @xref{Phony Targets, ,Phony Targets}. + +@item +Manipulate text by calling functions. +@xref{Functions, ,Functions for Transforming Text}. + +@item +Use the @samp{-o} or @samp{--old-file} +option to pretend a file's modification-time is old. +@xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}. + +@item +Conditional execution. + +This feature has been implemented numerous times in various versions +of @code{make}; it seems a natural extension derived from the features +of the C preprocessor and similar macro languages and is not a +revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}. + +@item +Specify a search path for included makefiles. +@xref{Include, ,Including Other Makefiles}. + +@item +Specify extra makefiles to read with an environment variable. +@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}. + +@item +Strip leading sequences of @samp{./} from file names, so that +@file{./@var{file}} and @file{@var{file}} are considered to be the +same file.@refill + +@item +Use a special search method for library prerequisites written in the +form @samp{-l@var{name}}. +@xref{Libraries/Search, ,Directory Search for Link Libraries}. + +@item +Allow suffixes for suffix rules +(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any +characters. In other versions of @code{make}, they must begin with +@samp{.} and not contain any @samp{/} characters. + +@item +Keep track of the current level of @code{make} recursion using the +variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}. + +@item +Provide any goals given on the command line in the variable +@code{MAKECMDGOALS}. @xref{Goals, ,Arguments to Specify the Goals}. + +@item +Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}. + +@item +Provide selective @code{vpath} search. +@xref{Directory Search, ,Searching Directories for Prerequisites}. + +@item +Provide computed variable references. +@xref{Reference, ,Basics of Variable References}. + +@item +Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}. +System V @code{make} has a very, very limited form of this +functionality in that it will check out SCCS files for makefiles. + +@item +Various new built-in implicit rules. +@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}. + +@item +The built-in variable @samp{MAKE_VERSION} gives the version number of +@code{make}. +@vindex MAKE_VERSION +@end itemize + +@node Missing, Makefile Conventions, Features, Top +@chapter Incompatibilities and Missing Features +@cindex incompatibilities +@cindex missing features +@cindex features, missing + +The @code{make} programs in various other systems support a few features +that are not implemented in GNU @code{make}. The POSIX.2 standard +(@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not +require any of these features.@refill + +@itemize @bullet +@item +A target of the form @samp{@var{file}((@var{entry}))} stands for a member +of archive file @var{file}. The member is chosen, not by name, but by +being an object file which defines the linker symbol @var{entry}.@refill + +This feature was not put into GNU @code{make} because of the +nonmodularity of putting knowledge into @code{make} of the internal +format of archive file symbol tables. +@xref{Archive Symbols, ,Updating Archive Symbol Directories}. + +@item +Suffixes (used in suffix rules) that end with the character @samp{~} +have a special meaning to System V @code{make}; +they refer to the SCCS file that corresponds +to the file one would get without the @samp{~}. For example, the +suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from +the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole +series of such suffix rules is required. +@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. + +In GNU @code{make}, this entire series of cases is handled by two +pattern rules for extraction from SCCS, in combination with the +general feature of rule chaining. +@xref{Chained Rules, ,Chains of Implicit Rules}. + +@item +In System V and 4.3 BSD @code{make}, files found by @code{VPATH} +search (@pxref{Directory Search, ,Searching Directories for +Prerequisites}) have their names changed inside recipes. We feel it +is much cleaner to always use automatic variables and thus make this +feature obsolete.@refill + +@item +In some Unix @code{make}s, the automatic variable @code{$*} appearing in +the prerequisites of a rule has the amazingly strange ``feature'' of +expanding to the full name of the @emph{target of that rule}. We cannot +imagine what went on in the minds of Unix @code{make} developers to do +this; it is utterly inconsistent with the normal definition of @code{$*}. +@vindex * @r{(automatic variable), unsupported bizarre usage} + +@item +In some Unix @code{make}s, implicit rule search (@pxref{Implicit +Rules, ,Using Implicit Rules}) is apparently done for @emph{all} +targets, not just those without recipes. This means you can +do:@refill + +@example +@group +foo.o: + cc -c foo.c +@end group +@end example + +@noindent +and Unix @code{make} will intuit that @file{foo.o} depends on +@file{foo.c}.@refill + +We feel that such usage is broken. The prerequisite properties of +@code{make} are well-defined (for GNU @code{make}, at least), +and doing such a thing simply does not fit the model.@refill + +@item +GNU @code{make} does not include any built-in implicit rules for +compiling or preprocessing EFL programs. If we hear of anyone who is +using EFL, we will gladly add them. + +@item +It appears that in SVR4 @code{make}, a suffix rule can be specified +with no recipe, and it is treated as if it had an empty recipe +(@pxref{Empty Recipes}). For example: + +@example +.c.a: +@end example + +@noindent +will override the built-in @file{.c.a} suffix rule. + +We feel that it is cleaner for a rule without a recipe to always simply +add to the prerequisite list for the target. The above example can be +easily rewritten to get the desired behavior in GNU @code{make}: + +@example +.c.a: ; +@end example + +@item +Some versions of @code{make} invoke the shell with the @samp{-e} flag, +except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a +Program}). The @samp{-e} flag tells the shell to exit as soon as any +program it runs returns a nonzero status. We feel it is cleaner to +write each line of the recipe to stand on its own and not require this +special treatment. +@end itemize + +@comment The makefile standards are in a separate file that is also +@comment included by standards.texi. +@include make-stds.texi + +@node Quick Reference, Error Messages, Makefile Conventions, Top +@appendix Quick Reference + +This appendix summarizes the directives, text manipulation functions, +and special variables which GNU @code{make} understands. +@xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules}, +and @ref{Options Summary, ,Summary of Options}, +for other summaries. + +Here is a summary of the directives GNU @code{make} recognizes: + +@table @code +@item define @var{variable} +@itemx define @var{variable} = +@itemx define @var{variable} := +@itemx define @var{variable} += +@itemx define @var{variable} ?= +@itemx endef +Define multi-line variables.@* +@xref{Multi-Line}. + +@item undefine @var{variable} +Undefining variables.@* +@xref{Undefine Directive}. + +@item ifdef @var{variable} +@itemx ifndef @var{variable} +@itemx ifeq (@var{a},@var{b}) +@itemx ifeq "@var{a}" "@var{b}" +@itemx ifeq '@var{a}' '@var{b}' +@itemx ifneq (@var{a},@var{b}) +@itemx ifneq "@var{a}" "@var{b}" +@itemx ifneq '@var{a}' '@var{b}' +@itemx else +@itemx endif +Conditionally evaluate part of the makefile.@* +@xref{Conditionals}. + +@item include @var{file} +@itemx -include @var{file} +@itemx sinclude @var{file} +Include another makefile.@* +@xref{Include, ,Including Other Makefiles}. + +@item override @var{variable-assignment} +Define a variable, overriding any previous definition, even one from +the command line.@* +@xref{Override Directive, ,The @code{override} Directive}. + +@item export +Tell @code{make} to export all variables to child processes by default.@* +@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}. + +@item export @var{variable} +@itemx export @var{variable-assignment} +@itemx unexport @var{variable} +Tell @code{make} whether or not to export a particular variable to child +processes.@* +@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}. + +@item private @var{variable-assignment} +Do not allow this variable assignment to be inherited by prerequisites.@* +@xref{Suppressing Inheritance}. + +@item vpath @var{pattern} @var{path} +Specify a search path for files matching a @samp{%} pattern.@* +@xref{Selective Search, , The @code{vpath} Directive}. + +@item vpath @var{pattern} +Remove all search paths previously specified for @var{pattern}. + +@item vpath +Remove all search paths previously specified in any @code{vpath} +directive. +@end table + +Here is a summary of the built-in functions (@pxref{Functions}): + +@table @code +@item $(subst @var{from},@var{to},@var{text}) +Replace @var{from} with @var{to} in @var{text}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(patsubst @var{pattern},@var{replacement},@var{text}) +Replace words matching @var{pattern} with @var{replacement} in @var{text}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(strip @var{string}) +Remove excess whitespace characters from @var{string}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(findstring @var{find},@var{text}) +Locate @var{find} in @var{text}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(filter @var{pattern}@dots{},@var{text}) +Select words in @var{text} that match one of the @var{pattern} words.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(filter-out @var{pattern}@dots{},@var{text}) +Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(sort @var{list}) +Sort the words in @var{list} lexicographically, removing duplicates.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(word @var{n},@var{text}) +Extract the @var{n}th word (one-origin) of @var{text}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(words @var{text}) +Count the number of words in @var{text}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(wordlist @var{s},@var{e},@var{text}) +Returns the list of words in @var{text} from @var{s} to @var{e}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(firstword @var{names}@dots{}) +Extract the first word of @var{names}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(lastword @var{names}@dots{}) +Extract the last word of @var{names}.@* +@xref{Text Functions, , Functions for String Substitution and Analysis}. + +@item $(dir @var{names}@dots{}) +Extract the directory part of each file name.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(notdir @var{names}@dots{}) +Extract the non-directory part of each file name.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(suffix @var{names}@dots{}) +Extract the suffix (the last @samp{.} and following characters) of each file name.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(basename @var{names}@dots{}) +Extract the base name (name without suffix) of each file name.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(addsuffix @var{suffix},@var{names}@dots{}) +Append @var{suffix} to each word in @var{names}.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(addprefix @var{prefix},@var{names}@dots{}) +Prepend @var{prefix} to each word in @var{names}.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(join @var{list1},@var{list2}) +Join two parallel lists of words.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(wildcard @var{pattern}@dots{}) +Find file names matching a shell file name pattern (@emph{not} a +@samp{%} pattern).@* +@xref{Wildcard Function, ,The Function @code{wildcard}}. + +@item $(realpath @var{names}@dots{}) +For each file name in @var{names}, expand to an absolute name that +does not contain any @code{.}, @code{..}, nor symlinks.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(abspath @var{names}@dots{}) +For each file name in @var{names}, expand to an absolute name that +does not contain any @code{.} or @code{..} components, but preserves +symlinks.@* +@xref{File Name Functions, ,Functions for File Names}. + +@item $(error @var{text}@dots{}) +When this function is evaluated, @code{make} generates a fatal error +with the message @var{text}.@* +@xref{Make Control Functions, ,Functions That Control Make}. + +@item $(warning @var{text}@dots{}) +When this function is evaluated, @code{make} generates a warning with +the message @var{text}.@* +@xref{Make Control Functions, ,Functions That Control Make}. + +@item $(shell @var{command}) +Execute a shell command and return its output.@* +@xref{Shell Function, , The @code{shell} Function}. + +@item $(origin @var{variable}) +Return a string describing how the @code{make} variable @var{variable} was +defined.@* +@xref{Origin Function, , The @code{origin} Function}. + +@item $(flavor @var{variable}) +Return a string describing the flavor of the @code{make} variable +@var{variable}.@* +@xref{Flavor Function, , The @code{flavor} Function}. + +@item $(foreach @var{var},@var{words},@var{text}) +Evaluate @var{text} with @var{var} bound to each word in @var{words}, +and concatenate the results.@* +@xref{Foreach Function, ,The @code{foreach} Function}. + +@item $(if @var{condition},@var{then-part}[,@var{else-part}]) +Evaluate the condition @var{condition}; if it's non-empty substitute +the expansion of the @var{then-part} otherwise substitute the +expansion of the @var{else-part}.@* +@xref{Conditional Functions, ,Functions for Conditionals}. + +@item $(or @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]]) +Evaluate each condition @var{conditionN} one at a time; substitute the +first non-empty expansion. If all expansions are empty, substitute +the empty string.@* +@xref{Conditional Functions, ,Functions for Conditionals}. + +@item $(and @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]]) +Evaluate each condition @var{conditionN} one at a time; if any +expansion results in the empty string substitute the empty string. If +all expansions result in a non-empty string, substitute the expansion +of the last @var{condition}.@* +@xref{Conditional Functions, ,Functions for Conditionals}. + +@item $(call @var{var},@var{param},@dots{}) +Evaluate the variable @var{var} replacing any references to @code{$(1)}, +@code{$(2)} with the first, second, etc.@: @var{param} values.@* +@xref{Call Function, ,The @code{call} Function}. + +@item $(eval @var{text}) +Evaluate @var{text} then read the results as makefile commands. +Expands to the empty string.@* +@xref{Eval Function, ,The @code{eval} Function}. + +@item $(value @var{var}) +Evaluates to the contents of the variable @var{var}, with no expansion +performed on it.@* +@xref{Value Function, ,The @code{value} Function}. +@end table + +Here is a summary of the automatic variables. +@xref{Automatic Variables}, +for full information. + +@table @code +@item $@@ +The file name of the target. + +@item $% +The target member name, when the target is an archive member. + +@item $< +The name of the first prerequisite. + +@item $? +The names of all the prerequisites that are +newer than the target, with spaces between them. +For prerequisites which are archive members, only +the named member is used (@pxref{Archives}). + +@item $^ +@itemx $+ +The names of all the prerequisites, with spaces between them. For +prerequisites which are archive members, only the named member is used +(@pxref{Archives}). The value of @code{$^} omits duplicate +prerequisites, while @code{$+} retains them and preserves their order. + +@item $* +The stem with which an implicit rule matches +(@pxref{Pattern Match, ,How Patterns Match}). + +@item $(@@D) +@itemx $(@@F) +The directory part and the file-within-directory part of @code{$@@}. + +@item $(*D) +@itemx $(*F) +The directory part and the file-within-directory part of @code{$*}. + +@item $(%D) +@itemx $(%F) +The directory part and the file-within-directory part of @code{$%}. + +@item $(<D) +@itemx $(<F) +The directory part and the file-within-directory part of @code{$<}. + +@item $(^D) +@itemx $(^F) +The directory part and the file-within-directory part of @code{$^}. + +@item $(+D) +@itemx $(+F) +The directory part and the file-within-directory part of @code{$+}. + +@item $(?D) +@itemx $(?F) +The directory part and the file-within-directory part of @code{$?}. +@end table + +These variables are used specially by GNU @code{make}: + +@table @code +@item MAKEFILES + +Makefiles to be read on every invocation of @code{make}.@* +@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}. + +@item VPATH + +Directory search path for files not found in the current directory.@* +@xref{General Search, , @code{VPATH} Search Path for All Prerequisites}. + +@item SHELL + +The name of the system default command interpreter, usually @file{/bin/sh}. +You can set @code{SHELL} in the makefile to change the shell used to run +recipes. @xref{Execution, ,Recipe Execution}. The @code{SHELL} +variable is handled specially when importing from and exporting to the +environment. @xref{Choosing the Shell}. + +@item MAKESHELL + +On MS-DOS only, the name of the command interpreter that is to be used +by @code{make}. This value takes precedence over the value of +@code{SHELL}. @xref{Execution, ,MAKESHELL variable}. + +@item MAKE + +The name with which @code{make} was invoked. Using this variable in +recipes has special meaning. @xref{MAKE Variable, ,How the +@code{MAKE} Variable Works}. + +@item MAKELEVEL + +The number of levels of recursion (sub-@code{make}s).@* +@xref{Variables/Recursion}. + +@item MAKEFLAGS + +The flags given to @code{make}. You can set this in the environment or +a makefile to set flags.@* +@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. + +It is @emph{never} appropriate to use @code{MAKEFLAGS} directly in a +recipe line: its contents may not be quoted correctly for use in the +shell. Always allow recursive @code{make}'s to obtain these values +through the environment from its parent. + +@item MAKECMDGOALS + +The targets given to @code{make} on the command line. Setting this +variable has no effect on the operation of @code{make}.@* +@xref{Goals, ,Arguments to Specify the Goals}. + +@item CURDIR + +Set to the pathname of the current working directory (after all +@code{-C} options are processed, if any). Setting this variable has no +effect on the operation of @code{make}.@* +@xref{Recursion, ,Recursive Use of @code{make}}. + +@item SUFFIXES + +The default list of suffixes before @code{make} reads any makefiles. + +@item .LIBPATTERNS +Defines the naming of the libraries @code{make} searches for, and their +order.@* +@xref{Libraries/Search, ,Directory Search for Link Libraries}. +@end table + +@node Error Messages, Complex Makefile, Quick Reference, Top +@comment node-name, next, previous, up +@appendix Errors Generated by Make + +Here is a list of the more common errors you might see generated by +@code{make}, and some information about what they mean and how to fix +them. + +Sometimes @code{make} errors are not fatal, especially in the presence +of a @code{-} prefix on a recipe line, or the @code{-k} command line +option. Errors that are fatal are prefixed with the string +@code{***}. + +Error messages are all either prefixed with the name of the program +(usually @samp{make}), or, if the error is found in a makefile, the name +of the file and linenumber containing the problem. + +In the table below, these common prefixes are left off. + +@table @samp + +@item [@var{foo}] Error @var{NN} +@itemx [@var{foo}] @var{signal description} +These errors are not really @code{make} errors at all. They mean that a +program that @code{make} invoked as part of a recipe returned a +non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets +as failure, or it exited in some other abnormal fashion (with a +signal of some type). @xref{Errors, ,Errors in Recipes}. + +If no @code{***} is attached to the message, then the subprocess failed +but the rule in the makefile was prefixed with the @code{-} special +character, so @code{make} ignored the error. + +@item missing separator. Stop. +@itemx missing separator (did you mean TAB instead of 8 spaces?). Stop. +This means that @code{make} could not understand much of anything +about the makefile line it just read. GNU @code{make} looks for +various separators (@code{:}, @code{=}, recipe prefix characters, +etc.) to indicate what kind of line it's parsing. This message means +it couldn't find a valid one. + +One of the most common reasons for this message is that you (or +perhaps your oh-so-helpful editor, as is the case with many MS-Windows +editors) have attempted to indent your recipe lines with spaces +instead of a tab character. In this case, @code{make} will use the +second form of the error above. Remember that every line in the +recipe must begin with a tab character (unless you set +@code{.RECIPEPREFIX}; @pxref{Special Variables}). Eight spaces do not +count. @xref{Rule Syntax}. + +@item recipe commences before first target. Stop. +@itemx missing rule before recipe. Stop. +This means the first thing in the makefile seems to be part of a +recipe: it begins with a recipe prefix character and doesn't appear to +be a legal @code{make} directive (such as a variable assignment). +Recipes must always be associated with a target. + +The second form is generated if the line has a semicolon as the first +non-whitespace character; @code{make} interprets this to mean you left +out the "target: prerequisite" section of a rule. @xref{Rule Syntax}. + +@item No rule to make target `@var{xxx}'. +@itemx No rule to make target `@var{xxx}', needed by `@var{yyy}'. +This means that @code{make} decided it needed to build a target, but +then couldn't find any instructions in the makefile on how to do that, +either explicit or implicit (including in the default rules database). + +If you want that file to be built, you will need to add a rule to your +makefile describing how that target can be built. Other possible +sources of this problem are typos in the makefile (if that filename is +wrong) or a corrupted source tree (if that file is not supposed to be +built, but rather only a prerequisite). + +@item No targets specified and no makefile found. Stop. +@itemx No targets. Stop. +The former means that you didn't provide any targets to be built on the +command line, and @code{make} couldn't find any makefiles to read in. +The latter means that some makefile was found, but it didn't contain any +default goal and none was given on the command line. GNU @code{make} +has nothing to do in these situations. +@xref{Makefile Arguments, ,Arguments to Specify the Makefile}.@refill + +@item Makefile `@var{xxx}' was not found. +@itemx Included makefile `@var{xxx}' was not found. +A makefile specified on the command line (first form) or included +(second form) was not found. + +@item warning: overriding recipe for target `@var{xxx}' +@itemx warning: ignoring old recipe for target `@var{xxx}' +GNU @code{make} allows only one recipe to be specified per target +(except for double-colon rules). If you give a recipe for a target +which already has been defined to have one, this warning is issued and +the second recipe will overwrite the first. @xref{Multiple Rules, +,Multiple Rules for One Target}. + +@item Circular @var{xxx} <- @var{yyy} dependency dropped. +This means that @code{make} detected a loop in the dependency graph: +after tracing the prerequisite @var{yyy} of target @var{xxx}, and its +prerequisites, etc., one of them depended on @var{xxx} again. + +@item Recursive variable `@var{xxx}' references itself (eventually). Stop. +This means you've defined a normal (recursive) @code{make} variable +@var{xxx} that, when it's expanded, will refer to itself (@var{xxx}). +This is not allowed; either use simply-expanded variables (@code{:=}) or +use the append operator (@code{+=}). @xref{Using Variables, ,How to Use +Variables}. + +@item Unterminated variable reference. Stop. +This means you forgot to provide the proper closing parenthesis +or brace in your variable or function reference. + +@item insufficient arguments to function `@var{xxx}'. Stop. +This means you haven't provided the requisite number of arguments for +this function. See the documentation of the function for a description +of its arguments. @xref{Functions, ,Functions for Transforming Text}. + +@item missing target pattern. Stop. +@itemx multiple target patterns. Stop. +@itemx target pattern contains no `%'. Stop. +@itemx mixed implicit and static pattern rules. Stop. +These are generated for malformed static pattern rules. The first means +there's no pattern in the target section of the rule; the second means +there are multiple patterns in the target section; the third means +the target doesn't contain a pattern character (@code{%}); and the +fourth means that all three parts of the static pattern rule contain +pattern characters (@code{%})--only the first two parts should. +@xref{Static Usage, ,Syntax of Static Pattern Rules}. + +@item warning: -jN forced in submake: disabling jobserver mode. +This warning and the next are generated if @code{make} detects error +conditions related to parallel processing on systems where +sub-@code{make}s can communicate (@pxref{Options/Recursion, +,Communicating Options to a Sub-@code{make}}). This warning is +generated if a recursive invocation of a @code{make} process is forced +to have @samp{-j@var{N}} in its argument list (where @var{N} is greater +than one). This could happen, for example, if you set the @code{MAKE} +environment variable to @samp{make -j2}. In this case, the +sub-@code{make} doesn't communicate with other @code{make} processes and +will simply pretend it has two jobs of its own. + +@item warning: jobserver unavailable: using -j1. Add `+' to parent make rule. +In order for @code{make} processes to communicate, the parent will pass +information to the child. Since this could result in problems if the +child process isn't actually a @code{make}, the parent will only do this +if it thinks the child is a @code{make}. The parent uses the normal +algorithms to determine this (@pxref{MAKE Variable, ,How the @code{MAKE} +Variable Works}). If the makefile is constructed such that the parent +doesn't know the child is a @code{make} process, then the child will +receive only part of the information necessary. In this case, the child +will generate this warning message and proceed with its build in a +sequential manner. + +@end table + +@node Complex Makefile, GNU Free Documentation License, Error Messages, Top +@appendix Complex Makefile Example + +Here is the makefile for the GNU @code{tar} program. This is a +moderately complex makefile. + +Because it is the first target, the default goal is @samp{all}. An +interesting feature of this makefile is that @file{testpad.h} is a +source file automatically created by the @code{testpad} program, +itself compiled from @file{testpad.c}. + +If you type @samp{make} or @samp{make all}, then @code{make} creates +the @file{tar} executable, the @file{rmt} daemon that provides +remote tape access, and the @file{tar.info} Info file. + +If you type @samp{make install}, then @code{make} not only creates +@file{tar}, @file{rmt}, and @file{tar.info}, but also installs +them. + +If you type @samp{make clean}, then @code{make} removes the @samp{.o} +files, and the @file{tar}, @file{rmt}, @file{testpad}, +@file{testpad.h}, and @file{core} files. + +If you type @samp{make distclean}, then @code{make} not only removes +the same files as does @samp{make clean} but also the +@file{TAGS}, @file{Makefile}, and @file{config.status} files. +(Although it is not evident, this makefile (and +@file{config.status}) is generated by the user with the +@code{configure} program, which is provided in the @code{tar} +distribution, but is not shown here.) + +If you type @samp{make realclean}, then @code{make} removes the same +files as does @samp{make distclean} and also removes the Info files +generated from @file{tar.texinfo}. + +In addition, there are targets @code{shar} and @code{dist} that create +distribution kits. + +@example +@group +# Generated automatically from Makefile.in by configure. +# Un*x Makefile for GNU tar program. +# Copyright (C) 1991 Free Software Foundation, Inc. +@end group + +@group +# This program is free software; you can redistribute +# it and/or modify it under the terms of the GNU +# General Public License @dots{} +@dots{} +@dots{} +@end group + +SHELL = /bin/sh + +#### Start of system configuration section. #### + +srcdir = . + +@group +# If you use gcc, you should either run the +# fixincludes script that comes with it or else use +# gcc with the -traditional option. Otherwise ioctl +# calls will be compiled incorrectly on some systems. +CC = gcc -O +YACC = bison -y +INSTALL = /usr/local/bin/install -c +INSTALLDATA = /usr/local/bin/install -c -m 644 +@end group + +# Things you might add to DEFS: +# -DSTDC_HEADERS If you have ANSI C headers and +# libraries. +# -DPOSIX If you have POSIX.1 headers and +# libraries. +# -DBSD42 If you have sys/dir.h (unless +# you use -DPOSIX), sys/file.h, +# and st_blocks in `struct stat'. +# -DUSG If you have System V/ANSI C +# string and memory functions +# and headers, sys/sysmacros.h, +# fcntl.h, getcwd, no valloc, +# and ndir.h (unless +# you use -DDIRENT). +# -DNO_MEMORY_H If USG or STDC_HEADERS but do not +# include memory.h. +# -DDIRENT If USG and you have dirent.h +# instead of ndir.h. +# -DSIGTYPE=int If your signal handlers +# return int, not void. +# -DNO_MTIO If you lack sys/mtio.h +# (magtape ioctls). +# -DNO_REMOTE If you do not have a remote shell +# or rexec. +# -DUSE_REXEC To use rexec for remote tape +# operations instead of +# forking rsh or remsh. +# -DVPRINTF_MISSING If you lack vprintf function +# (but have _doprnt). +# -DDOPRNT_MISSING If you lack _doprnt function. +# Also need to define +# -DVPRINTF_MISSING. +# -DFTIME_MISSING If you lack ftime system call. +# -DSTRSTR_MISSING If you lack strstr function. +# -DVALLOC_MISSING If you lack valloc function. +# -DMKDIR_MISSING If you lack mkdir and +# rmdir system calls. +# -DRENAME_MISSING If you lack rename system call. +# -DFTRUNCATE_MISSING If you lack ftruncate +# system call. +# -DV7 On Version 7 Unix (not +# tested in a long time). +# -DEMUL_OPEN3 If you lack a 3-argument version +# of open, and want to emulate it +# with system calls you do have. +# -DNO_OPEN3 If you lack the 3-argument open +# and want to disable the tar -k +# option instead of emulating open. +# -DXENIX If you have sys/inode.h +# and need it 94 to be included. + +DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \ + -DVPRINTF_MISSING -DBSD42 +# Set this to rtapelib.o unless you defined NO_REMOTE, +# in which case make it empty. +RTAPELIB = rtapelib.o +LIBS = +DEF_AR_FILE = /dev/rmt8 +DEFBLOCKING = 20 + +@group +CDEBUG = -g +CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \ + -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \ + -DDEFBLOCKING=$(DEFBLOCKING) +LDFLAGS = -g +@end group + +@group +prefix = /usr/local +# Prefix for each installed program, +# normally empty or `g'. +binprefix = + +# The directory to install tar in. +bindir = $(prefix)/bin + +# The directory to install the info files in. +infodir = $(prefix)/info +@end group + +#### End of system configuration section. #### + +@group +SRCS_C = tar.c create.c extract.c buffer.c \ + getoldopt.c update.c gnu.c mangle.c \ + version.c list.c names.c diffarch.c \ + port.c wildmat.c getopt.c getopt1.c \ + regex.c +SRCS_Y = getdate.y +SRCS = $(SRCS_C) $(SRCS_Y) +OBJS = $(SRCS_C:.c=.o) $(SRCS_Y:.y=.o) $(RTAPELIB) +@end group +@group +AUX = README COPYING ChangeLog Makefile.in \ + makefile.pc configure configure.in \ + tar.texinfo tar.info* texinfo.tex \ + tar.h port.h open3.h getopt.h regex.h \ + rmt.h rmt.c rtapelib.c alloca.c \ + msd_dir.h msd_dir.c tcexparg.c \ + level-0 level-1 backup-specs testpad.c +@end group + +.PHONY: all +all: tar rmt tar.info + +@group +tar: $(OBJS) + $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS) +@end group + +@group +rmt: rmt.c + $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c +@end group + +@group +tar.info: tar.texinfo + makeinfo tar.texinfo +@end group + +@group +.PHONY: install +install: all + $(INSTALL) tar $(bindir)/$(binprefix)tar + -test ! -f rmt || $(INSTALL) rmt /etc/rmt + $(INSTALLDATA) $(srcdir)/tar.info* $(infodir) +@end group + +@group +$(OBJS): tar.h port.h testpad.h +regex.o buffer.o tar.o: regex.h +# getdate.y has 8 shift/reduce conflicts. +@end group + +@group +testpad.h: testpad + ./testpad +@end group + +@group +testpad: testpad.o + $(CC) -o $@@ testpad.o +@end group + +@group +TAGS: $(SRCS) + etags $(SRCS) +@end group + +@group +.PHONY: clean +clean: + rm -f *.o tar rmt testpad testpad.h core +@end group + +@group +.PHONY: distclean +distclean: clean + rm -f TAGS Makefile config.status +@end group + +@group +.PHONY: realclean +realclean: distclean + rm -f tar.info* +@end group + +@group +.PHONY: shar +shar: $(SRCS) $(AUX) + shar $(SRCS) $(AUX) | compress \ + > tar-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ + -e q + version.c`.shar.Z +@end group + +@group +.PHONY: dist +dist: $(SRCS) $(AUX) + echo tar-`sed \ + -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ + -e q + version.c` > .fname + -rm -rf `cat .fname` + mkdir `cat .fname` + ln $(SRCS) $(AUX) `cat .fname` + tar chZf `cat .fname`.tar.Z `cat .fname` + -rm -rf `cat .fname` .fname +@end group + +@group +tar.zoo: $(SRCS) $(AUX) + -rm -rf tmp.dir + -mkdir tmp.dir + -rm tar.zoo + for X in $(SRCS) $(AUX) ; do \ + echo $$X ; \ + sed 's/$$/^M/' $$X \ + > tmp.dir/$$X ; done + cd tmp.dir ; zoo aM ../tar.zoo * + -rm -rf tmp.dir +@end group +@end example + +@node GNU Free Documentation License, Concept Index, Complex Makefile, Top +@appendixsec GNU Free Documentation License +@cindex FDL, GNU Free Documentation License +@include fdl.texi + +@node Concept Index, Name Index, GNU Free Documentation License, Top +@unnumbered Index of Concepts + +@printindex cp + +@node Name Index, , Concept Index, Top +@unnumbered Index of Functions, Variables, & Directives + +@printindex fn + +@bye diff --git a/doc/stamp-vti b/doc/stamp-vti new file mode 100644 index 0000000..aac448b --- /dev/null +++ b/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 19 July 2010 +@set UPDATED-MONTH July 2010 +@set EDITION 3.82 +@set VERSION 3.82 diff --git a/doc/version.texi b/doc/version.texi new file mode 100644 index 0000000..aac448b --- /dev/null +++ b/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 19 July 2010 +@set UPDATED-MONTH July 2010 +@set EDITION 3.82 +@set VERSION 3.82 |