Phoenix CD 2.0/Phoenix_CD.cdr/02a/pctmk.zip/PCTMK.DOC

Text File | 1986-01-13 | 24KB | 757 lines

                                      PCTMK

                          A tool for program development



                                 G. W. Glasscock
                            15617 S. E. Fairwood Blvd.
                                Renton, Wa.  98058
                                  [phone]























        Version 1.0                                      January 1986


        Copyright (c) 1986, G. W. Glasscock,  All rights reserved.


                                    DISCLAIMER

        The author has taken due care in preparing this manual and
        accompanying program to ensure it operates as described.
        However, the author makes no expressed or implied warranty of any
        kind with regard to this program or the documentation in the
        manual.  Under no circumstances shall the author be liable for
        incidental or consequential damages arising from the use or
        inability to use this program.











































                                                                 Page 1

        INTRODUCTION

        PCTMK is a tool for conveniently building a program or a set of
        programs ensuring that the current version of a program reflects
        all changes made to any of the source files comprising that
        program.  It accomplishes this task efficiently by compiling only
        those source files which have been modified.  A command entered
        at the DOS command prompt is used to invoke PCTMK and provide the
        name of the target file to be constructed.  The user supplies the
        detailed knowledge needed to construct the target file through
        rules which he places in a "makefile".

        If the modular approach to program development is used, it is
        easy to forget which source files have been modified and which
        source files make up a particular program.  Since the user of
        PCTMK must create a "makefile", he has conveniently documented
        the steps necessary to build his program.

        PCTMK provides programmers who use PCDOS [1] and MS-DOS [2] an
        introduction to the capabilities of "make" which was developed by
        S. I. Feldman of Bell Laboratories for the UNIX [3] operating
        system.  PCTMK is intended for use with version 2.0 and later
        releases of PCDOS or MS-DOS.  PCTMK will work with most compilers
        and assemblers which run on these operating systems.

        Although PCTMK provides the basic capabilities needed for a
        "make" program, it is missing several advanced features useful in
        a complete "make" program.  PCMK, a superset of PCTMK, provides
        these useful advanced features for only $21.00.

                Wild card character expansion
                Full path name support
                User defined macros
                Access to DOS environment via macros
                Access to internally generated macros
                Built-in rules defined by the user
                Printed manual with examples (40 pages)












        1. PCDOS is a Trademark of International Business Machines
        2. MS-DOS is a Trademark of Microsoft Inc.
        3. UNIX is a Trademark of Bell Laboratories
                                                                Page 2

        BASIC OPERATION

        The basic function of PCTMK is to produce a target file which is
        current or up-to-date.  It accomplishes this by automatically
        executing all commands necessary to produce the updated target
        file.  A target file is defined as "current" if its date and time
        are more recent than any file on which it depends.

        PCTMK determines what needs to be done by examining the "make-
        file".  This "makefile" contains user supplied rules.  These
        rules contain a list of files that a target depends upon and a
        list of the commands necessary to create the target file.  The
        date and time of a file's last modification is obtained from DOS.
        This date and time must be accurate if PCTMK is to operate
        correctly.

        As an illustration, suppose a program called "mypgm.exe" is built
        from three assembly language files: "f1.asm", "f2.asm", and
        "f3.asm".  Also, assume that a file of macro definitions
        "mdefs.mac" is "included" in the assembly language files "f2.asm"
        and "f3.asm".  Using only the basic capabilities of PCTMK, the
        four rules shown below describe the "makefile" required to build
        the program "mypgm.exe".

            mypgm.exe : f1.obj f2.obj f3.obj
                    link f1.obj f2.obj f3.obj, mypgm.exe, NUL;

            f1.obj : f1.asm
                    masm f1.asm;

            f2.obj : f2.asm mdefs.mac
                    masm f2.asm;

            f3.obj : f3.asm mdefs.mac
                    masm f3.asm;


        The first rule states that "mypgm.exe" depends on "f1.obj",
        "f2.obj", and "f3.obj".  The second line of this rule is the DOS
        command or program to run if "mypgm.exe" is out of date with any
        of the files on which it it depends.  The second rule states that
        "f1.obj" depends upon "f1.asm" and provides a command to create
        "f1.obj".  Likewise, the third rule states that "f2.obj" depends
        on "f2.asm" and "mdefs.mac".  The second line of this rule is the
        DOS command which will create an updated "f2.obj".  The fourth
        rule is similar to the third rule.

        If these four rules are placed in a file named "MAKEFILE", the
        command

            PCTMK

                                                                 Page 3

        is sufficient to cause "mypgm.exe" to be recreated after a change
        had been made to any of the source files, "f1.asm", "f2.asm",
        "f3.asm", or "mdef.mac".

        Let's assume that after running "mypgm", it is determined that a
        modification to the file "f2.asm" is necessary to correct a
        problem.  After making this modification, PCTMK is executed.
        From the four rules in "MAKEFILE" and the date and times of the
        target and dependency files, PCTMK discovers that "f2.asm" has
        been modified and executes the command associated with rule 3.
        The command associated with rule 1 will then be executed because
        "f2.obj" is now out of date.  The commands associated with rules
        2 or 4 are not executed because the targets in these rules are
        current with their dependency files.






































                                                                Page 4

        MAKEFILE SYNTAX

        The overall syntax of a "makefile" is relatively simple.  It
        contains lines of ASCII text by which the user can construct
        rules.  A rule is an entry in the "makefile" which states depend-
        ency condition(s).  It also defines actions to be taken should
        that condition be met.  Blank lines are allowed between rules.

        The sharp "#" character is used to start a comment.  When a sharp
        "#" is found, the line is effectively ended because the sharp and
        all characters following the sharp up to the end-of-line are
        ignored.  If it is necessary to use a sharp in a rule, it can be
        "escaped"; the sequence "\#" is replaced by a sharp and does not
        signify the start of a comment.

        Non-comment lines may be continued by placing a backslash "\"
        character at the end of the line.  In this case, the backslash
        followed by an end-of-line is ignored so that the first character
        of the next line immediately follows the character which preceded
        the backslash.

        To define a rule within the "makefile", use the following syntax:

        target : [dependent ... ] [; command]
        [(tab) command]
            ...

        Items inside brackets are optional and may be omitted.  The
        appearance of three dots "..." means that the previous item may
        be repeated.  Targets and dependents are strings of letters,
        digits, and special characters delimited by white space.  White
        space must both precede and follow the colon.  White space is
        defined as one or more blanks or tab characters.  Targets and
        dependents can appear in more than one rule.

        Because targets and dependents refer to DOS file names which may
        or may not exist, you would be wise to restrict your use of
        special characters to those which can be used in valid DOS file
        names.

        A command is any string of characters terminating with an
        unescaped sharp "#" or the end-of-line sequence.  Usually com-
        mands appear on separate lines which begin with a tab character.
        However, one command may be placed at the end of a target/
        dependency line if it is preceded by a semicolon.  The commands
        of a rule are executed in the order of appearance provided at
        least one of the dependents is more recent than the target.

        The first string in a DOS command line identifies the file/
        command to be executed.  Three types of files, ".COM", ".EXE",
        and ".BAT", as well as commands which are internal to the DOS
        command line processor, can be run under DOS.  PCTMK handles all
                                                                 Page 5

        of these commands.  It is not necessary to provide the suffix of
        the command to be run.  The syntax of the command should conform
        to DOS conventions, but depends to a large extent upon the
        command being executed.

        A comment may be placed at the end of a target or command line by
        using the sharp "#" to signal the start of the comment.  Both
        target lines and command lines that do not end with a comment may
        be continued.











































                                                                Page 6

        PCTMK COMMAND

        pctmk [-f makefile] [-s] [-i] [-n] [names]

        Any or all of the command line parameters may be omitted.  The
        sequence in which parameters are entered has no significance for
        their meaning.  Command line parameters are of two types: options
        and target names.  The case of the characters on the command line
        is not significant.

        Options

        The four PCTMK options are:

            -f "makefile"  is the name of a file which contains the rules
                that you want PCTMK to process.  If this option is
                omitted, PCTMK uses the file "MAKEFILE" in the current
                directory.

            -s  specifies that PCTMK call the system's command processor
                "COMMAND.COM" to execute all commands.

            -i  requests that error codes returned by commands be
                ignored.  Normally, PCTMK aborts when a command it
                executes generates an error return.  When this option is
                present, it will continue processing.  This option is
                useful when working with commands that set the "exit"
                code incorrectly.

            -n  requests that PCTMK only print the commands that would be
                executed but not execute them.  This option allows you to
                see what commands PCTMK would issue without actually
                executing them.

        Target Names  [names]

        For each target name present on the command line, PCTMK attempts
        to create an updated version of that target.  If no targets are
        present on the command line, the first target found in the
        "makefile" will be updated.












                                                                 Page 7

        OPERATIONAL DETAILS

        The information provided in this section will help you understand
        the operation of PCTMK so that you can better take advantage of
        this tool.

        Command Execution

        PCTMK provides two options for executing or running commands.
        Direct execution is the preferable method because PCTMK can
        access the exit code of the DOS command it executes and halt when
        that command (i.e. a compiler or assembler) detects errors.  Of
        course, access to the exit code is useless unless it is set
        accurately by the command being executed.

        You may provide the full path name for a file to be executed.  If
        only the command name is given, PCTMK tries to locate a command
        by first looking in the current directory, then in the
        directories identified by the DOS environment variable, PATH.
        The full path name is necessary to execute a command which is not
        in the current directory or in a directory identified by the
        environment PATH variable.

        Commands can also be executed by first calling the DOS command
        line interpreter which will then execute the command.  There are
        three reasons PCTMK uses this method for executing commands.
        Since some commands are internal to the DOS command processor or
        have special syntactical conventions, they must be executed by
        the DOS command line processor.  Appendix A contains a list of
        the commands PCTMK always executes via the DOS command line
        processor.  PCTMK does not itself handle redirection of input,
        redirection of output, or pipes.  If a command line contains any
        of the characters "<", ">", or "|", that command line is executed
        via the DOS command line processor.  Any command which has a
        ".BAT" suffix is executed via the DOS command line processor.
        The problem with executing commands via the DOS command processor
        is that the exit code of the command is not available to PCTMK.

        PCTMK WILL CONTINUE NORMALLY WHEN A COMMAND EXECUTED BY THE DOS
        COMMAND LINE INTERPRETER ABORTS BECAUSE PCTMK IS NOT INFORMED OF
        THIS ABNORMAL CONDITION.

        By using the "-s" option, you can force PCTMK to call the DOS
        command line processor to execute all commands.

        Size of Commands

        DOS restricts the parameter portion of a command line to 126
        characters.  If the command is to be executed via the command
        line processor, the complete command may not exceed 123
        characters.  Several techniques have been developed to cope with
        this limit.  Some of the DOS commands, (i.e.  copy and backup)
                                                                Page 8

        avoid this problem by expanding wild card characters as a part of
        the command.  "LINK" allows parameters to be input from a file as
        an alternative to the DOS command line.  For some commands,
        simply running the command multiple times will avoid this limit.

        PCTMK helps cope with this situation by allowing one target to
        appear in multiple rules.  For each rule the commands associated
        with that rule are executed if the target is out of date with any
        of the dependencies of that rule.

        Support of Path Names

        PCTMK allows all file names to include a full path qualifier.
        However, some assemblers and compilers do not allow file names
        which include a path.  This is universally true for compilers and
        assemblers which were produced before DOS 2.0 was available.
        Even the DOS 2.0 command processor has restrictions on the use of
        file names which contain a path prefix.

        Lower Case vs Upper Case

        Where possible PCTMK maintains the distinction between upper and
        lower case letters.  That is the string "abcd" is not identical
        to the string "ABCD".  However, PCTMK must deal with DOS which
        converts the lower case letters to upper case in file names.  As
        a result, lower case letters in target names are converted to
        uppercase.

























                                                                 Page 9

        EXAMPLE OF USAGE

        The previous sections have described the basic operation of
        PCTMK, the syntax of the "makefile", and the command line used to
        invoke PCTMK.  This section presents an example using PCTMK and a
        product from C Ware.  The "makefile" illustrated here uses an
        assembler and a "C" compiler.  This "makefile" happens to be the
        one used to develop PCTMK.

        #   Rule 1
        pctmk.exe : pcmk.o parser.o builtin.o ffind.o fetenv.o
                bind pcmk.o parser.o builtin.o ffind.o fetenv.o a:exec.o \
        -opctmk -p -s4000

        #   Rule 2
        pcmk.o : pcmk.c defs.h
                c88 pcmk.c

        #   Rule 3
        parser.o : parser.c defs.h
                c88.exe parser.c

        #   Rule 4
        builtin.o : builtin.c  defs.h
                c88 builtin.c

        #   Rule 5
        ffind.o : ffind.a
                asm88 ffind.a

        #   Rule 6
        fetenv.o : fetenv.a
                asm88 fetenv.a


        Rule 1 describes how to build "pctmk.exe".  Because this is the
        first target in the "makefile", it is chosen whenever a target is
        omitted from the PCTMK command line.  The dependency part of this
        rule list the five (5) object files on which "pctmk.exe" depends
        that are subject to change.

        The second line of this rule starts with a tab and is the command
        to run if one or more of the dependencies are out-of-date with
        "pctmk.exe".  This line is continued because the backslash "\" at
        the end of the line immediately precedes the end-of-line
        sequence.  When this command is executed PCTMK looks for "bind"
        in the current directory, then the directories specified by the
        environment variable PATH.  The parameters for this command are
        the object files on which "pctmk.exe" depends, "a:exec.o" and the
        three option flags.  The "-o" option supplies the name for the
        output of "bind".  The file "a:exec.o", which is part of the
        compiler package, is needed to construct "pctmk.exe".  It is not
                                                                Page 10

        necessary to include this file in the dependency list since it
        does not change.

        Before deciding to execute the command in rule 1, PCTMK must
        ensure that all of the dependents are also current.  To do this,
        PCTMK attempts to "make" each of the dependents.  It will find
        rules for each of these sub-targets.  Rule 2 states that "pcmk.o"
        depends upon "pcmk.c" and "defs.h".  If either of the files
        "pcmk.o" or "defs.h" are out-of date with "pcmk.o", the command
        which is the second line of rule 2 will be run to re-build
        "pcmk.o".  Rules 3 and 4 are similar to rule 2.  Note that the
        full name of the compiler, "c88.exe", is present in the command
        portion of rule 3.

        Rule 5 states that "ffind.o" depends upon "ffind.a".  If
        "ffind.o" is out-of-date with "ffind.a" the command show in the
        second line of this rule will be executed.  Rule 6 is similar to
        rule 5.

        You should be aware that PCTMK will try to "make" all of the file
        names which it encounters in a dependency list.  Even the source
        files: "pcmk.c", "parser.c", "builtin.c", "ffind.a", "fetenv.a",
        and "defs.h".  The attempt to "make" these source files will not
        succeed because there are no rules present that create these
        source files.  Because of this feature, PCTMK will work in
        environments where program generators and precompilers are used.


























                                 Appendix A                     Page 11

        DOS COMMANDS

        The commands listed below are always executed via the DOS command
        processor.  The exit code is not available to PCMK when the DOS
        command processor is called to execute a command.

                    backup                  break
                    chdir                   cd
                    chkdsk                  cls
                    comp                    copy
                    ctty                    date
                    del                     erase
                    dir                     echo
                    for                     if
                    mkdir                   md
                    more                    pause
                    print
                    ren                     rename
                    restore
                    rmdir                   rd
                    sort                    time
                    type                    ver
                    verify                  vol





























                                 Appendix B                     Page 12

        DISTRIBUTION OF PCTMK

        PCTMK and its document is available at no cost to those who want
        to use it.  Please help distribute this software by copying both
        the program and the electronic form of the manual for anyone who
        may want to use this program.  The only restriction on copying
        this software is that the electronic form of the manual be copied
        along with the program, and that neither the program nor the
        manual be modified in any way.  I have placed PCTMK on several
        computer bulletin boards and I hope it will spread to additional
        bulletin boards.  PCTMK is not directly available from the
        author.  Copies of PCTMK must be obtained from either a bulletin
        board or a friend.

        My motivation for making this program available at no cost is to
        help market PCMK which is a superset of PCTMK and provides the
        user many useful and convenient features.

            -    Wild card character expansion
            -    Full path name support
            -    User defined macros
            -    Access to DOS environment via macros
            -    Access to internally generated macros
            -    Built-in rules defined by the user
            -    Printed manual with examples (40 pages)

        A copy of PCMK and its 40 page printed manual are available from
        the author for $21.00.  A check or money order for the full
        amount of the order must accompany all orders.  Washington state
        residents include 8.1% sales tax.

        G. W. Glasscock
        15617 S. E. Fairwood Blvd.
        Renton, Wa.  98058
        [phone]

        Because of the low cost of this product, I will not be able to
        return your long distance telephone calls.  However, I am willing
        to talk with you if you pay for the call.  I am available most
        evenings 6:00 PM to 9:00 PM PST.  I will answer all mail that I
        receive concerning PCMK or PCTMK.