make -- Command

Program-building discipline
make [option ...] [argument ...] [target ...]

make helps  you build things that  consist of more than  one file of source
code.  A ``thing'' can be a program, a report, a document, or anything else
that is constructed out of something else.

Complex programs often consist of  several object modules, each of which is
the product of  compiling a source file. A source  file may refer to one or
more  include files,  which  can also  be  changed.  Some  programs may  be
generated from  specifications given to  program generators, such  as yacc.
Recompiling  and  relinking  complicated  programs  can  be  difficult  and
tedious.

make regenerates programs automatically.  It follows a specification of the
structure of the  program that you write into a  file called makefile. make
also checks  the date and time  that COHERENT has recorded  for each source
file   and  its   corresponding   object  module;   to  avoid   unnecessary
recompilation,  make will  recompile  a source  file  only if  it has  been
altered since its object module was last compiled.

Options

The following lists  the options that can be passed  to make on its command
line.

-d   (Debug) Give  verbose printout of all  decisions and information going
     into decisions.

-e   Force  macro  definitions  in environment  to  override  those in  the
     makefile.

-f file
     file contains the make specification.  If this option does not appear,
     make uses the file makefile,  which is sought first in the directories
     named  in the  PATH environmental  variable, and  then in  the current
     directory.   If  file is  `-',  make uses  the  standard input;  note,
     however, that the standard input can be used only if it is piped.

-i   Ignore all  errors from commands, and  continue processing.  To invoke
     this behavior  for an individual action within  a makefile, prefix the
     action with the `-' flag.  By default, make exits if a command returns
     an error.

-k   Continue to  update other targets that do not  depend upon the current
     target if  a non-ignored error occurs while  executing the commands to
     bring a target up to date.

-n   Test only; suppress  execution of commands.  To override this behavior
     for an individual action within a makefile, prefix the action with the
     `+' flag.

-p   Print all macro definitions and target descriptions.

-q   Return  a zero  exit status  if the  targets are up  to date.   Do not
     execute any commands.

-r   Do not use the built-in rules that describe dependencies.

-S   Terminate  make if  an error  occurs while  executing the  commands to
     bring a target up to date.   This is true by default, and the opposite
     of -k.

-s   Do not print command  lines when executing them.  Commands preceded by
     `@' are not printed, except under the -n option.

-t   (Touch option) Force the dates of  targets to be the current time, and
     bypass actual  regeneration.  However,  if the target  is out-of-date,
     make  will  still  execute an  individual  action  if  that action  is
     prefixed with the `+' flag.

The Makefile

A  makefile consists  of three  types  of instructions:  macro definitions,
dependency definitions, and commands.

A macro definition simply defines  a macro for use throughout the makefile;
for example, the macro definition

    FILES=file1.o file2.o file3.o

Note the use of the equal sign `='.

A dependency  definition names the object modules used  to build the target
program, and source  files used to build each object  module .  It consists
of the  target name, or  name of the  program to be created,  followed by a
colon `:' and the names of  the object modules that build it.  For example,
the statement

    example:  $(FILES)

uses the macro  FILES to name the object modules  used to build the program
example.  Likewise, the dependency definition

    file1.o:  file1.c macros.h

defines the object module file1.o  as consisting of the source file file1.c
and the header file macros.h.

Finally, a command  line details an action that make  must perform to build
the  target program.   Each command  line must  begin with  a space  or tab
character.  For example, the command line

        cc -o example $(FILES)

gives the cc  command needed to build the program  example.  The cc command
lists the object modules to be used, not the source files.

Note  that if  you prefix  an action  with a hyphen  `-', make  will ignore
errors in the  action.  If the action is prefixed  by `@', it tells make to
be  silent about the  action --  that is,  do not echo  the command  to the
standard output.  The `+' flag is described below.

Finally, you  can embed comments  within a makefile.  make  ignores a pound
sign `#'  and all text that follows it.   COHERENT's implementation of make
recognizes the presence of quotation marks, and and does not treat a `#' as
a comment if it appears between apostrophes or quotation marks, or prefixed
by a backslash.  Many other versions  of make do not permit this, including
the one specified by POSIX.2: caveat utilitor.

