Commit | Line | Data |
---|---|---|
f23cb965 | 1 | # |
61a8d43d | 2 | # @(#)README 1.3 %G% |
f23cb965 | 3 | # |
9372792e RH |
4 | August 30, 1982 |
5 | Fixed by Kurt Shoens, UCB | |
6 | If the "#line n name" occurs, then all future references | |
7 | to the current file are generated in terms of "name", instead | |
8 | of the name of file given to cpp in its command argument | |
9 | ||
f23cb965 RH |
10 | August 25, 1978 |
11 | ||
12 | Files in this directory form the C preprocessor, which handles '#include' | |
13 | files and macro definition and expansion for the C compiler. | |
14 | This new version was written by John F. Reiser and is from 5 to 12 | |
15 | times faster (on UNIX systems) than the old. | |
16 | ||
17 | To create the executable file 'cpp' in the current directory: | |
18 | make | |
19 | ||
20 | To install the preprocessor 'cpp' so it will be used by the C compiler: | |
21 | : safety first: backup the existing version | |
22 | cp /lib/cpp /lib/ocpp | |
23 | : install the new version | |
24 | cp cpp /lib/cpp | |
25 | ||
26 | Invocation | |
61a8d43d | 27 | cpp [-CEPRM] [-Dname] ... [-Dname=def] ... [-Idirectory] ... |
f23cb965 RH |
28 | [-Uname] ... [<infile>] [<outfile>] |
29 | ||
30 | If there are two non-flag arguments then the first is the name of the | |
31 | input file and the second is the name of the output file. If there is | |
32 | one non-flag argument then it is the name of the input file and the | |
33 | output is written on the standard output. If there are no non-flag | |
34 | arguments then the input is taken from the standard input and the output | |
35 | is written on the standard output. Flag arguments are: | |
36 | ||
37 | -C retain comments in output | |
38 | -Dname define name as "1" | |
39 | -Dname=def define name as def | |
40 | -E ignored | |
41 | -Idirectory add directory to search list for #include files | |
61a8d43d | 42 | -M generate Makefile dependencies (-C and -M ignored) |
f23cb965 RH |
43 | -P don't insert lines "# 12 \"foo.c\"" into output |
44 | -R allow recursive macros | |
45 | -Uname undefine name | |
46 | ||
47 | Documentation clarifications: | |
48 | Symbols defined on the command line by "-Dfoo" are defined as "1", | |
49 | i.e., as if they had been defined by "#define foo 1" or "-Dfoo=1". | |
50 | The directory search order for #include files is | |
51 | 1) the directory of the file which contains the #include request | |
52 | (e.g. #include is relative to the file being scanned when | |
53 | the request is made) | |
54 | 2) the directories specified by -I, in left-to-right order | |
55 | 3) the standard directory(s) (which for UNIX is /usr/include) | |
56 | An unescaped linefeed (the single character "\n") terminates a | |
57 | character constant or quoted string. | |
58 | An escaped linefeed (the two-character sequence "\\\n") may be | |
59 | used in the body of a '#define' statement to continue | |
60 | the definition onto the next line. The escaped linefeed is | |
61 | not included in the macro body. | |
62 | Comments are uniformly removed (except if the argument -C is specified). | |
63 | They are also ignored, except that a comment terminates a token. | |
64 | Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but | |
65 | will never expand 'foobar'. If neither 'foo' nor 'bar' is a | |
66 | macro then the output is "foobar", even if 'foobar' | |
67 | is defined as something else. The file | |
68 | #define foo(a,b)b/**/a | |
69 | foo(1,2) | |
70 | produces "21" because the comment causes a break which enables | |
71 | the recognition of 'b' and 'a' as formals in the string "b/**/a". | |
72 | Macro formal parameters are recognized in '#define' bodies even inside | |
73 | character constants and quoted strings. The output from | |
74 | #define foo(a) '\a' | |
75 | foo(bar) | |
76 | is the seven characters " '\\bar'". Macro names are not recognized | |
77 | inside character constants or quoted strings during the regular scan. | |
78 | Thus | |
79 | #define foo bar | |
80 | printf("foo"); | |
81 | does not expand 'foo' in the second line, because it is inside | |
82 | a quoted string which is not part of a '#define' macro 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 | ||
100 | There are some differences between the new and the old preprocessor. | |
101 | Bugs fixed: | |
102 | "1.e4" is recognized as a floating-point number, rather than as an | |
103 | opportunity to expand the possible macro name "e4". | |
104 | Any kind and amount of white space (space, tab, linefeed, vertical tab, | |
105 | formfeed, carriage return) is allowed between a macro name and | |
106 | the left parenthesis which introduces its actual parameters. | |
107 | The comma operator is legal in preprocessor '#if' statements. | |
108 | Macros with parameters are legal in preprocessor '#if' statements. | |
109 | Single-character character constants are legal in preprocessor '#if' statements. | |
110 | Linefeeds are put out in the proper place when a multiline comment | |
111 | is not passed through to the output. | |
112 | The following example expands to "# # #" : | |
113 | #define foo # | |
114 | foo foo foo | |
115 | If the -R flag is not specified then the invocation of some recursive | |
116 | macros is trapped and the recursion forcibly terminated with an | |
117 | error message. The recursions that are trapped are the ones | |
118 | in which the nesting level is non-decreasing from some point on. | |
119 | In particular, | |
120 | #define a a | |
121 | a | |
122 | will be detected. (Use "#undef a" if that is what you want.) | |
123 | The recursion | |
124 | #define a c b | |
125 | #define b c a | |
126 | #define c foo | |
127 | a | |
128 | will not be detected because the nesting level decreases after | |
129 | each expansion of "c". | |
130 | The -R flag specifically allows recursive macros and recursion will | |
131 | be strictly obeyed (to the extent that space is available). | |
132 | Assuming that -R is specified: | |
133 | #define a a | |
134 | a | |
135 | causes an infinite loop with very little output. The tail recursion | |
136 | #define a <b | |
137 | #define b >a | |
138 | a | |
139 | causes the string "<>" to be output infinitely many times. The | |
140 | non-tail recursion | |
141 | #define a b> | |
142 | #define b a< | |
143 | a | |
144 | complains "too much pushback", dumps the pushback, and continues | |
145 | (again, infinitely). | |
146 | ||
147 | Stylistic choice: | |
148 | Nothing (not even linefeeds) is output while a false '#if', '#ifdef', | |
149 | or '#ifndef' is in effect. Thus when all conditions become true | |
150 | a line of the form "# 12345 \"foo.c\"" is output (unless -P). | |
151 | Error and warning messages always appear on standard error (file | |
152 | descriptor 2). | |
153 | Mismatch between the number of formals and actuals in a macro call | |
154 | produces only a warning, and not an error. Excess actuals | |
155 | are ignored; missing actuals are turned into null strings. | |
156 | ||
157 | Incompatibility: | |
158 | The virgule '/' in "a=/*b" is interpreted as the first character of | |
159 | the pair "/*" which introduces a comment, rather than as the | |
160 | second character of the divide-and-replace operator "=/". | |
161 | This incompatibility reflects the recent change in the C language | |
162 | which made "a/=*b" the legal way to write such a statement | |
163 | if the meaning "a=a/ *b" is intended. |