utils.doc

一些网络上用到的知识

measure of flexibility in constructing makefiles. Rules and macros can be
"conditionalized" so that a command-line macro definition (using the -D
option) can enable or disable sections of the makefile.

The format of these directives parallels, but is more extensive than, the
conditional directives allowed by Turbo Pascal:

   !if expression
     [ lines ]
   !endif

   !if expression
     [ lines ]
   !else
     [ lines ]
   !endif

   !if expression
     [ lines ]
   !elif expression
     [ lines ]
   !endif

The conditional directives form a group, with at least an !if directive
beginning the group and an !endif directive closing the group.

The expression allowed in an !if or an !elif directive uses a syntax
similar to that found in the C programming language. The expression is
evaluated as a simple 32-bit signed integer expression.

Numbers can be entered as decimal, octal, or hexadecimal constants. For
example, these are legal constants in an expression:

   4536       # decimal constant
   0677       # octal constant (note the leading zero)
   0x23aF     # hexadecimal constant

and any of the following unary operators:

   -     negation
   ~     bit complement
   !     logical not

An expression can use any of the following binary operators:

   +     addition
   -     subtraction
   *     multiplication
   /     division
   %     remainder
   >>    right shift
   <<    left shift
   &     bitwise and
   |     bitwise or
   ^     bitwise exclusive or
   &&    logical and
   ||    logical or
   >     greater than
   <     less than
   >=    greater than or equal to
   <=    less than or equal to
   ==    equality
   !=    inequality

An expression can contain the following ternary operator:

   ? :   The operand before the ? is treated as a test.

         If the value of that operand is nonzero, then the second
         operand (the part between the ? and the colon) is the
         result. If the value of the first operand is zero, the
         value of the result is the value of the third operand
         (the part after the :).

Parentheses can be used to group operands in an expression. In the absence
of parentheses, binary operators are grouped according to the same
precedence given in the C language.

Grouping is from left to right for operators of equal precedence, except
for the ternary operator (? :), which is right to left.

Macros can be invoked within an expression, and the special macro $d() is
recognized. After all macros have been expanded, the expression must have
proper syntax. Any words in the expanded expression are treated as errors.

The error directive (!error) causes MAKE to stop and print a fatal
diagnostic containing the text after !error. It takes the format

   !error [any_text]

This directive is designed to be included in conditional directives to
allow a user-defined abort condition. 

The undefine directive (!undef) causes any definition for the named macro
to be forgotten. If the macro is currently undefined, this directive has no
effect. 

 Using MAKE
============

You now know a lot about how to write makefiles; now's the time to learn
how to use them with MAKE. The simplest way to use MAKE is to type the
command

   MAKE

at the MS-DOS prompt. MAKE then looks for MAKEFILE; if it can't find it, it
looks for MAKEFILE.MAK; if it can't find that, it halts with an error
message.

You can specify a file with the -f option:

   MAKE -fstars.mak

The general syntax for MAKE is

   make option option ... target target ...

where option is a MAKE option (discussed later) and target is the name of a
target file to be handled by explicit rules.

If the command line does not include any target names, MAKE uses the first
target file mentioned in an explicit rule. If one or more targets are
mentioned on the command line, they will be built as necessary.

Here are some more examples of MAKE command lines:

   make -n -fstars.mak
   make -s
   make -Iinclude -DTURBO=c:\tp5\project


 The BUILTINS.MAK File
-----------------------

As you become familiar with MAKE, you will find that there are macros and
rules (usually implicit ones) that you use again and again. You've got
three ways of handling them. First, you can put them in every makefile you
create. Second, you can put them all in one file and use the !include
directive in each makefile you create. Third, you can put them all in a
file named BUILTINS.MAK.

Each time you run MAKE, it looks for a file named BUILTINS.MAK; if it finds
the file, MAKE reads it in before handling MAKEFILE (or whichever makefile
you want it to process).

The BUILTINS.MAK file is intended for any rules (usually implicit rules) or
macros that will be commonly used in files anywhere on your computer.

There is no requirement that any BUILTINS.MAK file exist. If MAKE finds a
BUILTINS.MAK file, it interprets that file first. If MAKE cannot find a
BUILTINS.MAK file, it proceeds directly to interpreting MAKEFILE (or
whatever makefile you specify).


 How MAKE Searches for Files
-----------------------------

