Return to README CVS log

Up to [Research Unix] / researchv10no / cmd / cpp

Annotation of researchv10no/cmd/cpp/README, revision 1.1

1.1     ! root        1: #ident "@(#)cpp:common/README  1.4"
        !             2: August 25, 1978                updated to      August 18, 1983
        !             3: 
        !             4: Files in this directory form the C preprocessor, which handles '#include'
        !             5: files and macro definition and expansion for the C compiler.
        !             6: This new version is from 5 to 12 times faster (on UNIX systems) than the old.
        !             7: 
        !             8: The preprocessor is not built in this directory; it is built in the 
        !             9: machine dependent directory of the target machine.  To create the 
        !            10: executable file 'cpp':
        !            11:        cd ../<machine>
        !            12:        make -f ../common/cpp.mk PD_MACH=D_<machine> PD_SYS=D_<system>
        !            13: where <machine> is the name of the target machine and <system> is the
        !            14: target operating system.  PD_MACH and PD_SYS determine which symbols
        !            15: will be predefined in the new cpp.
        !            16: 
        !            17: To install the preprocessor 'cpp' so it will be used by the C compiler:
        !            18:        # safety first: backup the existing version
        !            19:        cp /lib/cpp /lib/ocpp
        !            20:        # install the new version
        !            21:        make -f ../common/cpp.mk install PD_MACH=D_<machine> PD_SYS=D_<system>
        !            22: 
        !            23: Invocation
        !            24:        cpp [-CEPR] [-Dname] ... [-Dname=def] ... [-Idirectory] ...
        !            25:                [-Uname] ... [<infile> [<outfile>]]
        !            26: 
        !            27:        If there are two non-flag arguments then the first is the name of the
        !            28:        input file and the second is the name of the output file.  If there is
        !            29:        one non-flag argument then it is the name of the input file and the
        !            30:        output is written on the standard output.  If there are no non-flag
        !            31:        arguments then the input is taken from the standard input and the output
        !            32:        is written on the standard output.  Flag arguments are:
        !            33: 
        !            34:                -C      retain comments in output
        !            35:                -Dname  define name as "1"
        !            36:                -Dname=def      define name as def
        !            37:                -E      ignored
        !            38:                -Idirectory     add directory to search list for #include files
        !            39:                -P      don't insert lines "# 12 \"foo.c\"" into output
        !            40:                -R      allow recursive macros
        !            41:                -Uname  undefine name
        !            42:                
        !            43: Documentation clarifications:
        !            44:        Symbols defined on the command line by "-Dfoo" are defined as "1",
        !            45:                i.e., as if they had been defined by "#define foo 1" or
        !            46:                "-Dfoo=1".
        !            47:        The directory search order for #include files is
        !            48:                1) the directory of the file which contains the #include request
        !            49:                   (e.g. #include is relative to the file being scanned when
        !            50:                   the request is made)
        !            51:                2) the directories specified by -I, in left-to-right order
        !            52:                3) the standard directory(s) (which for UNIX is /usr/include)
        !            53:        An unescaped linefeed (the single character "\n") terminates a
        !            54:                character constant or quoted string.
        !            55:        An escaped linefeed (the two-character sequence "\\\n") may be
        !            56:                used in the body of a '#define' statement to continue
        !            57:                the definition onto the next line.  The escaped linefeed is
        !            58:                converted into a single blank in the macro body.
        !            59:        Comments are uniformly removed (except if the argument -C is specified).
        !            60:                They are also ignored, except that a comment terminates a token.
        !            61:                Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but
        !            62:                will never expand 'foobar'.  If neither 'foo' nor 'bar' is a
        !            63:                macro then the output is "foobar", even if 'foobar'
        !            64:                is defined as something else.  The file
        !            65:                        #define foo(a,b)b/**/a
        !            66:                        foo(1,2)
        !            67:                produces "21" because the comment causes a break which enables
        !            68:                the recognition of 'b' and 'a' as formals in the string
        !            69:                "b/**/a".
        !            70:        Macro formal parameters are recognized in '#define' bodies even inside
        !            71:                character constants and quoted strings.  The output from
        !            72:                        #define foo(a) '\a'
        !            73:                        foo(bar)
        !            74:                is the six characters "'\\bar'".  Macro names are not recognized
        !            75:                inside character constants or quoted strings during the
        !            76:                regular scan.
        !            77:                Thus
        !            78:                        #define foo bar
        !            79:                        printf("foo");
        !            80:                does not expand 'foo' in the second line, because it is inside
        !            81:                a quoted string which is not part of a '#define' macro
        !            82:                definition.
        !            83:        Macros are not expanded while processing a '#define' or '#undef'.
        !            84:                Thus
        !            85:                        #define foo bletch
        !            86:                        #define bar foo
        !            87:                        #undef foo
        !            88:                        bar
        !            89:                produces "foo".  The token appearing immediately after a
        !            90:                '#ifdef' or '#ifndef' is not expanded (of course!).
        !            91:        Macros are not expanded during the scan which determines the actual
        !            92:                parameters to another macro call.  Thus
        !            93:                |       #define foo(a,b)b a
        !            94:                |       #define bar hi
        !            95:                |       foo(bar,
        !            96:                |       #define bar bye
        !            97:                |       )
        !            98:                |produces " bye" (and warns about the redefinition of 'bar').
        !            99:                |--->not any longer.  Newlines have been stripped by now, so
        !           100:                        the # is no longer at the beginning of a line.
        !           101:                The note is still true, though.  When a macro is expanded,
        !           102:                        the first step is to put the actual arguments in the
        !           103:                        corresponding locations in the token-string the macro
        !           104:                        is defined to be.  The next step is to start to re-
        !           105:                        process the token-string as input text.
        !           106: 
        !           107: There are some differences between the new and the old preprocessor.
        !           108: Bugs fixed:
        !           109:        "1.e4" is recognized as a floating-point number, rather than as an
        !           110:                opportunity to expand the possible macro name "e4".
        !           111:        Any kind and amount of white space (space, tab, linefeed, vertical tab,
        !           112:                formfeed, carriage return) is allowed between a macro name and
        !           113:                the left parenthesis which introduces its actual parameters.
        !           114:        The comma operator is legal in preprocessor '#if' statements.
        !           115:        Macros with parameters are legal in preprocessor '#if' statements.
        !           116:        Single-character character constants are legal in preprocessor '#if'
        !           117:                statements.
        !           118:        Linefeeds are put out in the proper place when a multiline comment
        !           119:                is not passed through to the output.
        !           120:        The following example expands to "# # #" :
        !           121:                #define foo #
        !           122:                foo foo foo
        !           123:        If the -R flag is not specified then the invocation of some recursive
        !           124:                macros is trapped and the recursion forcibly terminated with an
        !           125:                error message.  The recursions that are trapped are the ones
        !           126:                in which the nesting level is non-decreasing from some point on.
        !           127:                In particular,
        !           128:                        #define a a
        !           129:                        a
        !           130:                will be detected.  (Use "#undef a" if that is what you want.)
        !           131:                The recursion
        !           132:                        #define a c b
        !           133:                        #define b c a
        !           134:                        #define c foo
        !           135:                        a
        !           136:                will not be detected because the nesting level decreases after
        !           137:                each expansion of "c".
        !           138:        The -R flag specifically allows recursive macros and recursion will
        !           139:                be strictly obeyed (to the extent that space is available).
        !           140:                Assuming that -R is specified:
        !           141:                        #define a a
        !           142:                        a
        !           143:                causes an infinite loop with very little output.  The tail
        !           144:                recursion
        !           145:                        #define a <b
        !           146:                        #define b >a
        !           147:                        a
        !           148:                causes the string "<>" to be output infinitely many times.  The
        !           149:                non-tail recursion
        !           150:                        #define a b>
        !           151:                        #define b a<
        !           152:                        a
        !           153:                complains "too much pushback", dumps the pushback, and continues
        !           154:                (again, infinitely).
        !           155:        
        !           156: Stylistic choice:
        !           157:        Nothing (not even linefeeds) is output while a false '#if', '#ifdef',
        !           158:                or '#ifndef' is in effect.  Thus when all conditions become true
        !           159:                a line of the form "# 12345 \"foo.c\"" is output (unless -P).
        !           160:        Error and warning messages always appear on standard error (file
        !           161:                descriptor 2).
        !           162:        Mismatch between the number of formals and actuals in a macro call
        !           163:                produces only a warning, and not an error.  Excess actuals
        !           164:                are ignored; missing actuals are turned into null strings.
        !           165:        Comments which worked their way into #if lines no longer cause a
        !           166:                syntax error.
        !           167:        Newlines found during the scan for actual arguments are changed to
        !           168:                blanks so that confusing (for cpp) situations did not occur.
        !           169:        Formfeeds (^L) act like newlines w.r.t. recognizing # as the flag
        !           170:                for cpp.
        !           171: 
        !           172: Incompatibility:
        !           173:        The virgule '/' in "a=/*b" is interpreted as the first character of
        !           174:                the pair "/*" which introduces a comment, rather than as the
        !           175:                second character of the divide-and-replace operator "=/".
        !           176:                This incompatibility reflects the recent change in the C
        !           177:                language which made "a/=*b" the legal way to write such a
        !           178:                statement if the meaning "a=a/ *b" is intended.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.