mmaakkee -- Command

Program-building discipline
mmaakkee [_o_p_t_i_o_n ...] [_a_r_g_u_m_e_n_t ...] [_t_a_r_g_e_t ...]

mmaakkee 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 _o_b_j_e_c_t _m_o_d_u_l_e_s, each of which is
the product of  compiling a _s_o_u_r_c_e _f_i_l_e. A source  file may refer to one or
more  iinncclluuddee files,  which  can also  be  changed.  Some  programs may  be
generated from  specifications given to  program generators, such  as yyaacccc.
Recompiling  and  relinking  complicated  programs  can  be  difficult  and
tedious.

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

_O_p_t_i_o_n_s
The following lists  the options that can be passed  to mmaakkee on its command
line.

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

-ee   Force  macro  definitions  in environment  to  override  those in  the
     mmaakkeeffiillee.

-ff _f_i_l_e
     _f_i_l_e contains the mmaakkee specification.  If this option does not appear,
     mmaakkee uses the file mmaakkeeffiillee,  which is sought first in the directories
     named  in the  PPAATTHH environmental  variable, and  then in  the current
     directory.   If  _f_i_l_e is  `-',  mmaakkee uses  the  standard input;  note,
     however, that the standard input can be used _o_n_l_y if it is piped.

-ii   Ignore all  errors from commands, and  continue processing.  To invoke
     this behavior  for an individual action within  a mmaakkeeffiillee, prefix the
     action with the `-' flag.  By default, mmaakkee exits if a command returns
     an error.

-k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n   Test only; suppress  execution of commands.  To override this behavior
     for an individual action within a mmaakkeeffiillee, prefix the action with the
     `+' flag.

-pp   Print all macro definitions and target descriptions.

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

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

-SS   Terminate  mmaakkee 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k.

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

-t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,
     mmaakkee  will  still  execute an  individual  action  if  that action  is
     prefixed with the `+' flag.

_T_h_e _M_a_k_e_f_i_l_e
A  mmaakkeeffiillee consists  of three  types  of instructions:  _m_a_c_r_o _d_e_f_i_n_i_t_i_o_n_s,
_d_e_p_e_n_d_e_n_c_y _d_e_f_i_n_i_t_i_o_n_s, and _c_o_m_m_a_n_d_s.

A macro definition simply defines  a macro for use throughout the mmaakkeeffiillee;
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  _t_a_r_g_e_t _n_a_m_e, 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  FFIILLEESS to name the object modules  used to build the program
eexxaammppllee.  Likewise, the dependency definition

    file1.o:  file1.c macros.h

defines the object module ffiillee11.oo  as consisting of the source file ffiillee11.cc
and the header file mmaaccrrooss.hh.

Finally, a command  line details an action that mmaakkee  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 cccc  command needed to build the program  eexxaammppllee.  The cccc command
lists the _o_b_j_e_c_t _m_o_d_u_l_e_s to be used, _n_o_t the source files.

