@(#)make_std.txt	1.10	94/06/24 SMI
#
# Copyright 1994 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#

		    Makefile Standards and Guidelines
		    =================================

Introduction
============

	The following standards and guidelines were produced in an effort
to meet a number of build design goals for SunOS 5.x.  

	The design goals should help you form a framework for understanding
and remembering the guidelines.  If you do not have the time to study the
design goals, then jump down to the guidelines and follow them, using the
list of standard macros as a reference or glossary.  Many of your questions
may be answered by inferring what you can from Glenn Skinner's sample
command Makefile at the end of this document.


Build Design Goals
==================

Incremental install targets:

	"smart" incremental install targets, sensitive to the modification
	dates of installed objects and their sources.

Incremental builds:

	"fast" incremental builds by retaining intermediate files, repre-
	senting intermediate dependencies in targets and rules, and 
	avoiding the clobbering of early build files by later ones.	

Host architecture independence:

	a closed system of source and tools designed to avoid corrupting
	the build machine.

	support for concurrent work on more than one release on one host.

Suitably global flexibility:

	a hierarchy of centralized "include" makefiles defining standard
	macros, rules, and targets for their areas of the source tree.

	great reliance upon central rules and macro names defined in the
	make.rules file (in the /usr/share/lib/make directory).

Configurability:

	use of standard macro names defined in the shell environment.

	opportunity to configure local builds by overriding macro values
	on the command line rather than editing makefiles.

AT&T similarity:

	reasonably close adherence to the Sun and AT&T makefile agreement.


Goal Implementation
===================

	Let us examine some of the implementation details which correspond
to each of the goals.  A library example will be used.  The details in the
example have been taken from a wide variety of makefiles just for illus-
tration.  You should not expect to find nor write all of the workings of
the example in one makefile.  A command makefile example occurs at the end
of these guidelines.


Incremental install targets
---------------------------

	Incremental install targets list the installed objects as
dependencies.  If an incremental install target is up-to-date and
you try rebuilding it, *nothing* happens: dependencies get checked,
but no installation occurs.

	The typical incremental install target depends on the "all"
target and a list of target objects in target directories specified
in terms of ROOT.  Each installed object depends on a local object
in the source that can be built using the "all" target.
	
	Suppose LIBRARY is "libexample.a" and ROOT is /proto.
In this fictional example, if the installed object is to be
/proto/usr/lib/libexample.a, the install target would be:

install: all $(ROOTLIBRARY)

where ROOTLIBRARY is $(ROOTLIBDIR)/$(LIBRARY), fitting this pattern-
matching rule:

$(ROOTLIBDIR)/%: %
	$(INS.file)

The pattern '%' matches the $(LIBRARY) built by the "all" target and
having the value libexample.a.

The dependency relationship this defines ensures that the installation
will occur *only* if the target library is out-of-date with respect to
the locally built library (or missing).  In the bigger build picture,
other objects dependent upon the library might avoid being rebuilt
when an unnecessary library installation has been avoided.  This is
what is meant by "incremental" installation.  Imagine the benefit we
get from avoiding an unnecessary installation of stdio.h; a large
amount of command rebuilding might be avoided.


	In practice, the above model can be complicated by a few factors:
ROOTLIBRARY is permitted to be a list of libraries, ROOTLIBS, and the local
object(s) '%' can be stored in an architecture-specific or machine-specific
directory, MACH, when there are some specific sources to justify it.
Furthermore, AT&T put profiled libraries in subdirectories named "libp,"
creating a special case.  And, we have dynamic libraries.  Consequently,
the example becomes:

LIBS=		$(LIBRARY)
MACHLIBS=	$(LIBS:%=$(MACH)/%)
PLIB=		libp/$(LIBRARY)
DYNLIB=		$(LIBRARY:.a=.so$(VERS))
MACHPLIB=	$(MACH)/$(PLIB)
ROOTLIBDIR=	$(ROOT)/usr/lib
ROOTLIBS=	$(LIBS:%=$(ROOTLIBDIR)/%)
ROOTPLIB=	$(ROOTLIBDIR)/$(PLIB)

# install rules
$(ROOTLIBDIR)/%: $(MACH)/%
	$(INS.file)

$(ROOTLIBDIR)/libp/%: $(MACH)/libp/%
	$(INS.file)

install: all $(ROOTLIBS) $(ROOTPLIB)


	(This example assumes the ROOT library directories are in place.)

	A macro, such as ROOTLIBS, representing a list of installed
objects, fits a pattern-matching rule and thereby generates a list of
dependencies which fit the right-hand side of the rule.  These dependencies
are predictable enough to be represented in another macro, such as MACHLIBS
(or LIBS, if the source is machine independent).  That macro is used as a
target to build the dependencies of the "install" target.  Being a list, it
forms a list of targets with further respective dependencies.  The list in
this implementation supplants the for-loop we have previously associated
with "install" targets.  A for-loop is indicative of a non-incremental
installation quite capable of triggering unnecessary secondary rebuilding;
as such, it is to be avoided.

	The "all" dependency has been added to the install target for
two reasons.  First, the pattern-matching install rules fail to match
in the event that the object to be installed has not yet been built, as
would be the case, for example, if someone ran "make install" right
after a "make clobber."  Second, the "all" dependency forces the local
targets to be up-to-date before the objects can be installed.  Previously,
mere existence was enough to satisfy a pattern-matching rule, sometimes
causing out-of-date objects to be installed when they were newer than
their old install targets.


Incremental Builds
------------------

	Incremental builds trade disk space for speed by retaining nearly
all intermediate files from the build process.  This is most noticeable
with libraries built from regular objects, profiled, objects, PIC objects,
or debug objects.  The aim is to segregate these objects to prevent the
building of one class of them from overwriting another previously built
class.  The implementation complicates build rules: the simple rule of
placing a derived object next to its source has to be replaced with a set
of rules which "know" how to derive segregated objects.  In a sense, the
rules know the class of an object by where it goes.  Each class of object
goes into its own directory.  Because the directory names are arbitrary,
they should be standardized by convention.  In the example below, they
are objs, profs, and pics.  There are corresponding macro names to hold
the respective lists of object names.

OBJS=	$(OBJECTS:%=objs/%)
PROFS=	$(OBJECTS:%=profs/%)
PICS=	$(OBJECTS:%=pics/%)

The directories do not necessarily exist prior to a build, hence:

objs profs pics libp:
	-@mkdir $@

Here is representative use of two of the macros and directories:

ARFLAGS=  r

$(LIBRARY): objs $(OBJS)
	$(AR) $(ARFLAGS) $@ $(OBJS)

libp/$(LIBRARY): profs libp $(PROFS)
	$(AR) $(ARFLAGS) $@ $(PROFS)

where OBJS, PROFS, and other such dependencies can be built by:

objs/%.o profs/%.o pics/%.o: %.c
	$(COMPILE.c) -o $@ $<

The one rule suffices because COMPILE.c uses standard macros which can be
assigned varying values dynamically:

# conditional assignments
$(PROFS) :=	CFLAGS += -p
$(PICS)  :=	CFLAGS += -K pic
$(PICS)  :=	CPPFLAGS += -DPIC


	If incremental builds are going to retain many intermediate files,
the way to get the most benefit from the files is through the representation
of intermediate dependencies.  In the case of libraries, the installed
library ultimately depends upon source files for its objects, but we retain
the archive local to the source tree and all the object files it archives.

	If you rewrite one elaborate build rule into a series of rules
and subtargets, keep a few things in mind.  Retain the intermediate
objects corresponding to the subtargets so "make" can stat them; don't
remove them during the build process, you will lose the basis for
incremental building.  Remember to add the intermediate objects to
the list of items removed by the "clean" target.  If some intermediate
objects very rarely change and have long-term value, associate them
with clobber rather than clean.

	A series of pattern-matching rules works well with out-of-date
intermediate files present.  However, such rules can fail when the files
are absent (as mentioned above in the justification for adding "all" as a
dependency of the "install" target).  The way to avert the failure is
follow the pattern-matching rules in the makefile with explicit dependen-
cies.  It is crucial to get the ordering correct.  An accurate representa-
tion allows the build to resume work in small steps applying just the
right rules.  Here is a simplified example taken from the kernel's adb
macro directory.  SCRIPTS-sun4c is a list of targets to build in the sun4c
directory.

sun4c/%.adb.c : %.adb
	sparc/adbgen1 < $< > $@

sun4c/%.run: sun4c/%.adb.c
	$(BUILD.run)

sun4c/%: sun4c/%.run
	$(BUILD.adb)

# dependencies made explicit
$(SCRIPTS-sun4c) : $$(@).adb.c $$(@).run

	Without the explict dependencies, "make" would not know
how to build sun4c/foo from foo.adb in the absence of sun4c/foo.adb.c
and sun4c/foo.run.  With the dependencies, foo.adb yields sun4c/foo.adb.c
that yields sun4c/foo.run that yields sun4c/foo.

	The above example serves to illustrate a chain of pattern-matching
rules.  However, it also illustrates a concept taken too far.  In actual
practice, people only changed the .adb source files.  The intermediate
objects were not independently changed, so the full chain of rules was
fired in every instance.  If intermediate objects do not change indepen-
dently, then you are not gaining an incremental build advantage.  You need
to balance the overhead of additional rules with the advantage of accurate
incremental builds from independent changes.

	Fast incremental rebuilds depend upon not oversimplifying the
steps it takes to build each object and not overstating the dependencies
of each step.  Many opportunities for improvement remain in this area.
Not all speed improvements stem from dependency information enhancements.
In some build actions, commands can be replaced by appropriate makefile
macros.  For examples, architecture values can be derived from the
predefined macro TARGET_ARCH, and $(@D) and $(@F) can replace "dirname"
and "basename."  For-loops can be replaced with suitable dynamic targets.

	There is choice among tradeoffs in representing dependencies.
Overstated dependencies can slow the build down.  Understated dependen-
cies can break incremental builds or make them inaccurate.  Let us study
a configuration that presents these risks and tradeoffs.

	In some areas of the source base you can find several adjacent
directories of command source and one directory of library source, where
many or all of the commands depend on linking with one or a few libraries
built in the library directory.  For example, consider this diagram:

				topdir/
				Makefile

	libdir/		cmddir1/	cmddir2/	cmddir3/
	Makefile	Makefile	Makefile	Makefile
	*.c *.o		*.c *.o		*.c *.o		*.c *.o
	libfoo.a	cmd1a cmd1b	cmd2		cmd3a cmd3b


	There are several ways to build such a configuration; in selecting
a method, you should consider build performance, incremental build
accuracy, and completeness of the dependency graph.  In general, our
practices indicate we are willing to trade some completeness of the graph
for speed in the build but not compromise the accuracy of incremental
builds in the large.

	Three methods are worth consideration, each recommended within
a range of configuration sizes.  Viewed from the perspective of one of
the directories of command source, the three methods are:

  1) forcibly jumping to the library directory and checking each library
     against its sources,
  2) merely checking the existence of each library and building each if
     it is missing,
  3) not checking for the library, assuming it exists, failing otherwise.

	The essential details of (1) are:

