home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 196.lha / DMake_v1.0 / dmake.doc < prev    next >
Text File  |  1988-12-27  |  7KB  |  226 lines
  1.  
  2.                  DMAKE.DOC
  3.  
  4.                ALPHA RELEASE V1.00 5-Jan-1988
  5.  
  6.                *ALPHA* *ALPHA* *ALPHA*
  7.  
  8.     NOTE!!    This is an alpha version.  I have yet to add all the features
  9.     I will eventually want (like \ line continuation).  In fact, that's
  10.     the whole point of saying 'alpha' above ... only people interesting
  11.     in exploring and testing the radical features of DMake should be
  12.     using this release.
  13.  
  14.     You MUST be familar with 'make' to understand these instructions.
  15.  
  16.     The default file is 'DMakefile'.  Options are:
  17.  
  18.     -a            force a time comparisons to fail
  19.     -f filename        use this instead of DMakefile
  20.     -n            don't actually execute the lines
  21.     -v    (debugging)
  22.  
  23.                    RADICAL FEATURES
  24.  
  25.     We are all familar with the UNIX make utility.    We all hate it.
  26.     This program is the beginnings of my solution to the problem.
  27.  
  28.     (1) Multiple dependancies on the left:
  29.  
  30.         ram:a.o ram:b.o ram:c.o : a.c b.c c.c
  31.         cc %(right) -o %(left)
  32.  
  33.     (2) Wildcards with virtual reverse mapping (I just made that word
  34.         up).  In the example below, a directory search is used to
  35.         resolve the *.c wildcard in the line "ram:*.o : *.c".  The left
  36.         side is then replaced with the resolved list changing the order
  37.         according to the wildcard specification ( *.c -> ram:*.o ).
  38.         NOTE that the two wildcard specifications have to contain the
  39.         same wildcards in the same order.  NO directory search is made
  40.         for the objects ... the names are generated from the source.
  41.  
  42.         Finally, note the line 'ram:*.o : *.asm'... note that this
  43.         combined with 'ram:*.o : *.c' specifies a joinin of the two
  44.         specs ... the 'ram:*.o' spec in the linker line will contain
  45.         ALL the objects.
  46.  
  47.         $(EXE) : ram:symbols.m ram:*.o
  48.         ln +Q %(ram:*.o) -o $(EXE)
  49.  
  50.         ram:*.o :    *.c
  51.         cc +Iram:symbols.m %(right) -o %(left)
  52.  
  53.         ram:*.o :    *.asm
  54.         as %(right) -o %(left)
  55.  
  56.         ram:symbols.m : include:symbols.m
  57.         copy %(right) %(left)
  58.  
  59.     (3) $ and % variables.  $(SYMBOL) is the standard way to specify
  60.         a symbol name.  %(symbol) is used to macro-insert wildcard
  61.         symbols that appear on the right.  Two special %
  62.         symbols exist:  %(left) contains the stuff on the left and
  63.         %(right) contains the stuff on the right.
  64.  
  65.         Note the difference between these two lines:
  66.  
  67.         all:    ram:*.o
  68.         ln %(ram:*.o) -o c:blah
  69.  
  70.         ram:*.o : *.c
  71.         cc %(*.c) -o %(left)
  72.  
  73.         The difference is that the symbol in the linker line contains
  74.         ALL the objects while the symbol in the compiler line contains
  75.         only the CURRENT .c file being compiled.  The reason is explained
  76.         below, but it ought to be obvious.
  77.  
  78.         Note that only variables on the right of the ':' may be
  79.         specified via their name in a %() macro.  You can refer to
  80.         the left side with %(left), or the entire right side with
  81.         %(right).
  82.  
  83.     (4) Another form that might be useful is this:
  84.  
  85.         ram:*.o : *.c *.h
  86.         cc %(*.c) -o %(left)
  87.  
  88.         Carefully now:  Each .O file is dependant on its .C file.
  89.         Each .O file depends on ALL OF THE .H FILES.
  90.  
  91.  
  92.                 SPECIFICATION OF DEPENDANCIES
  93.  
  94.     The specification of dependancies might seem a bit confusing to
  95.     you.  Lets take a general example:
  96.  
  97.     a b c d  : r s t u
  98.  
  99.     The rule is as follows:  UNTIL one side is exhausted, one item on
  100.     the left is dependant on one item on the right.  That is, a : r,
  101.     b : s, c : t  etc....
  102.  
  103.     If there are EXTRA arguments on the right, each argument is applied
  104.     to ALL THE ARGUMENTS ON THE LEFT.  If I had a 'v' above it would be
  105.     equivalent to  a : v, b : v, c : v, d : v.
  106.  
  107.     EXTRA arguments on the left are disalloweds except for two cases:
  108.  
  109.     blah :            - blah depends on nothing
  110.     a b c d e : x        - a : x, b : x, c : x , d : x, etc....
  111.     *.c : *.h        - WRONG THIS DOES NOT SPECIFY ALL THE
  112.                   .C FILES DEPENDANT ON THE .H FILES!!!
  113.  
  114.     *.o : *.c *.h        - This does, as well as saying that each
  115.                   object depends on its associated .C file
  116.  
  117.             EXECUTION ORDER & VARIABLES
  118.  
  119.     Whenever possible, a depth first execution order will be taken:
  120.  
  121.     all:    ram:symbols.m    $(OBJS)
  122.         ln "%(OBJS)" -o c:blah
  123.  
  124.     $(OBJS): *.c
  125.         cc +Iram:symbols.m %(right) -o %(left)
  126.  
  127.     ram:symbols.m : include:symbols.m
  128.         copy %(right) %(left)
  129.  
  130.     Here, the symbols are guarenteed to be copied before the objects
  131.     are compiled.  Variables work somewhat like the normal make.  You
  132.     can create variables with '=':
  133.  
  134.     SRCS =    a.c b.c c.c
  135.     OBJS =    $(SRCS:"*.c":"ram:*.o")             (i.e. ram:a.o, ram:b.o ...)
  136.  
  137.     When used in the Makefile, use $(SYMBOL) to get an exact replacement,
  138.     %(SYMBOL) to get an indirect replacement.  That is,
  139.  
  140.     OBJS = ram:*.o
  141.  
  142.     all: $(OBJS)
  143.         ln %(OBJS) ...
  144.  
  145.     Here, %(OBJS) finds "ram:*.o" then re-applies it to %, giving you
  146.     the object list.
  147.  
  148.     The other little item you just saw is global name replacement on
  149.     symbol inclusion:
  150.  
  151.         $(SYMNAME:"oldwild":"newwild")      -if the symbol is a list of
  152.                          files and not a wildcard
  153.  
  154.         %(SYMNAME:"oldwild":"newwild")      -if the symbol is a wildcard
  155.                          on the righthand side of
  156.                          the dependancy.
  157.  
  158.     Causes the symbol to be parsed (space delimits) and each filename
  159.     rung through the grinder.  Each filename is matched with the left
  160.     wildcard and then modified according to the right wildcard.  Here
  161.     are two common DMakefiles:
  162.  
  163.     SRCS =    a.c b.c c.c d.c e.c
  164.     OBJS =    $(SRCS:"*.c":"ram:*.o")
  165.  
  166.     all: $(OBJS)
  167.         ln $(OBJS) -o c:blah
  168.  
  169.     $(OBJS) : $(SRCS)
  170.         cc %(right) -o %(left)
  171.  
  172.                 ---
  173.  
  174.     SRCS =    *.c
  175.     OBJS =    ram:*.o
  176.  
  177.     # note, in the line below you must specify $(SRCS) on the right
  178.     # hand side of you want %(SRCS) to expand properly
  179.  
  180.     all: $(OBJS) $(SRCS)
  181.         ln %(OBJS) -o c:blah
  182.         Echo "%(SRCS)"
  183.  
  184.     $(OBJS) : $(SRCS)
  185.         cc %(right) -o %(left)
  186.  
  187.     arc: $(SRCS) c:blah
  188.         -delete ram:x.arc
  189.         arc a ram:x %(right)
  190.  
  191.  
  192.                 ALPHA 'TO-DO'
  193.  
  194.     There are probably lots of bugs.  The bigest one now is the lack
  195.     of error detection... it won't stop if it comes across an error.
  196.     You *can* ^C dmake though ... no problem.
  197.  
  198.     DMake is currently extremely slow ... extremely extremely slow.
  199.     I am not releasing source yet (cause it's a mess).  You just
  200.     wouldn't BELIEVE what I had to go through!
  201.  
  202.     DMake currently uses Execute() to run commands.  Error codes are
  203.     ignored.  However, you *can* 'cd' ... this is handled internally.
  204.     The original directory can be returned to via 'cd' with no argument.
  205.  
  206.     Since Execute() is used, command lines that are too long get
  207.     chopped.  Eventually there will be no limit (for non BCPL program).
  208.     But, since 'cd' is internal, you can sometimes shorten the link
  209.     line.  In the example below we use the wildcard modification
  210.     feature to modify ram:*.o to just *.o in the link line after having
  211.     CD'd to ram:.
  212.  
  213.     OBJS = ram:*.o
  214.     SRCS = *.c
  215.  
  216.     $(EXE): $(OBJS)
  217.         cd ram:
  218.         ln %(right:"ram:*":"*") -lc32 -o $(EXE)
  219.         cd
  220.  
  221.     $(OBJS): $(SRCS)
  222.         cc %(right) -o %(left)
  223.  
  224.  
  225.  
  226.