home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_100 / 186_01 / make.doc < prev    next >
Text File  |  1985-08-21  |  16KB  |  377 lines
  1.  
  2.  
  3.  
  4.  
  5.                          MAKE, Version 1.1
  6.                                 by
  7.                           James Pritchett
  8.                      275 Bleecker St., Apt. 1
  9.                         New York, NY  10014
  10.                           (212) 989-1865
  11.                          December 6, 1985
  12.  
  13.  
  14.  
  15. ACKNOWLEDGEMENTS
  16.  
  17.       The  code  for  MAKE  is based on the program MK written by
  18.    Allen Holub and published in Dr. Dobb's Journal,  August  1985
  19.    issue (#106).    Many  of the functions used in MAKE are taken
  20.    directly from MK,  with  only  the  alterations  necessary  to
  21.    compile under   BDS   C.      Other   functions  were  altered
  22.    significantly to port from MS-DOS to CP/M-80.   Finally,  MAKE
  23.    includes  features  not  available in MK, such as command line
  24.    options and some macros.  I am thus heavily  indebted  to  Mr.
  25.    Holub  for  his  functions, which are identified in the source
  26.    files, as well as for the overall structure  of  the  program.
  27.    The  code  as  published  in DDJ contains no copyright notice,
  28.    but it should be assumed  that  all  functions  identified  as
  29.    written  by  Holub are his property and if used elsewhere, due
  30.    credit should be given to him. 
  31.  
  32.  
  33. DESCRIPTION
  34.  
  35.       MAKE is a version of the UNIX utility for CP/M-80.  It  was
  36.    developed  with  the BDS C compiler, version 1.50a, and should
  37.    run on any standard CP/M-80 system.
  38.  
  39.       MAKE is a utility used to simplify the  compilation/linkage
  40.    process  of  C  programs  consisting  of  more than one source
  41.    file.  Put simply, MAKE will determine which  files,  if  any,
  42.    need  to  be  compiled and linked, and will batch all the CP/M
  43.    commands needed to perform the compilation and  linkage.    If
  44.    changes are made to some, but not all, source files, MAKE will
  45.    determine which files have been changed and will compile  only
  46.    those files that have been changed.
  47.  
  48.       MAKE  gets the information on which source files are needed
  49.    for a program and what commands are necessary to  compile  and
  50.    link  from a "makefile." The makefile is a text file outlining
  51.    the interdependancy of files relating  to  a  program  (source
  52.    files, object  files, header files).  The makefile consists of
  53.    a series of "objects" that  can  be  made  (object  files  and
  54.    executable files).   Each object has a list of "dependancies",
  55.    which are either filenames (source files or header files),  or
  56.    other objects  in  the  makefile.  Each object also has a list
  57.    of "actions"  necessary  to  make  the  object:    these   are
  58.    standard CP/M  command lines (such as "CC FOO").  In practice,
  59.    objects that are executable files will depend  on  object-file
  60.    objects  (i.e.,  COM  files  depend on CRL files), and objects
  61.    that are object files will depend on source and  header  files
  62.    (i.e., CRL  files  depend  on C and H files).  The actions for
  63.    making  executable-file  objects  will  usually   be   linkage
  64.    commands,  and the actions for making object-file objects will
  65.    be compilation commands.
  66.  
  67.       When MAKE is run, it is given a "target"  to  make.    MAKE
  68.    will  find  the  target  object  in  the  makefile,  and  will
  69.    evaluate its dependancies.  If a  dependancy  is  a  file,  it
  70.    will  check  to  see  if  that file has been changed since the
  71.    last MAKE run.  If a  dependancy  is  another  object  in  the
  72.    makefile, MAKE  will  see if that object needs making.  If any
  73.    of the dependancy files has been changed, or  if  any  of  the
  74.    dependancy  objects  needs  making,  then  the commands in the
  75.    action list will be batched for execution.   Since  dependancy
  76.    objects  are  made  before the target, the commands for making
  77.    dependancies will always occur before  the  commands  for  the
  78.    target.
  79.  
  80.       MAKE  determines  whether  files have been changed by means
  81.    of file attributes.  MAKE checks a  particular  attribute  bit
  82.    (attribute t3'  by  default)  in  the dependancy filename.  If
  83.    that bit is set, then the file  is  assumed  to  be  unchanged
  84.    from the  last  MAKE  run.    If the bit is reset, the file is
  85.    assumed to be changed, and will  cause  the  object  it  is  a
  86.    dependancy for  to  be  made.  If the bit is reset, it will be
  87.    set by MAKE after testing.  It will remain set until the  file
  88.    is edited  or  renamed  (i.e.,  until it is altered).  The set
  89.    attribute will have no effect on other CP/M functions.  For  a
  90.    full  discussion  of this principle, see Ian Ashdown's back-up
  91.    utility BU, DDJ, January 1985, issue #99 (note  that  although
  92.    he  refers  to  t3'  as an "archive bit", any unused CP/M file
  93.    attribute will perform the same).  MAKE will  not  affect  any
  94.    other file attributes that may be set for a given file.
  95.  
  96.       Commands  are  batched  by  creating  a pending SUBMIT file
  97.    (A:$$$.SUB) and warm-booting.    MAKE  will  nest  with  other
  98.    batched  commands,  so  that MAKE itself can be invoked from a
  99.    SUBMIT file.
  100.  
  101.  
  102. MAKEFILE FORMAT
  103.  
  104.       A makefile entry is in the following format:
  105.  
  106.        objectname: dependancy1 dependancy2 . . . dependancyX
  107.                    action1
  108.                    action2
  109.                    . . .
  110.                    action3
  111.  
  112.    Any number of entries may be contained in a  single  makefile,
  113.    and  all  entries  need not relate to the same target (i.e., a
  114.    makefile  may  contain   information   relating   to   several
  115.    different programs).
  116.  
  117.       The  objectname  may  be  any combination of alphanumerics,
  118.    and does not necessarily  have  to  be  the  filename  of  the
  119.    object  to  be  made  (e.g.,  if  the  object  to  be  made is
  120.    "FOOBAR.COM", the objectname could be "FOOBAR.COM",  "FOOBAR",
  121.    or "BINKY").    Objectnames must be terminated by a colon, and
  122.    must begin in the left-most column.
  123.  
  124.       Following the objectname, on the same line, is  a  list  of
  125.    dependancies, each  separated  by  white  space.  A dependancy
  126.    may  be  either  a  filename   or   an   objectname   (if   an
  127.    objectname, it  must  refer  to  another  entry  in  the  same
  128.    makefile).  Any dependancy that does not match  an  objectname
  129.    in the  makefile will be considered a filename.  Filenames are
  130.    in the standard BDS C format:
  131.  
  132.        [uu/d:]filename.typ
  133.  
  134.    where "uu/" is an optional user area specification,  and  "d:"
  135.    is an  optional  drive  name  specification.  All dependancies
  136.    must be on the same line  as  the  objectname.    There  is  a
  137.    maximum of 20 dependancies per entry.
  138.  
  139.       There  are  two  "macros"  available  in MAKE, version 1.1:
  140.    the default drive and default user area.   These  specify  the
  141.    drive  and  user  area that will be searched for all filenames
  142.    that do not have  explicit  drive/user  specifications.    The
  143.    format of the two macros is:
  144.  
  145.        $:d     (d = drive name)
  146.        $/uu    (uu = user area)
  147.  
  148.    Macros  must  be  on  separate  lines,  and  must begin in the
  149.    left-most column.  If no default drive/user is  given  in  the
  150.    makefile,  and  no explicit drive/user is given on a filename,
  151.    then  the  currently  logged  drive/user  will  be   searched.
  152.    Macros should  be  stated only once in a makefile.  If a macro
  153.    is stated more than once, the last statement will be used.
  154.  
  155.       On the line  after  the  objectname/dependancy_list  begins
  156.    the action_list.    Each action should be a CP/M command line,
  157.    and each action should be on a different line.  There must  be
  158.    no  blank  lines  either  between  the objectname line and the
  159.    first  action_list   line,   or   between   actions   in   the
  160.    action_list.   Actions  should  be given in the order they are
  161.    to be executed.  Any amount of white  space  may  precede  the
  162.    action  on  the line, although this is not necessary (it looks
  163.    neater, however).    The  first  blank  line  terminates   the
  164.    action_list.   There  may  be  no  more  than  10  actions per
  165.    action_list.  If the default disk or default user area  macros
  166.    are  used,  they  will NOT affect filenames listed as parts of
  167.    commands.
  168.  
  169.       The action_list is optional.  Objects with no actions  will
  170.    be  evaluated  as  normal,  but  will  not affect the batch of
  171.    commands.  The reason for this is  to  set  up  an  objectname
  172.    that substitutes  for  a  list of files in a makefile.  If you
  173.    have a program that has several source files  that  depend  on
  174.    the  three  headers  "FOO.H",  "BAR.H",  and "ZOT.H", then the
  175.    following makefile entry:
  176.  
  177.        headers: foo.h bar.h zot.h
  178.                                    [blank line]
  179.  
  180.    will  allow  you  to  use  the  objectname  "headers"  in  the
  181.    dependancy_lists  for  the  source  files in lieu of the three
  182.    header filenames.  This is also a way of  getting  around  the
  183.    maximum-dependancy limit.   Note that such a "no-action" entry
  184.    MUST be followed by a blank line.
  185.  
  186.       If a dependancy_list or an action cannot be contained on  a
  187.    single  physical  line,  a  backslash  typed at the end of the
  188.    line will continue the list or action on the next line.    For
  189.    example, the action:
  190.  
  191.        L2 B:FOOBAR B:BINKY -L A:DIO A:WILDEXP A:FLOAT\
  192.        A:LONG -D -T 7000
  193.  
  194.    will be  processed  as  a  single line.  The maximum length of
  195.    any logical line  is  300  characters.    All  characters  are
  196.    folded  to upper-case, so that "foo", "Foo", and "FOO" are all
  197.    equivalent.
  198.  
  199.       Comments may be placed in a makefile.  All comments  should
  200.    begin with  a  '#'  in  the  left-most  column.  Any number of
  201.    comments may be included in a makefile, and may occur  at  any
  202.    point in a makefile.
  203.  
  204.       A sample  makefile  is  given on the disk.  It contains the
  205.    information necessary to create MAKE.COM.
  206.  
  207.  
  208. USAGE
  209.  
  210.       Command syntax is as follows:
  211.  
  212.        MAKE [target] [options]
  213.  
  214.    If no target is given on the command line, MAKE will take  the
  215.    first object  in  the  makefile  as  the  target.  The options
  216.    are:
  217.  
  218.           -A:  MAKE will make  all  objects  encountered  in  the
  219.        course  of  evaluating  the target, whether it thinks they
  220.        need it or not.
  221.  
  222.           -F filename:  MAKE will read  the  file  "filename"  as
  223.        the makefile.    If  this  option  is not given, MAKE will
  224.        supply the default filename "MAKEFILE".
  225.  
  226.           -N:  MAKE will  evaluate  the  objects,  but  will  not
  227.        actually batch  the  commands.  This is helpful in testing
  228.        a makefile.
  229.  
  230.           -Q:  "Quiet"  mode.    Supresses  all  messages  except
  231.        fatal errors.
  232.  
  233.           -R:   MAKE  will  not  set  the  file attributes of any
  234.        files.  This is useful  when  a  header  file  needed  for
  235.        several  different  programs  has  been  changed,  and you
  236.        don't want it to be set as unchanged  until  all  programs
  237.        have been re-compiled/linked.
  238.  
  239.           -T:  "Touch-up"  mode.  MAKE will set the attributes of
  240.        files, but will not batch any  commands.    This  is  used
  241.        when  a  file  has  had  insignificant  changes made to it
  242.        (such as adding a comment).
  243.  
  244.    All options  must  be  preceded  by  a  hyphen,  and  must  be
  245.    separated by a space.
  246.  
  247.       As  MAKE  evaluates the target, it will display the command
  248.    lines to be batched in the order  they  will  execute.    When
  249.    evaluation  is complete, the user is prompted for verification
  250.    of the $$$.SUB file creation.  Typing Control-C at the  prompt
  251.    aborts MAKE  and  will  prevent the execution of commands.  If
  252.    the -Q option is  given,  the  display  of  commands  and  the
  253.    prompt is supressed.
  254.  
  255.       Examples of usage:
  256.  
  257.        (1) MAKE FOOBAR.COM
  258.        (2) MAKE FOOBAR.COM -F B:FOOMAKE -Q
  259.        (3) MAKE -F MAKEFOO
  260.  
  261.        (1) makes "FOOBAR.COM" from the file "MAKEFILE"
  262.        (2) makes "FOOBAR.COM" from the file "B:FOOMAKE" in quiet mode
  263.        (3) makes the first object in the file "MAKEFOO"
  264.  
  265. ERROR MESSAGES
  266.  
  267.    Non-fatal errors:
  268.  
  269.     "Unknown option -o ignored."
  270.        -- This will not affect the parsing of other options.
  271.  
  272.     "Unknown macro $xxx ignored."
  273.        -- Self-explanatory.
  274.  
  275.    Fatal errors:
  276.  
  277.     "Can't open MAKEFILE."
  278.        -- Self-explanatory.
  279.  
  280.     "File empty!"
  281.        -- The makefile has no entries in it.
  282.  
  283.     "Line too long (300 chars maximum)"
  284.     "Action too long (max = 10 lines)"
  285.     "Too many dependancies!  (20 maximum)"
  286.        -- The  various  limits have been exceeded.  To change the
  287.        limits for any of these, see CONFIGURABLE OPTIONS below.
  288.  
  289.     "Missing ':'"
  290.        --  MAKE  cannot  locate  a   colon   after   a   supposed
  291.        objectname.
  292.  
  293.     "Don't know how to make <target>."
  294.        -- Target does not exist in makefile.
  295.  
  296.     "Dependancy file <filename> does not exist."
  297.        --  MAKE  cannot  locate  a  dependancy  it  thinks  is  a
  298.        filename.  If this error occurs for a dependancy  that  is
  299.        NOT  a  filename, then the dependancy could not be located
  300.        as an object in the makefile.
  301.  
  302.     "Can't create A:$$$.SUB"
  303.     "Error in writing A:$$$.SUB"
  304.     "Error in closing A:$$$.SUB"
  305.        -- All self-explanatory.
  306.  
  307.     "Out of memory"
  308.        -- Some function or another has tried to  allocate  memory
  309.        and failed.    This  should only happen if the makefile is
  310.        really big, and breaking up the makefile  should  fix  the
  311.        problem.
  312.  
  313.  
  314. CONFIGURABLE OPTIONS
  315.  
  316.       MAKE consists  of  the  following  files:   MAKE.H, MAKE.C,
  317.    MAKEIO.C and MDEBUG.C.  MDEBUG.C is needed only if  the  debug
  318.    code  is  included  in  the  program  by  #defining the symbol
  319.    "DEBUG" in MAKE.H.  To compile/link MAKE:
  320.  
  321.        CC MAKE -E3000
  322.        CC MAKEIO -E3000
  323.        L2 MAKE MAKEIO
  324.  
  325.    If compiling with the debug code, don't use the -E options.
  326.  
  327.       The following constants are in MAKE.H and  may  be  altered
  328.    by the user:
  329.  
  330.        MAXLINE:
  331.        Maximum characters per input line (default:  300)
  332.  
  333.        MAXDEP:
  334.        Maximum dependancies per dependancy_list (default:  20)
  335.  
  336.        MAXBLOCK:
  337.        Maximum commands per action_list (default:  10)
  338.  
  339.        MAXUSER:
  340.        Maximum valid user area on system (default:  15)
  341.  
  342.        MATTRIB:
  343.        Number  of  attribute  to  use in testing dependancy files
  344.        for changed/unchanged status.  Can be any  number  from  1
  345.        to  11,  except  9  or  10,  which  are  reserved for CP/M
  346.        (defaults to 11).  If you  use  Ian  Ashdown's  BU,  or  a
  347.        similar  utility  that  works  with  attribute 11, you may
  348.        wish to change MATTRIB to another attribute.
  349.  
  350.        PUBLIC:
  351.        If you use the Plu*Perfect Systems  "public  files"  patch
  352.        for  the  CP/M  BDOS,  #define this symbol to include code
  353.        that will  keep  MAKE  from  inadvertantly  moving  public
  354.        files around  between  user  areas.  Otherwise, comment it
  355.        out (PUBLIC file protection is ON by default).
  356.  
  357.  
  358. WISH LIST
  359.  
  360.    Fuller set of macros (like for rootname, string  substitution,
  361.    etc.).
  362.  
  363.    Generic  dependancies  (see  Holub's  article  in  DDJ  for  a
  364.    discussion of these goodies).
  365.  
  366.  
  367.  
  368.    I hope this utility is useful for all BDS  C  programmers  out
  369.    there (how  could  it  NOT be?).  Note that MAKE will work for
  370.    non-C programs, too (like assembly code), or it could even  be
  371.    used  as a simple file archiving program (although not as good
  372.    as BU).  Enjoy!
  373.  
  374.  
  375.    James Pritchett
  376.  
  377.