in top makefile:

SUBDIRS = cmddir1 cmddir2 cmddir3

clean clobber := SUBDIRS += libdir

all install clean clobber lint: $(SUBDIRS) FRC

in a command dir:

LDLIBS += $(LOCAL_LIB)

$(PROG): $(LOCAL_LIB)

$(LOCAL_LIB): FRC
	@cd $(@D); pwd; make $(@F)
	@pwd

FRC:

	In a given configuration, (1) is the slowest to build because it
is doing much redundant checking.  It also represents the complete depen-
dency graph, thus a build from scratch started in a command directory
succeeds.  

	The essential details of (2) are:

in top makefile:

SUBDIRS = libdir cmddir1 cmddir2

all install clean clobber lint: $(SUBDIRS) FRC

in a command dir:

LDLIBS += $(LOCAL_LIB)

$(PROG): $(LOCAL_LIB)

$(LOCAL_LIB):
	@cd $(@D); pwd; make $(@F)
	@pwd


	In the same configuration given above, (2) is markedly faster to
build than (1) because (2) avoids redundant checking of library source,
however it represents a truncated dependency graph.  It indicates a
dependence on the existence of a library, not necessarily an up-to-date
library.  A build from scratch started in a command directory will
succeed, but an incremental build started there might use an out-of-date
library since it checks only for existence.  Hence (2) relies on the
makefile at the top of the configuration to direct the build in the large
into the library directory first, ensuring libraries are up-to-date before
they are referenced.

	The essential details of (3) are:

