home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / utils / asmutl / pmake2.lbr / PMAKE.DQC / PMAKE.DOC
Text File  |  1986-11-16  |  18KB  |  529 lines
  1.         PMAKE     21 Jul 84                                page 1
  2.  
  3.  
  4.  
  5.         Copyright 1984  Michael M Rubenstein
  6.  
  7.         Permission is granted for noncommercial distribution of this 
  8.         program and documentation.
  9.  
  10.         Credits.
  11.  
  12.         PMAKE is a much simplified version of the Unix make program.  
  13.         PMAKE is derived from a version of make for the IBM PC written by 
  14.         John M Sellens.
  15.  
  16.  
  17.  
  18.         Changes in version 2.0.
  19.  
  20.         The major change is that pmake now supports named variable 
  21.         substitution.  The old $1, $2, ... syntax is no longer supported.  
  22.         Unfortunately, this means version 1 makefiles will require 
  23.         modification before use with version 2.
  24.  
  25.  
  26.  
  27.         Description.
  28.  
  29.         It is generally accepted that moderate to large sized programs 
  30.         are best written as a collection of relatively small modules.  It 
  31.         is often most convenient to keep these modules in separate files.  
  32.         This, however, quickly leads to difficulties in keeping track of 
  33.         which files must be compiled or assembled.
  34.  
  35.         The problem grows even worse when one is working on a system of 
  36.         programs which share some modules.  How often does one change 
  37.         something and not know offhand just what files have to be 
  38.         compiled and linked?  Happens to me all the time.
  39.  
  40.         PMAKE partially solves these problems.
  41.  
  42.         Details will be presented later, but an intuitive description of 
  43.         PMAKE seems appropriate here.
  44.  
  45.         Throughout the following, the term "file name" includes the 
  46.         possible specification of drive and user number in the form
  47.  
  48.              [<drive>][<user>][:]
  49.  
  50.         (the ":" is required and only permitted if at least one of 
  51.         <drive> or <user> is specified.  Examples
  52.  
  53.              b3:file        file on drive b, user 3
  54.              3:file         file on current drive, user 3
  55.              b:file         file on drive b, current user
  56.              file           file on current drive and user
  57.  
  58.         One prepares a file (the MAKEFILE) showing for each file in the 
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.         PMAKE     21 Jul 84                                page 2
  68.  
  69.  
  70.         system which other files it depends on (i.e. which other file 
  71.         will, when changed, require a change to this file) and the method 
  72.         of changing (or recreating).
  73.  
  74.         Consider, for example, PMAKE itself.  It was written as four 
  75.         files, PMAKE.C, GETMEM.C, and GETMOD.C.  Two of these, PMAKE.C 
  76.         and GETMOD.C include a header file, PMAKE.H.
  77.  
  78.         Let's look at the dependencies.  Our objective is to create 
  79.         PMAKE.COM.  PMAKE.COM depends on the relocatables
  80.  
  81.              PMAKE.REL
  82.              GETMEM.REL
  83.              GETMOD.REL
  84.  
  85.         generated by the C compiler
  86.  
  87.         (That's on my system.  Your C compiler might generate a different 
  88.         file type).
  89.  
  90.         In turn
  91.  
  92.              PMAKE.REL      depends on     PMAKE.C and PMAKE.H
  93.              GETMEM.REL     depends on     GETMEM.C
  94.              GETMOD.REL     depends on     GETMOD.C and PMAKE.H
  95.  
  96.         One also tells PMAKE, in the MAKEFILE, how these files are to be 
  97.         (in this case) created when there is a change to a file on which 
  98.         it depends.
  99.  
  100.              To Make        Command(s)
  101.              ----------     ---------------------------------------------
  102.              PMAKE.REL      cc pmake
  103.              GETMEM.REL     cc getmem
  104.              GETMOD.REL     cc getmod
  105.              PMAKE.COM      l80 pmake/n,pmake,getmem,getmod,strmake/e
  106.  
  107.         Suppose a change is made to PMAKE.H.  PMAKE will then compile 
  108.         PMAKE.C and GETMOD.C (GETMEM is not affected by this change) and 
  109.         link PMAKE.COM.
  110.  
  111.         As will be seen in the next section, there are several other 
  112.         features, but they are simply modifications to the above to ease 
  113.         use or to take into account some characteristics of CP/M.
  114.  
  115.         Note that the concept of dependence is not quite what most people 
  116.         think "natural".  In the above, PMAKE.C, which includes PMAKE.H, 
  117.         does not depend on PMAKE.H (i.e. if you change PMAKE.H, no 
  118.         changes are needed to PMAKE.C).  PMAKE.REL does depend on PMAKE.H 
  119.         since a change to PMAKE.H requires changing PMAKE.REL.
  120.  
  121.  
  122.  
  123.         The MAKEFILE.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.         PMAKE     21 Jul 84                                page 3
  134.  
  135.  
  136.         The MAKEFILE contains the information PMAKE needs to bring a 
  137.         system up to date.  It may contain 5 types of lines
  138.  
  139.              1.   Blank lines.
  140.              2.   Comment lines, beginning with ";".
  141.              3.   Variable definition lines, beginning with "%".
  142.              4.   Howto lines, beginning with tab.
  143.              5.   Dependency lines, beginning with any other character.
  144.  
  145.         All lines must be 128 or fewer characters.
  146.  
  147.         Blank and comment lines are simply ignored by PMAKE.
  148.  
  149.         As will be seen, howto lines may contain references to variables 
  150.         supplied when PMAKE is invoked.  Variable definition lines may 
  151.         included in the MAKEFILE to specify default values for the 
  152.         variables.  A varibale definition line consists of a "%" in the 
  153.         first position, followed by an assignment to a variable, e.g.
  154.  
  155.              %debug=-vdebug
  156.  
  157.         or a "%" simply followed by a name, e.g.
  158.  
  159.              %debug
  160.  
  161.         The latter is interpreted as being equivalent to
  162.  
  163.              %debug=debug
  164.  
  165.         Variable names consist of up to 8 characters, each of which is a 
  166.         letter, digit, or one of ".", "-", "_".  Variables may be used in 
  167.         any type of line and may be nested, but it is the users 
  168.         responsibility to insure that recursion does not take place.  To 
  169.         use a variable, simply put it's name between percent signs, e.g. 
  170.         %debug%.  The final "%" is not needed if the character after the 
  171.         variable is not one of those which may appear in a variable (or 
  172.         "%").  To put a "%" in a line, just use "%%".
  173.  
  174.         As we will see, variables may also be defined in the command 
  175.         line.  They may not be redefined.  Once a variable is defined, 
  176.         any attempt at redefinition is silently ignored.  Thus, 
  177.         definitions in the makefile may be considered defaults to be used 
  178.         if no definition of the variable is given on the command line.
  179.  
  180.         Howto lines are simply CP/M commands.  They are used to generate 
  181.         a submit file which will bring the desired files up to date.
  182.  
  183.         Finally, dependency lines contain a file name followed by a white 
  184.         space (space or tab) separated list of files on which it depends.  
  185.         Dependency lines are always converted to upper case by PMAKE. 
  186.         Each dependency line is followed by zero or more (we'll see why 
  187.         you might want zero shortly) howto lines.  If PMAKE determines 
  188.         that the file must be brought up to date, the howto lines are 
  189.         written to the output submit file, making any needed parameter 
  190.         substitutions.
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.         PMAKE     21 Jul 84                                page 4
  200.  
  201.  
  202.  
  203.         There should be no more than one dependency line for any file.  
  204.         If there is more than one, all but the first will be ignored.  
  205.         The order of the dependency lines is not otherwise significant.
  206.  
  207.         Let's look at a sample MAKEFILE.
  208.  
  209.         ; sample MAKEFILE for PMAKE
  210.  
  211.         pmake.rel       pmake.c pmake.h
  212.                         cc pmake %debug%
  213.  
  214.         getmod.rel      getmod.c pmake.h
  215.                         cc getmod %debug%
  216.  
  217.         getmem.rel      getmem.c
  218.                         cc getmem
  219.  
  220.  
  221.         pmake.com       pmake.rel getmod.rel getmem.rel
  222.                         l80 pmake/n/y,pmake,getmod,getmem/e
  223.  
  224.         When invoking PMAKE, one tells it the file(s) it is to bring up 
  225.         to date.  The command
  226.  
  227.              pmake pmake.com
  228.  
  229.         will bring the file pmake.com (and any files it depends on) up to 
  230.         date.
  231.  
  232.         Using this MAKEFILE, let's say that PMAKE determines that 
  233.         getmod.c has been modified.  It will generate the commands
  234.  
  235.              cc getmod -QDEBUG
  236.              l80 pmake/n/y,pmake,getmod,getmem,strmake/e
  237.  
  238.         (assuming no parameter has been specified when PMAKE is invoked.)
  239.  
  240.         How does PMAKE now a file has been changed?  On Unix, make checks 
  241.         the date last modified of all files.  This isn't possible in 
  242.         CP/M 2.2.  Therefore, a file attribute is used.  As distributed, 
  243.         the F1 attribute is set whenever PMAKE brings a file up to date 
  244.         and, presumably, is reset when the file is updated.  All of the 
  245.         editors I use will do this.  If the F1 attribute is unsuitable, 
  246.         PMAKE may be changed (see Installation section) to use any of the 
  247.         file attributes.
  248.  
  249.         PMAKE examines each file and places it into one of 4 categories:
  250.  
  251.              1.   File does not exist.
  252.              2.   File has the attribute set (unchanged file).
  253.              3.   File does not have the attribute set (changed file).
  254.              4.   File has been brought up to date in this run.
  255.  
  256.         A file is brought up to date under any of the following 
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.         PMAKE     21 Jul 84                                page 5
  266.  
  267.  
  268.         circumstances:
  269.  
  270.              1.   The file does not exist and there is a dependency line 
  271.                   for the file.
  272.  
  273.              2.   There is a dependency line for the file with no 
  274.                   dependencies.
  275.  
  276.              3.   Any file on which it depends has been changed or 
  277.                   brought up to date in the current run.
  278.  
  279.         All files are marked as unchanged.
  280.  
  281.         It is an error for a file to depend on another which does not 
  282.         exist and for which there is no dependency line.
  283.  
  284.         It must be understood that only files which PMAKE sees are 
  285.         candidates for all this.  The MAKEFILE might (mine, in fact does) 
  286.         contain other dependencies.  For example, my MAKEFILE for PMAKE 
  287.         contains
  288.  
  289.         pset.rel        pset.c
  290.                         cc pset
  291.  
  292.         pset.com        pset.rel
  293.                         l80 pset/n/y,pset/e
  294.  
  295.         If PMAKE is told to make pmake.com, it will never look at these 
  296.         files and the condition of, say, pset.c is immaterial.
  297.  
  298.         Now, suppose one wants to bring several programs up to date.  One 
  299.         could simply tell PMAKE to bring them all up to date in the 
  300.         command line with something like
  301.  
  302.              pmake pmake.com pset.com
  303.  
  304.         This could quickly get out of hand if there are several programs 
  305.         in the system.  The solution is to use a phony file and include a 
  306.         line like
  307.  
  308.  
  309.         Note that this example begins with a ".".  This is not really 
  310.         necessary, but will tell PMAKE that the file is phony and will 
  311.         prevent checking it's status -- it will immediately be treated as 
  312.         a file which does not exist.  Now with the command
  313.  
  314.              pmake .programs
  315.  
  316.         PMAKE will bring .programs up to date.  This is, of course, not 
  317.         very meaningful, but in order to do it PMAKE will first have to 
  318.         bring pmake.com and pset.com up to date, which is desired.
  319.  
  320.         To further simplify use of PMAKE, if no file is requested in the 
  321.         command, PMAKE will bring the phony file ".do" up to date.  One 
  322.         would normally specify
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.         PMAKE     21 Jul 84                                page 6
  332.  
  333.  
  334.  
  335.  
  336.         in the above case or
  337.  
  338.  
  339.         if only pmake.com were in the MAKEFILE allowing the simplest (and 
  340.         most common) form of the pmake command
  341.  
  342.              pmake
  343.  
  344.         Phony files have some other uses.  In some cases there will be 
  345.         more dependencies for a file than can be put on one line.  It's 
  346.         not necessary here, but the dependency for pmake.com could have 
  347.         been written
  348.  
  349.  
  350.  
  351.         pmake.com       .pmake1 .pmake2
  352.                         l80 pmake/n/y,pmake,getmod,getmem,strmake/e
  353.  
  354.         Finally, there are two special phony files, .init and .fin, used 
  355.         for initialization and completion.  If any howto lines are 
  356.         output, the generated submit file will contain the howto lines 
  357.         for .init at the beginning and those for .fin at the end.  These 
  358.         can be used to set up any environment needed before compiling and 
  359.         to restore the environment or to delete temporary files after 
  360.         compiling.
  361.  
  362.  
  363.  
  364.         Running PMAKE.
  365.  
  366.         The most common form of the PMAKE command is simply
  367.  
  368.              pmake
  369.  
  370.         This will read the file makefile.dat and bring the phony file .do up 
  371.         to date, placing the required commands in the file makef000.sub.  
  372.         A list of files which must be marked as up to date is placed in 
  373.         makefile.set.  The command
  374.  
  375.              pset makefile.set
  376.  
  377.         will now mark these files as up to date.
  378.  
  379.         In some cases, it may be necessary to specify some options to 
  380.         PMAKE.  Options are specified with a preceding "-".  Most options 
  381.         require a parameter, which may be separated from the option by 
  382.         spaces.
  383.  
  384.         Possible options are
  385.  
  386.              -f <filename>       specifies a MAKEFILE.  If omitted, 
  387.                                  makefile.dat is used.
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.         PMAKE     21 Jul 84                                page 7
  398.  
  399.  
  400.              -i                  allows continuation on certain errors.
  401.  
  402.              -n <number>         maximum size of a submit file.  This is 
  403.                                  described more fully below.
  404.  
  405.              -v <variable def>   specifies a variable definition,
  406.                                  May occur more than once.  The 
  407.                                  definition is in the same form as in the 
  408.                                  file, but without the leading "%" (e.g. 
  409.                                  -vdebug=-qdebug).  If the definition 
  410.                                  contains spaces, it must be enclosed in 
  411.                                  quotes or appostrophes.
  412.  
  413.         In addition to options, the PMAKE command may contain names of 
  414.         files to be brought up to date.  If none is specified, the 
  415.         (phony) file .do will be brought up to date.
  416.  
  417.         The -n option requires more explanation.  Normally CP/M imposes a 
  418.         limit of 128 lines on a submit file.  This may not be enough.  
  419.         PMAKE will, if a submit file gets too large, generate a SUBMIT 
  420.         command for a new file and start placing commands in this new 
  421.         file.  The files generated are makef000.sub, makef001.sub, ...
  422.         Since the howto lines may contain submits (if one uses a SUBMIT 
  423.         processor such as SUB2 or SUPERSUB which allows nesting), PMAKE 
  424.         must know how many lines it can put into a the submit file.  As 
  425.         distributed, the default is 96, allowing reasonable nesting.  
  426.         This may be changed with the -n option.  If you are using a 
  427.         memory resident SUBMIT processor, such as EX or ZEX which do not 
  428.         allow nesting, specify "-n 0" to allow any number of lines.
  429.  
  430.         If an error is encountered or if everything is up to date and 
  431.         does not require marking, the file $$$.sub will be deleted.  This 
  432.         makes it very easy to embed PMAKE in a submit file which then 
  433.         submits the generated file and executes PSET.
  434.  
  435.  
  436.  
  437.         Installation and Field Modification.
  438.  
  439.         A few locations in pmake.com may have to be changed with DDT:
  440.  
  441.              0109H          The file attribute bit which is to be used to 
  442.                             indicate changed files.  0=F1, 1=F2, ..., 
  443.                             7=F8, 8=T1, 9=T2, 10=T3.  Distributed as 0.  
  444.                             The byte at 0103H in PSET.COM must be changed 
  445.                             to the same value.
  446.  
  447.              010BH-010CH    The maximum number of lines to be put into a 
  448.                             SUBMIT file (actually, one more line may be 
  449.                             put into the SUBMIT file.  If your SUBMIT 
  450.                             processor does not allow nesting,  this 
  451.                             should be changed to 0FFFFH.  Distributed as 
  452.                             96 (60H).
  453.  
  454.              010DH-0115H    The name of your SUBMIT processor, terminated 
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.         PMAKE     21 Jul 84                                page 8
  464.  
  465.  
  466.                             by a zero byte.  Distributed as "SUB".
  467.  
  468.  
  469.  
  470.  
  471.         Modification and Enhancement.
  472.  
  473.         Source code is provided for use with the Software Toolworks C80 
  474.         compiler.  However, the program was compiled with a private, 
  475.         proprietary run time system so a fair amount of work will be 
  476.         required to compile on your system.  Major considerations are
  477.  
  478.              1.   The file handling routines process the drive/user 
  479.                   specification.  If your's does not, you will have to 
  480.                   either do without it or make modifications.
  481.  
  482.              2.   The function "error" displays a message, preceded by 
  483.                   the program name.
  484.  
  485.              3.   The function "error" and the function "exit" (if called 
  486.                   with a nonzero argument) delete a:$$$.sub.  This is 
  487.                   used in the error handling.
  488.  
  489.              4.   The file handling routines create a new file with a 
  490.                   temporary name and rename it when closed.  This is very 
  491.                   different from most systems.
  492.  
  493.              5.   The setflg function sets various file modes.  In this 
  494.                   program, the only one of interest is "d", which deletes 
  495.                   the file when it is closed.
  496.  
  497.  
  498.         This list is not exhaustive.  Beware.
  499.  
  500.         <End of Document>
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.