make searches for makefile  first in directories named in the environmental
variable PATH, and then in the current directory.

make Without a Makefile

Beginning with release  4.2 of COHERENT, you can also  invoke make to build
an  object for  which no  makefile  exists.  In  this case,  make uses  its
default suffix rules to identify the objects it should construct and how it
should construct them.  If, for example, you type

    make foo

make will search the local directory for any file named foo that has any of
the  suffices that  make  recognizes by  default.  If  the local  directory
contains a file  named foo.c, make invokes cc to  compile it; whereas if it
contains a file named foo.o, it invokes the linker ld to link it.

Note  that if  no makefile  exists, make by  default creates  an executable
named after the C source file, just as the command cc does.

Dependencies

The  makefile specifies  which files  depend upon other  files, and  how to
recreate the dependent files.  For example, if the target file test depends
upon the object module test.o, the dependency is as follows:

    test:   test.o
        cc -o test test.o

make knows  about common dependencies,  e.g., that .o files  depend upon .c
files with the same base  name.  The target .SUFFIXES contains the suffixes
that make  recognizes.  (Note  that you can  use the command  makedepend to
build such a list dynamically.  For details, see its entry in the Lexicon.)

make also has  a set of rules to regenerate  dependent files.  For example,
for a source  file with suffix .c and a  dependent file with the suffix .o,
the target .c.o gives the regeneration rule:

    .c.o:
        cc -c $<

The -c option to the cc commands tells cc not to link or erase the compiled
object module.  $< is a macro  that make defines; it stands for the name
of the file that causes the current action.  The default suffixes and rules
are kept in the files /usr/lib/makemacros and /usr/lib/makeactions.

Macros

To  simplify the  writing of  complex dependencies,  make provides  a macro
facility.  To define a macro, write

    NAME = string

string  is  terminated by  the  end-of-line character,  so  it can  contain
blanks.   To  refer to  the  value of  the  macro, use  a  dollar sign  `$'
followed by the macro name enclosed in parentheses or braces, e.g.:

    $(NAME)
    ${NAME}

If the  macro name is  one character, parentheses are  not necessary.  make
uses macros in the definition of default rules:

    .c.o:
        $(CC) $(CFLAGS) -c $<

where the macros are defined as

    CC=cc
    CFLAGS=-V

The built-in macros are as follows:

$*   The target's name, minus a `.'-delimited suffix.

$@   For regular  targets, the  target's full  name.  For targets  that are
     library dependencies of the form library(object),  this macro  expands
     to the library part of the target.

$%   For targets that are library dependencies of the form library(object),
     this macro expands to the object part of the target.

$?   This expands to prerequisite files that are newer than the target.

$<
     For suffix-rules,  this macro expands to the  name of the prerequisite
     file that  make chose as the implicit prerequisite  of the target.  Do
     not use this macro outside a suffix rule.

You can  specify macro definitions in the makefile,  in the environment, or
as a  command-line argument.   A macro  defined as a  command-line argument
always overrides a definition of the  same macro name in the environment or
in  the  makefile.  Normally,  a  definition  in  a  makefile  overrides  a
definition of the same macro name  in the environment; however, with the -e
option,  a definition  in  the environment  overrides a  definition in  the
makefile.

Each command line argument should be a macro definition of the form

    OBJECT=a.o b.o

Arguments  that  include  spaces must  be  surrounded  by quotation  marks,
because blanks are significant to the shell sh.

Source File Path

make first looks for the file with the name given, which may be relative to
the current directory when make was invoked.  If it does not find the file,
and if the name of the  file is not an absolute path name, make removes any
leading  path information  from the  name  and looks  for the  file in  the
current directory.  If the file is not found in the current directory, make
then searches  for the  file in  the list of  directories specified  by the
macro  $(SRCPATH).  This allows  you  to  compile a  program  in an  object
directory separate from the source directory.  For example

    export SRCPATH=/usr/src/local/me
    make