in top makefile:

SUBDIRS = libdir cmddir

all install clean clobber lint: $(SUBDIRS) FRC

in a command dir:

LDLIBS += $(LOCAL_LIB)


	In the given configuration, (3) is the quickest to build.  The
dependency graph omits explicit reference to libraries (although the
KEEP_STATE mechanism keeps records of them).  A build from scratch started
in a command directory will fail because the libraries do not exist, so
(3) relies on the top makefile in the configuration for the existence of
the libraries.

	From these observations, the guidelines recommend the following.

	In general practice (2) is recommended because a small build in
a command directory can jump over to a library directory and build a
library if it needs it, but the expense of (1) is avoided.  Although
very small incremental builds may be inaccurate because of using out-
of-date libraries, large incremental builds are correct because higher
level makefiles will visit library directories before the command
directories which use them.  It is mandatory in (2) that the build in
the large build libraries before they are referenced.  For parallel "make"
a .WAIT is necessary.

	In small configurations of source, having few commands and small
libraries, you may want to use (1) for its completeness and accuracy.  The
small configuration implies a small performance penalty.  With (1), the
top makefile in the configuration should not descend directly into the
library directory for "all" and "install" targets; it should leave the
library build to be triggered as a side effect of the builds in the
command directories.  However, the top makefile should descend into
the library directory for "clean" and "clobber" targets.

	In very large configurations (3) is recommended for speed in
the build and less clutter in the makefiles.  In (3) a failure of a
top makefile to descend early into library directories will be obvious.
For parallel "make" a .WAIT is necessary.

Host Architecture Independence
------------------------------

	Host architecture independence is implemented through an AT&T
practice of using ROOT to specify a location, other than the build
machine's root directory, into which the build process deposits header
files and libraries for reference during later parts of the build.  The
default values of flags for build tools force references to be made under
the directory specified by ROOT.  Our default value for ROOT is /proto,
but it is often overridden in builds in CodeManager workspaces, since
workspaces often contain private proto areas reflecting local changes. Use
of ROOT permits flexibility with regard to the release of operating system
running on the build machine.  The implementation is simplified by some
complementary goals yet to be discussed, namely configurability and global
flexibility; nevertheless the specifics are the same: the value of ROOT is
used in all pertinent flags and preliminary directories and header files
are installed under ROOT.  (This material is taken from a number of
makefiles.)

ROOT=		/proto
CPPFLAGS=	-I$(ROOT)/usr/include
LDLIBS +=	-L$(ROOT)/usr/lib