MAKE will search for BUILTINS.MAK in the current directory or in the exec
directory if your computer is running under DOS 3.x. You should place this
file in the same directory as the MAKE.EXE file.

MAKE always searches for the makefile in the current directory only. This
file contains the rules for the particular executable program file being
built. The two files have identical syntax rules.

MAKE also searches for any !include files in the current directory. If you
use the -I (Include) option, it will also search in the specified
directory.


 MAKE Command-Line Options
---------------------------

   -Didentifier   Defines the named identifier to the string consisting of
                  the single character 1.

   -Diden=string  Defines the named identifier iden to the string after
                  the equal sign. The string cannot contain any spaces or
                  tabs.

   -Idirectory    MAKE will search for include files in the indicated
                  directory (as well as in the current directory).

   -Uidentifier   Undefines any previous definitions of the named
                  identifier.

   -s             Normally, MAKE prints each command as it is about to be
                  executed. With the -s option, no commands are printed
                  before execution.

   -n             Causes MAKE to print the commands, but not actually
                  perform them. This is useful for debugging a makefile.

   -ffilename     Uses filename as the MAKE file. If filename does not
                  exist and no extension is given, tries filename.MAK.

   -? or -h       Prints help message.


 MAKE Error Messages
---------------------

 Fatal Errors

Don't know how to make XXXXXXXX
   This message is issued when MAKE encounters a nonexistent file name in
   the build sequence, and no rule exists that would allow the file name to
   be built.

Error directive: XXXX
   This message is issued when MAKE processes an #error directive in the
   source file. The text of the directive is displayed in the message.

Incorrect command line argument: XXX
   This error occurs if MAKE is executed with incorrect command-line
   arguments.

Not enough memory
   This error occurs when the total working storage has been exhausted. You
   should try this on a machine with more memory. If you already have 640K
   in your machine, you may have to simplify the source file.

Unable to execute command
   This message is issued after attempting to execute a command. This could
   be a result of the command file not being found, or because it was
   misspelled. A less likely possibility is that the command exists but is
   somehow corrupted.

Unable to open makefile
   This message is issued when the current directory does not contain a
   file named MAKEFILE.


 Errors

Bad file name format in include statement
   Include file names must be surrounded by quotes or angle brackets. The
   file name was missing the opening quote or angle bracket.

Bad undef statement syntax
   An !undef statement must contain a single identifier and nothing else as
   the body of the statement.

Character constant too long
   Character constants can be only one or two characters long.

Command arguments too long
   The arguments to a command executed by MAKE were more than 127
   characters--a limit imposed by DOS.

Command syntax error
   This message occurs if

      o the first rule line of the makefile contained any leading
        whitespace.

      o an implicit rule did not consist of .ext.ext:.

      o an explicit rule did not contain a name before the : character.

      o a macro definition did not contain a name before the = character.

Division by zero
   A divide or remainder in an !if statement has a zero divisor.

Expression syntax error in !if statement
   The expression in an !if statement is badly formed--it contains a
   mismatched parenthesis, an extra or missing operator, or a missing or
   extra constant.

File name too long
   The file name given in an !include directive was too long for MAKE to
   process. File path names in MS-DOS must be no more than 78 characters
   long.

Illegal character in constant expression X
   MAKE encountered some character not allowed in a constant expression. If
   the character is a letter, this indicates a (probably) misspelled
   identifier.

Illegal octal digit
   An octal constant was found containing a digit of 8 or 9.

Macro expansion too long
   A macro cannot expand to more than 4096 characters. This error often
   occurs if a macro recursively expands itself. A macro cannot legally
   expand to itself.

Misplaced elif statement
   An !elif directive was encountered without any matching !if directive.

Misplaced else statement
   An !else directive was encountered without any matching !if directive.

Misplaced endif statement
   An !endif directive was encountered without any matching !if directive.

No file name ending
   The file name in an include statement was missing the correct closing
   quote or angle bracket.

Redefinition of target XXXXXXXX
   The named file occurs on the left-hand side of more than one explicit
   rule.

Unable to open include file XXXXXXXXX.XXX
   The named file could not be found. This could also be caused if an
   include file included itself. Check whether the named file exists.

Unexpected end of file in conditional started on line #
   The source file ended before MAKE encountered an !endif. The !endif was
   either missing or misspelled.

Unknown preprocessor statement
   A ! character was encountered at the beginning of a line, and the
   statement name following was not error, undef, if, elif, include, else,
   or endif.


*  *  *  *  *