Note  that if  you prefix  an action  with a hyphen  `-', mmaakkee  will ignore
errors in the  action.  If the action is prefixed  by `@', it tells mmaakkee 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 mmaakkeeffiillee.  mmaakkee  ignores a pound
sign `#'  and all text that follows it.   COHERENT's implementation of mmaakkee
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 mmaakkee do not permit this, including
the one specified by POSIX.2: _c_a_v_e_a_t _u_t_i_l_i_t_o_r.

mmaakkee searches for mmaakkeeffiillee  first in directories named in the environmental
variable PPAATTHH, and then in the current directory.

_m_a_k_e _W_i_t_h_o_u_t _a _M_a_k_e_f_i_l_e
Beginning with release  4.2 of COHERENT, you can also  invoke mmaakkee to build
an  object for  which no  mmaakkeeffiillee  exists.  In  this case,  mmaakkee 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

mmaakkee will search the local directory for any file named ffoooo that has any of
the  suffices that  mmaakkee  recognizes by  default.  If  the local  directory
contains a file  named ffoooo.cc, mmaakkee invokes cccc to  compile it; whereas if it
contains a file named ffoooo.oo, it invokes the linker lldd to link it.

Note  that if  no mmaakkeeffiillee  exists, mmaakkee by  default creates  an executable
named aa.oouutt;  in this,  it differs  from the command  cccc, which  creates an
executable named  after the first  .cc or .oo  file to appear  on its command
line.   For details  on cccc's  behavior, see  its entry  in the  Lexicon, in
particular the discussion of its option -oo.

_D_e_p_e_n_d_e_n_c_i_e_s
The  mmaakkeeffiillee specifies  which files  depend upon other  files, and  how to
recreate the dependent files.  For example, if the target file tteesstt depends
upon the object module tteesstt.oo, the dependency is as follows:

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

mmaakkee knows  about common dependencies,  e.g., that .oo files  depend upon .cc
files with the same base  name.  The target .SSUUFFFFIIXXEESS contains the suffixes
that mmaakkee recognizes.

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

    .c.o:
        cc -c $<

The -cc option to the cccc commands tells cccc not to link or erase the compiled
object module.  $< is a macro  that mmaakkee defines; it stands for the name of
the file  that causes the  current action.  The default  suffixes and rules
are kept in the files /uussrr/lliibb/mmaakkeemmaaccrrooss and /uussrr/lliibb/mmaakkeeaaccttiioonnss.

_M_a_c_r_o_s
To  simplify the  writing of  complex dependencies,  mmaakkee provides  a _m_a_c_r_o
facility.  To define a macro, write

    _N_A_M_E = _s_t_r_i_n_g

_s_t_r_i_n_g  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.:

    $(_N_A_M_E)
    ${_N_A_M_E}
If the  macro name is  one character, parentheses are  not necessary.  mmaakkee
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 _l_i_b_r_a_r_y(_o_b_j_e_c_t),  this macro  expands
     to the _l_i_b_r_a_r_y part of the target.

$%   For targets that are library dependencies of the form _l_i_b_r_a_r_y(_o_b_j_e_c_t),
     this macro expands to the _o_b_j_e_c_t 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  mmaakkee chose as the implicit prerequisite  of the target.  Do
     not use this macro outside a suffix rule.

You can  specify macro definitions in the mmaakkeeffiillee,  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  mmaakkeeffiillee.  Normally,  a  definition  in  a  mmaakkeeffiillee  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
mmaakkeeffiillee.

Each command line _a_r_g_u_m_e_n_t 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 sshh.

_S_o_u_r_c_e _F_i_l_e _P_a_t_h
mmaakkee 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, mmaakkee 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, mmaakkee
then searches  for the  file in  the list of  directories specified  by the
macro  $(SSRRCCPPAATTHH).  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 mmaakkeeffiillee and
sources  in /uussrr/ssrrcc/llooccaall/mmee.  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 $(SSRRCCPPAATTHH).

Note that $(SSRRCCPPAATTHH) 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 ppaatthh().

_M_a_c_r_o_s _a_n_d _E_n_v_i_r_o_n_m_e_n_t_a_l _V_a_r_i_a_b_l_e_s
The  environmental variable  MMAAKKEEFFLLAAGGSS  provides an  alternative method  of
passing parameters to mmaakkee. If this variable is defined, mmaakkee processes the
switches that  it contains as if  they were specified on  the command line.
mmaakkee  processes  MMAAKKEEFFLLAAGGSS  before  it  processes any  actual  command-line
parameters.

Either of the following two formats can be used for MMAAKKEEFFLLAAGGSS:

      MAKEFLAGS="-n -d"
      MAKEFLAGS=nd

Either of the above passes to mmaakkee the options nn and dd.

After  it processes  the switches  named in  MMAAKKEEFFLLAAGGSS, mmaakkee  processes all
options set on its command line.  mmaakkee then re-defines MMAAKKEEFFLLAAGGSS to contain
the full  set of  switches passed  to it, and  marks the macro  for export.
This means  that recursive invocations  of mmaakkee are passed  the same switch
settings as the highest-level invocation of mmaakkee. (See also the description
of the `+' flag, below.)

mmaakkee takes  all other environment-variable  settings passed to  it and uses
them to set the values of corresponding macros internally.

When  mmaakkee  executes  a  command,  it  exports  to  that  command  all  the
environmental  variables mmaakkee  imported from  the initial  environment, the
MMAAKKEEFFLLAAGGSS  environmental  variable,  and the  macros  defined  on the  mmaakkee
command line.