ROOTDIRS=	$(TARGETDIRS:%=$(ROOT)%)
ROOTLIBDIR=	$(ROOT)/usr/lib
ROOTLIBS=	$(LIBS:%=$(ROOTLIBDIR)/%)

# the Targetdirs file is the AT&T target.dirs file in a makefile format.
# it defines TARGETDIRS and ROOTDIRS.
include Targetdirs

sgs: rootdirs userheaders libheaders sysheaders

rootdirs: $(ROOTDIRS)

$(ROOTDIRS):
	$(INS.dir)

userheaders: FRC
	@cd head; pwd; $(MAKE) install_h

libheaders: FRC
	@cd lib; pwd; $(MAKE) install_h

sysheaders: FRC
	@cd uts; pwd; $(MAKE) install_h

FRC:

	We have added the "ws" script to our use of CodeManager to set
values of shell environment variables that specify ROOT references for
include paths and load paths, automatically.  For example, the specific
value seen above for CPPFLAGS is replaced with a reference to shell
variable ENVCPPFLAGS1.  For referencing libraries, there is a similar
variable ENVLDLIBS1.  See the man page for the ws script.


Suitably Global Flexibility
---------------------------

	Suitably global flexibility is implemented primarily with the
makefile "include" mechanism and secondarily with great reliance on the
make.rules file in /usr/share/lib/make.  At the top of the source tree is
Makefile.master, containing macro assignments of global importance.
Changes to Makefile.master apply to the whole build.

	Here is a simplified version of the current Makefile.master:

  [ . . . ]
#
# Makefile.master, global definitions for system source
#
ROOT=		/proto

INS=		install
SYMLINK=	ln -s
CHOWN=		echo
CHGRP=		echo

FILEMODE=	644
DIRMODE=	755
OWNER=		bin
GROUP=		bin

INS.file=	$(RM) $@; $(INS) -s -m $(FILEMODE) -f $(@D) $<
INS.dir=	$(INS) -s -d -m $(DIRMODE) $@
# installs and renames at once
#
INS.rename=	$(INS.file); $(MV) $(@D)/$(<F) $@

# In most places, assignments to these macros should be appended with +=
# (CPPFLAGS.master allows values to be prepended to CPPFLAGS.)
#
CFLAGS=		-O
CPPFLAGS.master= $(ENVCPPFLAGS1) $(ENVCPPFLAGS2) $(ENVCPPFLAGS3)
CPPFLAGS=	$(CPPFLAGS.master)

# Define compilation macros (may be temporary until make.rules goes SVr4).
#
COMPILE.c=	$(CC) $(CFLAGS) $(CPPFLAGS) -c
COMPILE.cc=	$(CCC) $(CCFLAGS) $(CPPFLAGS) -c
COMPILE.s=	$(AS) $(ASFLAGS) $(AS_CPPFLAGS)
LINK.c=		$(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS)

  [ . . . ]


	The macros INS.dir, INS.file, and INS.rename permit the syntax of
the install command to change with differing values for INS, such as it
would between the Berkeley version and the AT&T version.  The macros also
change their values when the superuser does a build with chown and chgrp
applied to output.  The mechanism that supports the switch to superuser
activities depends, for its success, on everyone consistently using
INS.dir, INS.file, and INS.rename for install work.  Use of the macros is
therefore required.

	(The mechanism was omitted for clarity from the example above; it
uses the CH macro to turn off superuser actions via a comment '#'
chararcter.  The superuser sets CH to "" so actions for root are no longer
commented out.  Evidence above of the non-superuser default operation is
the "echo" value assigned benignly to CHGRP and CHOWN.)

	INS.dir works with simple directory targets.  You should find it
somewhere after the install target in a makefile.  In contrast, INS.file
and INS.rename must be employed with a pattern-matching rule; they are
only reliable when used with pattern-matching rules, because the "$<"
dynamic macro they use often evaluates to nothing when used with a
standard target.  You should find INS.file and INS.rename used after
assignments and before targets in a makefile, often just before the
KEEP_STATE target.

	The variable MACH is deliberately missing because its value comes
from the shell environment of the build.  It directs the build into
instruction-set-specific subdirectories and selects instruction-set-
specific values for other variables and build rules.


	There are other features of global interest only to subsections
of the source tree.  Global library build definitions are in Makefile.lib
in the lib directory.  Likewise, global command build definitions are in
Makefile.cmd in the cmd directory.  Separate global makefiles called
Makefile.targ define common targets for libraries and command; these must
be separate makefiles, so they may be included after the top targets are
defined in the makefile that does the including.  More global makefiles
may be introduced in other areas of the source tree, wherever central
definitions would contribute control and consistency.

	Here is a lengthy yet simplified excerpt from Makefile.cmd:

  [ . . . ]
#
# cmd/Makefile.cmd
# Definitions common to command source.
#
# include global definitions; SRC should be defined in the shell.
# SRC is needed until RFE 1026993 is implemented.

include $(SRC)/Makefile.master

LN=		ln
CP=		cp
MV=		mv -f
SH=		sh
ECHO=		echo
MKDIR=		mkdir
TOUCH=		touch