or alteratively

    make SRCPATH=/usr/src/local/me

builds objects  in the current  directory as specified by  the makefile and
sources  in /usr/src/local/me.  To  test changes  to a  program built  from
several source files, copy only the files you wish to change to the current
directory; make  will use the local  sources and find the  other sources on
the $(SRCPATH).

Note that $(SRCPATH) can be a single directory, as in the above example, or
a `:'-separated list of directories,  as described in the Lexicon entry for
the function path().

Macros and Environmental Variables

The  environmental variable  MAKEFLAGS  provides an  alternative method  of
passing parameters to make. If this variable is defined, make processes the
switches that  it contains as if  they were specified on  the command line.
make  processes  MAKEFLAGS  before  it  processes any  actual  command-line
parameters.

Either of the following two formats can be used for MAKEFLAGS:

      MAKEFLAGS="-n -d"
      MAKEFLAGS=nd

Either of the above passes to make the options n and d.

After  it processes  the switches  named in  MAKEFLAGS, make  processes all
options set on its command line.  make then re-defines MAKEFLAGS to contain
the full  set of  switches passed  to it, and  marks the macro  for export.
This means  that recursive invocations  of make are passed  the same switch
settings as the highest-level invocation of make. (See also the description
of the `+' flag, below.)

make takes  all other environment-variable  settings passed to  it and uses
them to set the values of corresponding macros internally.

When  make  executes  a  command,  it  exports  to  that  command  all  the
environmental  variables make  imported from  the initial  environment, the
MAKEFLAGS  environmental  variable,  and the  macros  defined  on the  make
command line.

Always Actions

If  an action  for  rebuilding a  target  begins with  the  `+' flag,  make
executes the action even if the  command line specifies the option -n. This
is useful when dealing with  recursive makefiles: when you pass the options
-p, -d, or  -n to the top-level invocation of  make, the top-level makefile
can still  invoke the sub-makefiles, and  pass them the same  flags via the
environmental variable MAKEFLAGS,  as described above.  This simplifies the
debugging  of makefiles  for complex  projects.   This flag  mainly affects
make's usage with the options -q, -n, and -t.

Library Dependencies

make interprets targets of the form library(object) as referring to members
of an archive created with the  archiver ar. make can examine the archive's
contents to determine whether the named  member is present and what date it
possesses.

When  building such  a  target, make  looks  for suffix  rules  for use  in
building object,  but with  a target  suffix of .a  rather than  the actual
suffix of object.

For example, with the default make rules in effect, the target

    libc.a(clock.o)

would be  rebuilt from a source  file clock.c by the  suffix-rule .c.a. The
default suffix  rule (as supplied in  file /usr/lib/makeactions) deals with
building the  object file and then  uses the macros AR  and ARFLAGS to move
the resulting object file into the target archive.

Actions for library targets use macro definitions that differ slightly from
those for normal  actions.  When it builds a library  target, make sets the
macro  $@ to  the name  of the  library part  of the  target, and  sets the
special macro $% (defined only for use with library targets) to the name of
the object part of the target.

Single-Suffix Rules

make can use an inference rule of the form:

    suffix:
            actions

to infer an action from a target that does not have a suffix.  When you use
a target that  has no explicit rule and no  known suffix, make appends onto
the target every  known suffix in turn, and for  each suffix searches for a
file  or rule  for building  the  target.  If  make discovers  a file  that
matches one of file names that it has built, it then tries to use a single-
suffix  rule to  generate the  target from  targetsuffix, with  the actions
given in the single-suffix rule.

For example, the default rules for make contain a single-suffix rule:

      .c:
              $(CC) $(CFLAGS) $@ $<

Given the  above rule and  a file in  the current directory  or source path
named clock.c, the target

      clock:

results in  the executable file  clock being built by  compiling the single
source file clock.c and linking it.

Suffix-Rewriting Macro Expansion

You can use a special form of macro expansion

    $(macro:suffix[=value])

to simplify the use of macros that involve long lists of files names.  When
you request  the above  form of expansion,  make searches the  expansion of
macro;  for every  word that  ends in  suffix it  replaces suffix  with the
optional value.

For example, consider the following:

      SOURCES = parse.c interpret.c builtin.c
      OBJS = $(SOURCES:.c=.o)

This expansion of the macro OBJS is:

    parse.o interpret.o builtin.o

When a  makefile uses  long lists  of files, this  facility not  only saves
typing, but eases  maintenance because you need to change  only one list of
files.

Path-Oriented Macro Expansions

The following special-macro  expansion forms perform path processing on the
macro's contents:

     $(special)     Normal expansion
     $(specialF)    Expand only file-name part
     $(specialD)    Expand only directory part without trailing slash

where special is one of the following: @, ?, <, *, or %. These expansion
forms allow  rules (especially inference  rules) to deal  easily with path-
oriented  operations,   without  resorting  to   complex  shell  operations
involving  backquoting  and  the  command  basename.  In  particular,  when
expanding a  macro with a file  list such as ${?D},  make processes all the
entries in  the file list as specified; otherwise,  this would be extremely
cumbersome.

Files

makefile
Makefile -- List of dependencies and commands
/usr/lib/makeactions -- Default actions
/usr/lib/makemacros -- Default macros

See Also

as,
cc,
commands,
ld,
makedepend,
srcpath,
touch
The make Programming Discipline, tutorial

Diagnostics

make returns the following error messages:

; after target or macroname (error)
     A semicolon appeared after a target name or a macro name.

Bad macro name (error)
     A macro includes an illegal character, e.g., a control character.

= in or after dependency (error)
     An  equal sign  `=' appeared  within or followed  the definition  of a
     macro  name or  target  file.  For  example, OBJ=atod.o=factor.o  will
     produce this error.

