home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / cpm3 / cpmmake.ark / UNIXMAKE.MAN < prev   
Encoding:
Text File  |  1986-08-31  |  17.0 KB  |  525 lines
  1.  
  2.  
  3.  
  4. make(1)                                                   make(1)
  5.  
  6.  
  7.  
  8. make - Maintain, Update, and Regenerate Groups of Programs (ATT)
  9.  
  10.  
  11.  
  12.  
  13.  
  14. SYNTAX
  15.  
  16.      make [-options] [names]
  17.  
  18.      names   specifies targets to be made.
  19.  
  20.  
  21.  
  22. OPTIONS
  23.  
  24.      -b   specifies the compatibility mode for old makefiles.
  25.  
  26.      -d   prints  detailed  information  on   files   and   times
  27.           examined.
  28.  
  29.      -e   specifies   that   environment    variables    override
  30.           assignments within makefiles.
  31.  
  32.      -f makefile
  33.           makefile specifies the name of a description  file.   A
  34.           file  name  specified  with  a  hyphen  (-)  means  the
  35.           standard input.  The contents of makefile override  the
  36.           built-in rules if they are present.  If an -f option is
  37.           not  present,  makefile,  Makefile,   s.makefile,   and
  38.           s.Makefile are tried in order.  More than one -makefile
  39.           argument pair may appear.
  40.  
  41.      -i   ignores error codes returned by invoked commands.  This
  42.           mode is entered if the fake target name .IGNORE appears
  43.           in the description file.
  44.  
  45.      -k   abandons work on the current entry,  but  continues  on
  46.           other branches not depending on that entry.
  47.  
  48.      -n   prints commands, but does not execute them.  Even lines
  49.           beginning with an @ are printed.
  50.  
  51.      -p   prints the complete set of macro definitions and target
  52.           descriptions.
  53.  
  54.      -q   returns a zero or  nonzero  status  code  depending  on
  55.           whether or not the target file is up-to-date.
  56.  
  57.      -r   does not use the built-in rules.
  58.  
  59.  
  60.  
  61. Unix User's
  62. Reference Manual               -1-                       Commands
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. make(1)                                                   make(1)
  71.  
  72.  
  73.  
  74.      -s   does not print command lines  before  executing.   This
  75.           mode  is  also  entered if the fake target name .SILENT
  76.           appears in the description file.
  77.  
  78.      -t   touches the target files (causing  them  to  be  up-to-
  79.           date) rather than issuing the usual commands.
  80.  
  81.      .DEFAULT
  82.           If a file must  be  made  but  there  are  no  explicit
  83.           commands  or  relevant  built-in  rules,  the  commands
  84.           associated with  the  name  .DEFAULT  are  used  if  it
  85.           exists.
  86.  
  87.      .PRECIOUS
  88.           Dependents of this target will not be removed when quit
  89.           or interrupt are encountered.
  90.  
  91.      .SILENT
  92.           Same effect as the -s option.
  93.  
  94.      .IGNORE
  95.           Same effect as the -i option.
  96.  
  97.  
  98. DESCRIPTION
  99.  
  100.    Make executes commands in makefile updating one or more target
  101.    files.   If  makefile  is  specified  with  a  hyphen (-), the
  102.    standard input is used.
  103.  
  104.    Make updates a target only if it depends on files  newer  than
  105.    the  target.   All  prerequisite  files  of a target are added
  106.    recursively to the list of targets.  Missing files are  deemed
  107.    to be out of date.
  108.  
  109.    Makefile   contains   a   sequence   of   entries   specifying
  110.    dependencies.   The  first  line  of  an  entry  is  a  blank-
  111.    separated,  non-null  list  of  targets,  then  a  :,  then  a
  112.    (possibly  null)  list  of prerequisite files or dependencies.
  113.    Text following a ; and all following lines that begin  with  a
  114.    tab  are  Shell  commands to be executed to update the target.
  115.    The first line that does not begin with a tab or  #  begins  a
  116.    new  dependency  or  macro  definition.  Shell commands may be
  117.    continued  across   lines   with   the   <backslash><new-line>
  118.    sequence.  Everything printed by make (except the initial tab)
  119.    is passed directly to the Shell as is.  Thus,
  120.  
  121.       echo a\
  122.       b
  123.  
  124.    produces
  125.  
  126.  
  127. Unix User's
  128. Reference Manual               -2-                       Commands
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. make(1)                                                   make(1)
  137.  
  138.  
  139.  
  140.       ab
  141.  
  142.    exactly the same as the Shell would.
  143.  
  144.    Sharp (#) and newline surround comments.
  145.  
  146.    The following makefile states that pgm depends  on  two  files
  147.    a.o   and   b.o,  and  that  they  in  turn  depend  on  their
  148.    corresponding source files (a.c and b.c)  and  a  common  file
  149.    incl.h:
  150.  
  151.           pgm: a.o b.o
  152.                cc a.o b.o -o pgm
  153.           a.o: incl.h a.c
  154.                cc -c a.c
  155.           b.o: incl.h b.c
  156.                cc -c b.c
  157.  
  158.    Command lines are executed one at a  time,  each  by  its  own
  159.    Shell.   The  first  one or two characters in a command can be
  160.    the following: -, @, -@, or @-.  If @ is present, printing  of
  161.    the  command  is suppressed.  If - is present, make ignores an
  162.    error.  A line is printed when it is executed  unless  the  -s
  163.    option  is  present,  or the entry .SILENT: is in makefile, or
  164.    unless the initial character sequence contains a  @.   The  -n
  165.    option  specifies  printing without execution; however, if the
  166.    command line has the string $(MAKE) in it, the line is  always
  167.    executed   (see   discussion  of  the  MAKEFLAGS  macro  under
  168.    Environment).  The -t (touch) option updates the modified date
  169.    of a file without executing any commands.
  170.  
  171.    Commands returning nonzero status normally terminate make.  If
  172.    the  -i  option  is  present, or the entry .IGNORE: appears in
  173.    makefile, or the initial character  sequence  of  the  command
  174.    contains  -.   the  error  is  ignored.   If  the -k option is
  175.    present, work is abandoned on the current entry, but continues
  176.    on other branches that do not depend on that entry.
  177.  
  178.    The -b option allows old makefiles (those written for the  old
  179.    version  of  make)  to  run  without  errors.   The difference
  180.    between the old version of make and this version is that  this
  181.    version requires all dependency lines to have a (possibly null
  182.    or implicit) command associated with them.
  183.  
  184.    Interrupt and quit cause the target to be deleted  unless  the
  185.    target is a dependency of the special name .PRECIOUS.
  186.  
  187. Environment
  188.  
  189.    The environment is read by make.  All variables are assumed to
  190.    be  macro  definitions and processed as such.  The environment
  191.    variables are processed before  any  makefile  and  after  the
  192.  
  193. Unix User's
  194. Reference Manual               -3-                       Commands
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201. make(1)                                                   make(1)
  202.  
  203.  
  204.  
  205.    internal rules; thus, macro assignments in a makefile override
  206.    environment variables.  The -e option causes  the  environment
  207.    to override the macro assignments in a makefile.
  208.  
  209.    The MAKEFLAGS environment variable is  processed  by  make  as
  210.    containing  any  legal  input  option  (except -f, -p, and -d)
  211.    defined for the command line.  Further, upon invocation,  make
  212.    invents the variable if it is not in the environment, puts the
  213.    current options into it, and passes it on  to  invocations  of
  214.    commands.   Thus,  MAKEFLAGS always contains the current input
  215.    options.  This proves very useful for super-makes.   In  fact,
  216.    as  noted  above,  when  the  -n  option  is used, the command
  217.    $(MAKE) is executed anyway allowing a make -n to be  performed
  218.    recursively  on a whole software system to see what would have
  219.    been executed.  This is because the -n is put in MAKEFLAGS and
  220.    passed to further invocations of $(MAKE).
  221.  
  222.    This is one way of  debugging  all  of  the  makefiles  for  a
  223.    software project without actually doing anything.
  224.  
  225. Macros
  226.  
  227.    Entries of the form string1 = string2 are  macro  definitions.
  228.    String2 is defined as all characters up to a comment character
  229.    or  an   unescaped   newline.    Subsequent   appearances   of
  230.    $(string1[:subst1=[subst2]])  are  replaced  by  string2.  The
  231.    parentheses are optional if a single character macro  name  is
  232.    used  and  there  is  no  substitute  sequence.   The optional
  233.    :subst1=subst2 is a substitute sequence.  If it is  specified,
  234.    all  nonoverlapping  occurrences  of subst1 in the named macro
  235.    are replaced by subst2.  Strings (for  the  purposes  of  this
  236.    type  of  substitution) are delimited by blanks, tabs, newline
  237.    characters, and beginnings of lines.  An example of the use of
  238.    the substitute sequence is shown under Libraries.
  239.  
  240. Internal Macros
  241.  
  242.    There are five internally maintained macros which  are  useful
  243.    for writing rules for building targets.
  244.  
  245.      $*      the file name part of the current dependent with the
  246.              suffix  deleted.  It is evaluated only for inference
  247.              rules.
  248.  
  249.      $@      the full target name of the current target.   It  is
  250.              evaluated only for explicitly named dependencies.
  251.  
  252.      $<      is  only  evaluated  for  inference  rules  or   the
  253.              .DEFAULT  rule.   It  is  the module which is out of
  254.              date  with  respect  to  the   target   (i.e.,   the
  255.              manufactured  dependent  file  name).   Thus, in the
  256.  
  257. Unix User's
  258. Reference Manual               -4-                       Commands
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266. make(1)                                                   make(1)
  267.  
  268.  
  269.  
  270.              .c.o rule, the $< macro would  evaluate  to  the  .c
  271.              file.  An example for making optimized .o files from
  272.              .c files is:
  273.  
  274.                   .c.o:
  275.                        cc -c -O $*.c
  276.     or:
  277.                   .c.o:
  278.                        cc -c -O $<
  279.  
  280.      $?      is evaluated when explicit rules from  the  makefile
  281.              are evaluated.  It is the list of prerequisites that
  282.              are  out  of  date  with  respect  to  the   target;
  283.              essentially, those modules which must be rebuilt.
  284.  
  285.      $%      is only evaluated when  the  target  is  an  archive
  286.              library  member  of  the  form lib(file.o).  In this
  287.              case, $@ evaluates to lib and $%  evaluates  to  the
  288.              library member, file.o.
  289.  
  290.    Four of the five macros can have alternative forms.   When  an
  291.    upper  case  D  or F is appended to any of the four macros the
  292.    meaning is changed to "directory part" for D and  "file  part"
  293.    for F.  Thus, $(@D) refers to the directory part of the string
  294.    $@.  If there is no directory part, ./ is generated.  The only
  295.    macro  excluded from this alternative form is $?.  The reasons
  296.    for this are debatable.
  297.  
  298. Suffixes
  299.  
  300.    Certain names  (for  instance,  those  ending  with  .o)  have
  301.    inferable  prerequisites  such  as  .c, .s, etc.  If no update
  302.    commands for such  a  file  appear  in  makefile,  and  if  an
  303.    inferable  prerequisite  exists, that prerequisite is compiled
  304.    to make the target.  In this case, make  has  inference  rules
  305.    that  allow  building  files from other files by examining the
  306.    suffixes and determining an appropriate inference rule to use.
  307.    The current default inference rules are:
  308.  
  309.       .c .c~ .sh .sh~ .c.o .c~.o .c~.c .s.o .s~.o .y.o .y~.o .l.o
  310.       .l~.o
  311.       .y.c .y~.c .l.c .c.a .c~.a .s~.a .h~.h
  312.  
  313.    The internal rules for make are contained in the  source  file
  314.    rules.c  for  the  make  program.   These rules can be locally
  315.    modified.  To print out the rules compiled into  the  make  on
  316.    any   machine  in  a  form  suitable  for  recompilation,  the
  317.    following command is used:
  318.  
  319.       make -fp - 2>/dev/null </dev/null
  320.  
  321.  
  322. Unix User's
  323. Reference Manual               -5-                       Commands
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331. make(1)                                                   make(1)
  332.  
  333.  
  334.  
  335.    The only peculiarity in this output is the (null) string which
  336.    printf(3S) prints when handed a null string.
  337.  
  338.    A tilde in the above rules refers to an SCCS  file  (refer  to
  339.    sccsfile(4)).   Thus, the rule .c~.o would transform an SCCS C
  340.    source file into an object file (.o).  Because the s.  of  the
  341.    SCCS  files is a prefix, it is incompatible with make's suffix
  342.    point-of-view.  The tilde  is  a  way  of  changing  any  file
  343.    reference into an SCCS file reference.
  344.  
  345.    A rule with only one suffix (i.e. .c:) is  the  definition  of
  346.    how to build x from x.c.  In effect, the other suffix is null.
  347.    This is useful for building targets from only one source  file
  348.    (e.g., Shell procedures, simple C programs).
  349.  
  350.    Additional suffixes are  given  as  the  dependency  list  for
  351.    .SUFFIXES.   Order is significant; the first possible name for
  352.    which  both  a  file  and  a  rule  exist  is  inferred  as  a
  353.    prerequisite.  The default list is:
  354.  
  355.       .SUFFIXES: .o .c .y .l .s
  356.  
  357.    The above command for printing the internal rules displays the
  358.    list of suffixes implemented on the current machine.  Multiple
  359.    suffix  lists  accumulate;  .SUFFIXES:  with  no  dependencies
  360.    clears the list of suffixes.
  361.  
  362. Inference Rules
  363.  
  364.    The first example can be done more briefly:
  365.  
  366.           pgm: a.o b.o
  367.                cc a.o b.o -o pgm
  368.           a.o b.o: incl.h
  369.  
  370.    This is because make has a set of internal rules for  building
  371.    files.   The user may add rules to this list by simply putting
  372.    them in the makefile.  Certain macros are used by the  default
  373.    inference  rules to permit the inclusion of optional matter in
  374.    any resulting commands.   For  example,  CFLAGS,  LFLAGS,  and
  375.    YFLAGS  are  used  for  compiler options to cc(1), lex(1), and
  376.    yacc(1)  respectively.   Again,  the   previous   method   for
  377.    examining the current rules is recommended.
  378.  
  379.    The inference of prerequisites can be controlled.  The rule to
  380.    create  a  file  with  suffix .o from a file with suffix .c is
  381.    specified as  an  entry  with  .c.o:  as  the  target  and  no
  382.    dependents.   Shell commands associated with the target define
  383.    the rule for making a .o file from a .c file.  Any target that
  384.    has  no slashes in it and starts with a dot is identified as a
  385.    rule and not a true target.
  386.  
  387. Unix User's
  388. Reference Manual               -6-                       Commands
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396. make(1)                                                   make(1)
  397.  
  398.  
  399.  
  400. Libraries
  401.  
  402.    If a target or dependency name  contains  parentheses,  it  is
  403.    assumed   to   be   an  archive  library,  the  string  within
  404.    parentheses referring to a member within the  library.   Thus,
  405.    lib(file.o)  and  $(LIB)(file.o)  both  refer  to  an  archive
  406.    library containing file.o. (This assumes  the  LIB  macro  has
  407.    been   previously  defined.)   The  expression  $(LIB)(file1.o
  408.    file2.o) is not legal.  Rules pertaining to archive  libraries
  409.    have  the form .XX.a where the XX is the suffix from which the
  410.    archive member is to be made.  An unfortunate byproduct of the
  411.    current  implementation  requires  the XX to be different from
  412.    the suffix of the  archive  member.   Thus,  one  cannot  have
  413.    lib(file.o)  depend  upon  file.o explicitly.  The most common
  414.    use of the archive interface follows.   Here,  we  assume  the
  415.    source files are all C type source:
  416.  
  417.           lib: lib(file1.o) lib(file2.o) lib(file3.o)
  418.                @echo lib is now up to date
  419.           .c.a:
  420.                $(CC) -c $(CFLAGS) $<
  421.                ar rv $@ $*.o
  422.                rm -f $*.o
  423.  
  424.    In fact, the .c.a rule listed above is built into make and  is
  425.    unnecessary  in  this  example.   A more interesting, but more
  426.    limited example of an archive library maintenance construction
  427.    follows:
  428.  
  429.           lib: lib(file1.o) lib(file2.o) lib(file3.o)
  430.                $(CC) -c $(CFLAGS) $(?:.o=.c)
  431.                ar rv lib $?
  432.                rm $?  @echo lib is now up to date
  433.           .c.a:;
  434.  
  435.    Here the substitution mode of the macro  expansions  is  used.
  436.    The  $?   list  is  defined to be the set of object file names
  437.    (inside lib) whose C  source  files  are  out  of  date.   The
  438.    substitution  mode  translates  the .o to .c.  (Unfortunately,
  439.    one cannot as yet transform to .c~; however, this  may  become
  440.    possible  in  the  future.)   Note  also, the disabling of the
  441.    .c.a: rule, which would have created each object file, one  by
  442.    one.   This  particular  construct  speeds  up archive library
  443.    maintenance considerably.  This type of construct becomes very
  444.    cumbersome  if  the archive library contains a mix of assembly
  445.    programs and C programs.
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453. Unix User's
  454. Reference Manual               -7-                       Commands
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462. make(1)                                                   make(1)
  463.  
  464.  
  465.  
  466. SPECIAL CONSIDERATIONS
  467.  
  468.      + Some commands return nonzero status  inappropriately;  use
  469.        -i  to  overcome the difficulty or have the makefile issue
  470.        them as -command.
  471.  
  472.      + Commands that are directly executed by the Shell,  notably
  473.        cd(1), are ineffectual across newlines in make.
  474.  
  475.      + The syntax lib(file1.o   file2.o   file3.o)   is  illegal.
  476.        lib(file.o)  cannot  be  built  from  file.o.   The  macro
  477.        $(a:.o=.c~) does not work.
  478.  
  479.  
  480.  
  481. FILES
  482.  
  483.    [Mm]akefile and s.[Mm]akefile
  484.  
  485.  
  486.  
  487. SEE ALSO
  488.  
  489.    sh(1)
  490.    Make-A Program for Maintaining  Computer  Programs  by  S.  I.
  491.    Feldman.
  492.    An Augmented Version of Make by E. G. Bradford.
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519. Unix User's
  520. Reference Manual               -8-                       Commands
  521.  
  522.  
  523.  
  524.  
  525.