FILEMODE=	0555
LIBFILEMODE=	0444
ROOTBIN=	$(ROOT)/usr/bin
ROOTLIB=	$(ROOT)/usr/lib
ROOTSBIN=	$(ROOT)/sbin
ROOTETC=	$(ROOT)/etc
ROOTCCSBIN=	$(ROOT)/usr/ccs/bin

# storing LDLIBS in two macros allows reordering of options
LDLIBS.cmd=	$(ENVLDLIBS1) $(ENVLDLIBS2) $(ENVLDLIBS3)
LDLIBS=		$(LDLIBS.cmd)
LDFLAGS.cmd=	$(STRIPFLAG) $(ENVLDFLAGS1) $(ENVLDFLAGS2) $(ENVLDFLAGS3)
LDFLAGS=	$(LDFLAGS.cmd)

ROOTPROG=	$(PROG:%=$(ROOTBIN)/%)
ROOTSHFILES=	$(SHFILES:%=$(ROOTBIN)/%)
ROOTLIBPROG=	$(PROG:%=$(ROOTLIB)/%)
ROOTLIBSHFILES= $(SHFILES:%=$(ROOTLIB)/%)
ROOTSBINPROG=	$(PROG:%=$(ROOTSBIN)/%)
ROOTETCPROG=	$(PROG:%=$(ROOTETC)/%)
ROOTCCSBINPROG=	$(PROG:%=$(ROOTCCSBIN)/%)

$(ROOTBIN)/%: %
	$(INS.file)

$(ROOTLIB)/%: %
	$(INS.file)

$(ROOTSBIN)/%: %
	$(INS.file)

$(ROOTETC)/%: %
	$(INS.file)

$(ROOTCCSBIN)/%: %
	$(INS.file)

Both Makefile.cmd and Makefile.lib include Makefile.master from the top of
the source tree, so makefiles which include either of them need not include
Makefile.master.  Think of the definitions you need and include the suitably
global makefile.  (The SRC macro is discussed below.)

	Notice that pattern-matching rules may be considered part of defin-
itions not targets; they are not confined to the lower regions of makefiles.


	The second point of this implementation is careful use of standard
macros defined in the make.rules file.  Examples are LDLIBS, LDFLAGS,
CFLAGS, CPPFLAGS, LINTFLAGS, and many more.  When explicit build rules are
needed at all, they should be expressed using the most inclusive macros
available, e.g., use COMPILE.c or LINK.c in preference to a more detailed
line with CC.  Use some care in selecting the appropriate macro for flags,
e.g., use CPPFLAGS instead of CFLAGS for include-path specification.
CPPFLAGS is more descriptive, more precise, and used in more places.

	The '+=' operator for "make" only appends to a macro's value.  In
the LDLIBS case, above, the order of library references was important.
While the global definition of LDLIBS was useful, it caused a problem when
another library had to be referenced ahead of whatever was globally
defined.  The redundant assignment to LDLIBS.cmd solved the problem by
permitting this usage:

rfadmin := LDLIBS = -lns $(LDLIBS.cmd) -lcrypt_i

The technique has been applied to CPPFLAGS in Makefile.master,
creating CPPFLAGS.master.


Configurability
---------------

	Configurability is an extension of the practice of using
predefined macros from make.rules.  It encourages common acceptance and
use of the same macro names across the source tree.  It suggests, for
example, that a "clobber" target could be improved by replacing "rm -f"
with $(RM).  This may appear to add little value at the time it is
created, but later development or tests may be made much easier by the
configuration option this leaves open.  A powerful option comes from the
consistent and appropriate use of ROOT; it permits the entire output of
a "make -e install" to be redirected after simply setting ROOT to a
differing value in the shell.  Another important option is provided by
INS, which specifies the command used for doing file installation.  We
may at times want to set INS to some set-UID-root version of "install."
Use of INS, itself, is configurable with the macros DIRMODE, FILEMODE,
OWNER, and GROUP.  With experience, we have found that INS is not
flexible enough by itself, so INS is now enclosed in INS.dir, INS.file,
and other such macros to permit redefinition of installation actions
during the superuser's creation of releases.

	Besides the macros mentioned so far, arbitrary but standard macro
names for targets help make possible the use of the global definitions of
common targets.  Examples include MACHLIBS, ROOTLIBS, LIBS, ROOTDIRS,
LIBRARY, LINTLIB, PLIB, etc.

	Providing a macro name for any adjustible item may create a useful
command-line configuration option.  For example sun4c and SPARC kernel
modules with symbols for kdbx may be obtained without editing a makefile
by using:

cd uts
make -e CFLAGS=-g TARGET=all sun4c sparc


	Other macros simply make the source tree more consistent and
easier to understand: SUBDIRS, TARGET, FRC, etc.


AT&T Similarity
---------------

	Reasonably close adherence to the Sun and AT&T makefile agreement
involves preservation of the layout of the source directory structure, use
of some key makefile macros, the habit of defining some macros in the shell
environment, and adoption of the "clobber" target.  As implied in a
discussion above, this adherence goal includes the host-architecture
independence goal and much of the configurability goal.

	The most important AT&T macro is ROOT because of its role in the