_A_l_w_a_y_s _A_c_t_i_o_n_s
If  an action  for  rebuilding a  target  begins with  the  `+' flag,  mmaakkee
executes the action even if the  command line specifies the option -nn. This
is useful when dealing with  recursive mmaakkeeffiilleess: when you pass the options
-pp, -dd, or  -nn to the top-level invocation of  mmaakkee, the top-level mmaakkeeffiillee
can still  invoke the sub-mmaakkeeffiilleess, and  pass them the same  flags via the
environmental variable MMAAKKEEFFLLAAGGSS,  as described above.  This simplifies the
debugging  of mmaakkeeffiillees  for complex  projects.   This flag  mainly affects
mmaakkee's usage with the options -qq, -nn, and -tt.

_L_i_b_r_a_r_y _D_e_p_e_n_d_e_n_c_i_e_s
mmaakkee interprets targets of the form _l_i_b_r_a_r_y(_o_b_j_e_c_t) as referring to members
of an archive created with the  archiver aarr. mmaakkee can examine the archive's
contents to determine whether the named  member is present and what date it
possesses.

When  building such  a  target, mmaakkee  looks  for suffix  rules  for use  in
building _o_b_j_e_c_t,  but with  a target  suffix of .aa  rather than  the actual
suffix of _o_b_j_e_c_t.

For example, with the default mmaakkee rules in effect, the target

    libc.a(clock.o)

would be  rebuilt from a source  file cclloocckk.cc by the  suffix-rule .cc.aa. The
default suffix  rule (as supplied in  file /uussrr/lliibb/mmaakkeeaaccttiioonnss) deals with
building the  _o_b_j_e_c_t file and then  uses the macros AARR  and AARRFFLLAAGGSS 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, mmaakkee sets the
macro  $@ to  the name  of the  _l_i_b_r_a_r_y part  of the  target, and  sets the
special macro $% (defined only for use with library targets) to the name of
the _o_b_j_e_c_t part of the target.

_S_i_n_g_l_e-_S_u_f_f_i_x _R_u_l_e_s
mmaakkee 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, mmaakkee appends onto
the target every  known suffix in turn, and for  each suffix searches for a
file  or rule  for building  the  target.  If  mmaakkee 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  ttaarrggeett_s_u_f_f_i_x, with  the actions
given in the single-suffix rule.

For example, the default rules for mmaakkee contain a single-suffix rule:

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

Given the  above rule and  a file in  the current directory  or source path
named cclloocckk.cc, the target

      clock:

results in  the executable file  cclloocckk being built by  compiling the single
source file cclloocckk.cc and linking it.

_S_u_f_f_i_x-_R_e_w_r_i_t_i_n_g _M_a_c_r_o _E_x_p_a_n_s_i_o_n
You can use a special form of macro expansion

    $(_m_a_c_r_o:_s_u_f_f_i_x[=_v_a_l_u_e])

to simplify the use of macros that involve long lists of files names.  When
you request  the above  form of expansion,  mmaakkee searches the  expansion of
_m_a_c_r_o;  for every  word that  ends in  _s_u_f_f_i_x it  replaces _s_u_f_f_i_x  with the
optional _v_a_l_u_e.

For example, consider the following:

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

This expansion of the macro OOBBJJSS is:

    parse.o interpret.o builtin.o

When a  mmaakkeeffiillee uses  long lists  of files, this  facility not  only saves
typing, but eases  maintenance because you need to change  only one list of
files.

_P_a_t_h-_O_r_i_e_n_t_e_d _M_a_c_r_o _E_x_p_a_n_s_i_o_n_s
The following special-macro  expansion forms perform path processing on the
macro's contents:

     $(_s_p_e_c_i_a_l)     Normal expansion
     $(_s_p_e_c_i_a_lFF)    Expand only file-name part
     $(_s_p_e_c_i_a_lDD)    Expand only directory part without trailing slash

where _s_p_e_c_i_a_l  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  bbaasseennaammee.  In  particular,  when
expanding a  macro with a file  list such as ${?DD},  mmaakkee processes all the
entries in  the file list as specified; otherwise,  this would be extremely
cumbersome.

_F_i_l_e_s
mmaakkeeffiillee
MMaakkeeffiillee -- List of dependencies and commands
/uussrr/lliibb/mmaakkeeaaccttiioonnss -- Default actions
/uussrr/lliibb/mmaakkeemmaaccrrooss -- Default macros

_S_e_e _A_l_s_o
aass, cccc, ccoommmmaannddss, lldd, ssrrccppaatthh, ttoouucchh
_T_h_e _m_a_k_e _P_r_o_g_r_a_m_m_i_n_g _D_i_s_c_i_p_l_i_n_e, tutorial

_D_i_a_g_n_o_s_t_i_c_s
mmaakkee reports its exit status if it is interrupted or if an executed command
returns error  status.  It replies  ``Target _n_a_m_e not  defined'' or ``Don't
know how to make target _n_a_m_e'' if it cannot find appropriate rules.

_N_o_t_e_s
Prior to release 4.2,  COHERENT's implementation of mmaakkee permitted users to
use the macro $< outside of suffix rules.  This non-standard behavior is no
longer supported.

The order of  items in mmaakkeemmaaccrrooss/.SSUUFFFFIIXXEESS is significant.  The consequent
of a default rule (e.g., .oo)  must _p_r_e_c_e_d_e the antecedent (e.g., .cc) in the
entry .SSUUFFFFIIXXEESS. Otherwise, mmaakkee will not work properly.