Incomplete line at end of file (error)
     An incomplete line appeared at the end of the makefile.

Macro definition too long (error)
     The   macro  definition   exceeds  the   limited  designed   into  the
     preprocessor.

Multiple actions for name (error)
     A target is defined with more than one single-colon target line.

Multiple detailed actions for name (error)
     A target is defined with more than one single-colon target line.

Must use ``::'' for name (error)
     A double-colon target line was followed by a single-colon target line.

Newline after target or macroname (error)
     A newline character appears after a target name or a macro name.

`::' not allowed for name (error)
     A  double-colon target  line was  used  illegally; for  example, after
     single-colon target line.

::: or : in or after dependency list (error)
     A triple colon is  meaningless to make, and therefore illegal wherever
     it appears.  A  single colon may be used only  in a target line (which
     is also called the dependency list), and nowhere else.

Out of core (adddep) (error)
     This results  from a  system problem.  Try  reducing the size  of your
     makefile.

Out of range number input. (warning)
     You attempted to use a numeric value that is out of range.

Out of space (error)
     System problem.  Try reducing the size of your makefile.


Out of space (lookup) (error)
     System problem.  Try reducing the size of your makefile.

Syntax error (error)
     The syntax of a line is faulty.

Too many macro definitions (error)
     The number  of macros  you have created  exceeds the capacity  of your
     computer to process them.

= without macro name or in token list (error)
     An  equal sign  `=' can  be  used only  to define  a macro,  using the
     following   syntax:    ``MACRO=definition''.    An  incomplete   macro
     definition, or the appearance of  an equal sign outside the context of
     a macro definition, will trigger this error message.

: without preceding target (error)
     A colon appeared without a target file name, e.g., :string.

Notes

Prior to release 4.2,  COHERENT's implementation of make permitted users to
use the macro $< outside of suffix rules.  This non-standard behavior is
no longer supported.

The order of  items in makemacros/.SUFFIXES is significant.  The consequent
of a default rule (e.g., .o)  must precede the antecedent (e.g., .c) in the
entry .SUFFIXES. Otherwise, make will not work properly.

© 2012 by Stephen A. Ness