implementation of host-architecture independence.  SRC is used to denote
the absolute path to the top of the source tree.  In our use of
CodeManager, SRC provides a mechanism for doing builds after relocating
the source tree in the file system.  Ideally, SRC should be unnecessary:
all paths should be relative or with respect to ROOT.  The AT&T macro INC
should be avoided; its function of providing the include path for
header-file references is better handled by CPPFLAGS, because of the
engineering investment in the make.rules file.

	ROOT is supposed to get its value from the environment through the
use of the '-e' flag with "make."  The "ws" script sets ROOT for us and
correspondingly adds 'e' to the MAKEFLAGS environment variable.  The
assignment of /proto to ROOT in makefiles is a conservative practice to
control the default value of ROOT in cases where ROOT is absent from the
shell's environment.  Without the default, a superuser could easily
install into a build machine's header-file and library areas and corrupt
them.

	AT&T contributed the definition of the "clobber" target and a
redefinition of the "clean" target.  The clobber target removes everything
derived, nearly always employing the clean target in the process.  The clean
target removes intermediate build files such as object files, without
touching what might be called target objects such as libraries, commands,
kernels, and shell scripts.

	This concludes the topic of implementing the overall build design
goals.  The remaining sections are smaller guidelines, a list of common
macros, and Glenn Skinner's contribution of the vgrind command makefile
as an interestingly complex example.


Guidelines
==========

	This is a collection of rules and tips, aiming towards a
consistent and effective makefile style.  

	Maintain and extend the implementation details which strive for
the build design goals listed above.

	Use the "clean" and "clobber" targets as defined above.

	Use the "install_h" target for preliminary installation of header
files under ROOT.  The "sgs" target (an AT&T term for software generation
system) in the top makefile drives the preliminary work of establishing
those resources under ROOT which serve as dependencies for the rest of the
build.  (The compilers that at one time were a part of this system are
instead provided by packages you add or directories you mount.)

	The subtargets or objects of the "install" target should always
be defined in terms of ROOT, to maintain that macro's power to redirect
the output of installations.  For clarity, macros representing subtargets
of the "install" target should have names beginning with ROOT, e.g., use
ROOTDIRS instead of DIRS.

	If you must define your own installation rules, use INS.file,
INS.dir, and INS.rename rather than "install" or INS.

	Use options to the "install" command to set file modes, group,
and ownership.  These are represented in the macros DIRMODE, FILEMODE,
GROUP, and OWNER.  Conditional assignments work well for exceptions to
your default values for these macros.

	If you are creating a new makefile responsible for installing
objects into several target directories, you will probably find it easiest
to group the objects according to target directory, choose ROOT macro
names for the installed groups, and choose related non-ROOT macro names
for the groups of built objects that the installed objects require.  In
other words build and label your dependency graph backwards from the
"install" target.  The "install" target should drive everything.  The "all"
target is merely the collection of prerequisites for install work to begin.

	Use default build rules as much as possible.  Special cases should
be expressed as far as possible as conditional assignments to standard
macros used by default rules.  For example, rather than write an explicit
rule for building cal from cal.c just because it has to be linked with the
math library, use:

cal := LDLIBS += -lm

"Defines" for the C compiler should be added (+=) to CPPFLAGS.

	Derive as many macro values as practicable from other macro values.
This maintains the defined relations among the macros and reduces the number
of places to be edited for name changes or name assignments.  See, for
example, the LIBRARY macro in Makefile.lib.

	Continue the practice of including global makefiles; do not insert
their text into some new makefile, for this would ruin the intended
flexibility.  If you see unvarying material in several sibling makefiles,
collect the redundant material into a central makefile, cut it from the
individual makefiles, and include the central makefile.

	Use SCCS keywords and a copyright in the comments in the header of
your makefile.  (See terminator:/usr/integration/doc/keyword_info.)

	Identify the makefile in the comments in the header; specify its
full path name relative to the root of the source tree, e.g.,
cmd/vgrind/Makefile.

	When a parent makefile specifies a descent into a subdirectory,
a "pwd" should be used along with MAKE.  This assists error tracking in
"make" log files.

userheaders: FRC
	@cd head; pwd; $(MAKE) install_h

	Similarly, if a makefile specifies a lateral cd in the source
tree to build a remote target and return, use an addition "pwd" to denote
the return.

$(LIBMAIL): FRC
	@cd $(@D); pwd; $(MAKE) $(@F)
	@pwd

	When removing files under a "clean" or "clobber" target, a specific
list of files is preferred to a wild-card pattern.

clean:
	$(RM) $(OBJS) $(PROFS) $(CLEANFILES)

	As practicable, combine targets with the SUBDIRS dependency (e.g.,
all, install, clean, clobber, and lint) and use TARGET to specify what
should be done in the subdirectory.  TARGET gets its value through a
conditional assignment.  If "all" depends only on SUBDIRS, then "install"
should not depend on "all", rather it too should depend only on SUBDIRS
and rely on the "install" targets in subdirectories to depend on their
respective "all" targets.  This avoids redundant dependency checking.

	As practicable, use pattern-matching rules instead of subtargets and
hard-coded dynamic macros.  These rules provides a more general solution,
probably requiring less maintenance as things evolve.  Dynamic macros such
as "$<" are reliable with rules but unreliable with targets.  Mind the order
of the pattern-matching rules you write; the first match found is the rule
applied.  Usually you want assembler ahead of C source and local machine-
specific source ahead of remote common source.  Beware that pattern-matching
installation rules can, in rare instances, mix with build rules having odd
consequences.

	Avoid using a pattern-replacement macro reference as the left side
of colon (in a pattern-matching rule or a target); this ambiguous use of '%'
can cause unreliable results from the "make" parser.  Instead, assign to a
new macro the value generated by the pattern-replacement macro reference and
use the new macro on the left side of the pattern-matching rule.  This gives
you a chance to create a meaningful name for the pattern-replacement value.
So, in place of something fictional such as:

$(KOBJS:%=$(KERNARCH)/unix/%): $(KDEPS)

use this alternative:

UNIXOBJS= $(KOBJS:%=$(KERNARCH)/unix/%)

$(UNIXOBJS): $(KDEPS)


	Retain or add the ".KEEP_STATE" target.  Avoid "make depend."

	Place "dot" targets (such as .KEEP_STATE, .INIT, .DONE, .FAILED)
before the "all" target.  "all" should be the first regular target.
Place pattern-matching rules and suffix rules before any targets.  Bend
placement guidelines as needed either to consolidate information into
central include makefiles or to maintain a meaningful context for some
special purpose.

	As practicable, reference header files directly from the source
tree with relative include paths and the '-I' option in CPPFLAGS.

	Avoid adding a symbolic link to the source tree.

	Avoid explicit references to SCCS.  The source product must be
able to build without SCCS files present.

	Avoid macro names likely to appear in a developer's shell envi-
ronment with an entirely different meaning and an inappropriate value,
e.g., HOME, USER, PWD, PRINTER.


Common Macros
=============

	These are common macros not including all in the make.rules file.
They are presented alphabetically with short descriptions.

ARCH		obsolete designation of system architecture, e.g., sun2, sun3
AROBJS		the list of objects derived from OBJECTS and used by BUILD.AR
BUILD.AR	the default action for creating an archive (library)
BUILD_PROFS	a toggle for building profiled libraries, off by default
CH		a toggle for superuser actions, off by default via '#'
CLEANFILES	extra files to be removed by the "clean" target
CLOBBERFILES	extra files to be removed by the "clobber" target
DIRMODE		parameter to INS, the install command used in INS.dir
DYNLIB		a dynamic library target, added (+=) to LIBS if needed
FILEMODE	parameter to INS, the install command used in INS.file
FRC		pseudotarget and false dependency to *force* build actions
GROUP		parameter to INS, the install command
HDRDIRS		system directories supplying header files for "install_h"
HDRS		a plain list of header files
IFNOTPROTO	a toggle for symlink creation outside /proto, off by default
INS.dir		the whole install action using INS for a directory
INS.file	the whole install action using INS for a file
INS.liblink	an install action that creates a link or symlink to a library
INS.rename	INS.file with extra work to rename the installed object
KERNARCH	a kernel architecture such as sun4c (PLATGRP is preferred)
LIBNAME		the core part of the LIBRARY name such as 'w' in libw.a
LIBRARY		the specific library to be built locally such as libw.a
LIBS		the list of local library targets, regular, profiled, etc.
LINTLIB		the lint library target, added (+=) to LIBS if needed
LINTOUT		the default output file for LINT, not /dev/null
MACH		the instruction-set architecture of the build
MACHLIBS	a list of target LIBS in a MACH subdirectory
MACHPLIB	the PLIB target in a MACH subdirectory
NATIVECC	the native C compiler, CC, for the machine doing the build
NATIVEMACH	the instruction-set architecture of the machine doing the build
OBJECTS		a plain list of object names such as foo.o, bar.o, etc.
OBJS		a derived list of target OBJECTS in the objs subdirectory
OWNER		parameter to INS, the install command
PICS		a list target OBJECTS in the pics subdirectory, position-indep.
PLATFORM	a very specific architecture such as SUNW,SPARCstation-10,SX
PLATGRP		a group of platforms such as sun4c (can be a subset of KERNARCH)
PLIB		the name of the profiled library
PROFS		a list target OBJECTS in the profs subdirectory, profiled
PROG		a program target within command source, may be a list
ROOT		the prototypical file system, target area of "install"
ROOTDIRS	a list of directories to install under ROOT
ROOTBIN		the central target command directory under ROOT
ROOTCCSBIN	/usr/ccs/bin under ROOT
ROOTCCSBINPROG	PROG to be installed into ROOTCCSBIN
ROOTETC		/etc under ROOT
ROOTETCPROG	PROG to be installed into ROOTETC
ROOTHDRS	HDRS to be installed under ROOT
ROOTLIB		/usr/lib under ROOT
ROOTLIBDIR	the central target library directory under ROOT
ROOTLIBPROG	PROG to be installed into ROOTLIB
ROOTLIBS	LIBS to be installed into ROOTLIBDIR
ROOTPLIB	PLIB to be installed under ROOTLIBDIR
ROOTPROG	PROG to be installed into ROOTBIN
ROOTSBIN	/sbin under ROOT
ROOTSBINPROG	PROG to be installed into ROOTSBIN
ROOTSHLIB	/usr/share/lib under ROOT
ROOTSHLIBPROG	PROG to be installed into ROOTSHLIB
ROOTUSRSBIN	/usr/sbin under ROOT
ROOTUSRSBINPROG	PROG to be installed into ROOTUSRSBIN
SCRIPTS		shell scripts that go into the installed product
SCRIPTSRC	"source" for SCRIPTS having ".sh" extensions
SONAME		the shared-object name by which a DYNLIB identifies itself
SRC		the root of the source tree, i.e., usr/src in a workspace
SRCS		a list of source files exclusive of header files
STATIC		STATPROG with .static file extensions
STATPROG	a subset of PROG to be built in static form
SUBDIRS		a list of directories into which the build will descend
SYMLINK		the ln command with the -s option to create a symbolic link
TARGET		the target name for the build to invoke in a subdirectory
VERS		version-number suffix for DYNLIB


vgrind Makefile example
=======================

#
# [imagine standard SCCS keywords here]
#
# Copyright (c) 1990 by Sun Microsystems, Inc.
#
# cmd/vgrind/Makefile
#

#
# These are the objects associated with the overall vgrind command.
#
VFONTEDPR=	vfontedpr
RETEST= 	retest
MACROS=		tmac.vgrind
LANGDEFS=	vgrindefs
CSHPROG=	vgrind

#
# These macros captures objects that ultimately will be installed in
# (respectively) /usr/bin, /usr/lib, and /usr/share/lib.
#
# Note also that retest is used strictly as a test program and is never
# installed.  We omit it here, so that ordinary builds do not spend cycles
# on it.
#
PROG=		$(CSHPROG)
LIBPROG= 	$(VFONTEDPR) $(LANGDEFS)
TMACPROG=	$(MACROS)

VFONTEDPROBJS=	vfontedpr.o vgrindefs.o regexp.o
RETESTOBJS=	retest.o regexp.o

RETESTSRC=	$(RETESTOBJS:%.o=%.c)

OBJS= $(VFONTEDPROBJS) $(RETESTOBJS)
SRCS= $(OBJS:%.o=%.c)

#
# We can get away simply with omitting TMACPROGS to protect
# tmac.vgrind, since it's the only entry in that macro.
#
CLOBBERFILES=	$(LIBPROG) $(RETEST)

include ../Makefile.cmd

#
# Abbreviation for future use.
#
ROOTTMAC= $(ROOT)/usr/share/lib/tmac

#
# Override macro definitions from Makefile.cmd.  Necessary because
# we're building targets for multiple destinations.
#
ROOTLIBPROG= $(LIBPROG:%=$(ROOT)/usr/lib/%)
ROOTTMACPROG= $(TMACPROG:%=$(ROOTTMAC)/%)

#
# Conditional assignments pertinent to installation.
#
$(ROOTLIB)/$(LANGDEFS) 	:= FILEMODE= $(LIBFILEMODE)
$(ROOTTMACPROG) 	:= FILEMODE= $(LIBFILEMODE)

#
# The standard set of rules doesn't know about installing into
# subdirectories of /usr/share/lib, so we have to roll our own.
#
$(ROOTTMAC)/%: %
	$(INS.file)

.KEEP_STATE:

#
# retest appears here only in source form; see comment above for PROG.
#
all:	$(PROG) $(LIBPROG) $(TMACPROG) $(RETESTSRC)

$(VFONTEDPR): $(VFONTEDPROBJS)
	$(LINK.c) -o $@ $(VFONTEDPROBJS) $(LDLIBS)

$(LANGDEFS):	$(LANGDEFS).src
	$(RM) $@; $(CP) $(LANGDEFS).src $@

$(RETEST): $(RETESTOBJS)
	$(LINK.c) -o $@ $(RETESTOBJS) $(LDLIBS)

#
# XXX:	There should be a .csh rule in make.rules.  Until there is, we
# do it by hand.
#
$(CSHPROG): $(CSHPROG).csh
	$(RM) $@
	$(CP) $(CSHPROG).csh $@
	chmod +x $@

#
# We add "all" as a dependent to make sure that the install pattern
# matching rules see everything they should.  (This is a safety net.)
#
# XXX:	ROOTTMAC shouldn't appear as a dependent; it's here as a
# 	bandaid(TM) until /usr/lib/tmac becomes a symlink to
#	/usr/share/lib/tmac.
#
install: all $(ROOTTMAC) $(ROOTPROG) $(ROOTLIBPROG) $(ROOTTMACPROG)

# XXX: see above.
$(ROOTTMAC):
	$(INS.dir)

clean:
	$(RM) $(OBJS)

#
# Don't worry about linting retest.
#
lint :=	SRCS = $(VFONTEDPROBJS:%.o=%.c)
lint: lint_SRCS

include ../Makefile.targ