1
2FIXINCLUDES OPERATION
3=====================
4
5See also: http://autogen.SourceForge.net/fixinc.html
6
7The set of fixes required was distilled down to just the data required
8to specify what needed to happen for each fix. Those data were edited
9into a file named gcc/fixinc/inclhack.def. A program called AutoGen
10(http://autogen.SourceForge.net) uses these definitions to instantiate
11several different templates that then produces code for a fixinclude
12program (fixincl.x) and a shell script to test its functioning. On
13certain platforms (viz. those that do not have functional bidirectional
14pipes), the fixincl program is split into two. This should only concern
15you on DOS and BeOS.
16
17Regards,
18 Bruce <bkorb@gnu.org>
19
20
21
22GCC MAINTAINER INFORMATION
23==========================
24
25If you are having some problem with a system header that is either
26broken by the manufacturer, or is broken by the fixinclude process,
27then you will need to alter or add information to the include fix
28definitions file, ``inclhack.def''. Please also send relevant
29information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
30please, to me: bkorb@gnu.org.
31
32To make your fix, you will need to do several things:
33
341. Obtain access to the AutoGen program on some platform. It does
35 not have to be your build platform, but it is more convenient.
36
372. Edit "inclhack.def" to reflect the changes you need to make.
38 See below for information on how to make those changes.
39
403. Run the "genfixes" shell script to produce a new copy of
41 the "fixincl.x" file.
42
434. Rebuild the compiler and check the header causing the issue.
44 Make sure it is now properly handled. Add tests to the
45 "test_text" entry(ies) that validate your fix. This will
46 help ensure that future fixes won't negate your work.
47
485. Go into the fixinc build directory and type, "make check".
49 You are guaranteed to have issues printed out as a result.
50 Look at the diffs produced. Make sure you have not clobbered
51 the proper functioning of a different fix. Make sure your
52 fix is properly tested and it does what it is supposed to do.
53
546. Now that you have the right things happening, syncronize the
55 $(srcdir)/tests/base directory with the $(builddir)/tests/res
56 directory. The output of "make check" will be some diffs that
57 should give you some hints about what to do.
58
597. Rerun "make check" and verify that there are no issues left.
60
61
62MAKING CHANGES TO INCLHACK.DEF
63==============================
64
650. If you are not the fixincludes maintainer, please send that
66 person email about any changes you may want to make. Thanks!
67
681. Every fix must have a "hackname" that is compatible with C syntax
69 for variable names and is unique without regard to alphabetic case.
70 Please keep them alphabetical by this name. :-)
71
722. If the problem is known to exist only in certain files,
73 then name each such file with a "files = " entry.
74
753. It is relatively expensive to fire off a process to fix a source
76 file, therefore write apply tests to avoid unnecessary fix
77 processes. The preferred apply tests are "select", "bypass" and
78 "c_test" because they are performed internally. "test" sends
79 a command to a server shell that actually fires off one or more
80 processes to do the testing. Avoid it, if you can, but it is
81 still more efficient than a fix process. Also available is
82 "mach". If the target machine matches any of the named
83 globbing-style patterns, then the machine name test will pass.
84 It is desired, however, to limit the use of this test.
85
86 These tests are required to:
87
88 1. Be positive for all header files that require the fix.
89
90 It is desireable to:
91
92 2. Be negative as often as possible whenever the fix is not
93 required, avoiding the process overhead.
94
95 It is nice if:
96
97 3. The expression is as simple as possible to both
98 process and understand by people. :-)
99
100 Please take advantage of the fact AutoGen will glue
101 together string fragments. It helps. Also take note
102 that double quote strings and single quote strings have
103 different formation rules. Double quote strings are a
104 tiny superset of ANSI-C string syntax. Single quote
105 strings follow shell single quote string formation
106 rules, except that the backslash is processed before
107 '\\', '\'' and '#' characters (using C character syntax).
108
109 Examples of test specifications:
110
111 hackname = broken_assert_stdio;
112 files = assert.h;
113 select = stderr;
114 bypass = "include.*stdio.h";
115
116 The ``broken_assert_stdio'' fix will be applied only to a file
117 named "assert.h" if it contains the string "stderr" _and_ it
118 does _not_ contain the expression "include.*stdio.h".
119
120 hackname = no_double_slash;
121 c_test = "double_slash";
122
123 The ``no_double_slash'' fix will be applied if the
124 ``double_slash_test()'' function says to. See ``fixtests.c''
125 for documentation on how to include new functions into that
126 module.
127
1284. There are currently four methods of fixing a file:
129
130 1. a series of sed expressions. Each will be an individual
131 "-e" argument to a single invocation of sed.
132
133 2. a shell script. These scripts are _required_ to read all
134 of stdin in order to avoid pipe stalls. They may choose to
135 discard the input.
136
137 3. Replacement text. If the replacement is empty, then no
138 fix is applied. Otherwise, the replacement text is
139 written to the output file and no further fixes are
140 applied. If you really want a no-op file, replace the
141 file with a comment.
142
143 Replacement text "fixes" must be first in this file!!
144
145 4. A C language subroutine method for both tests and fixes.
146 See ``fixtests.c'' for instructions on writing C-language
147 applicability tests and ``fixfixes.c'' for C-language fixing.
148 These files also contain tables that describe the currently
149 implemented fixes and tests.
150
151 If at all possible, you should try to use one of the C language
152 fixes as it is far more efficient. There are currently five
153 such fixes, three of which are very special purpose:
154
155 i) char_macro_def - This function repairs the definition of an
156 ioctl macro that presumes CPP macro substitution within
157 pairs of single quote characters.
158
159 ii) char_macro_use - This function repairs the usage of ioctl
160 macros that no longer can wrap an argument with single quotes.
161
162 iii) machine_name - This function will look at "#if", "#ifdef",
163 "#ifndef" and "#elif" directive lines and replace the first
164 occurrence of a non-reserved name that is traditionally
165 pre-defined by the native compiler.
166
167 The next two are for general use:
168
169 iv) wrap - wraps the entire file with "#ifndef", "#define" and
170 "#endif" self-exclusionary text. It also, optionally, inserts
171 a prolog after the "#define" and an epilog just before the
172 "#endif". You can use this for a fix as follows:
173
174 c_fix = wrap;
175 c_fix_arg = "/* prolog text */";
176 c_fix_arg = "/* epilog text */";
177
178 If you want an epilog without a prolog, set the first "c_fix_arg"
179 to the empty string. Both or the second "c_fix_arg"s may be
180 omitted and the file will still be wrapped.
181
182 THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
183
184 If the regular expression '#if.*__need' is found, then it is
185 assumed that the file needs to be read and interpreted more
186 than once. However, the prolog and epilog text (if any) will
187 be inserted.
188
189 v) format - Replaces text selected with a regular expression with
190 a specialized formating string. The formatting works as follows:
191 The format text is copied to the output until a '%' character
192 is found. If the character after the '%' is another '%', then
193 one '%' is output and processing continues. If the following
194 character is not a digit, then the '%' and that character are
195 copied and processing continues. Finally, if the '%' *is*
196 followed by a digit, that digit is used as an index into the
197 regmatch_t array to replace the two characters with the matched
198 text. i.e.: "%0" is replaced by the full matching text, "%1"
199 is the first matching sub-expression, etc.
200
201 This is used as follows:
202
203 c_fix = format;
204 c_fix_arg = "#ifndef %1\n%0\n#endif";
205 c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
206
207 This would wrap a traditional #define inside of a "#ifndef"/"#endif"
208 pair. The second "c_fix_arg" may be omitted *IF* there is
209 a select clause and the first one matches the text you want
210 replaced. You may delete text by supplying an empty string for
211 the format (the first "c_fix_arg").
212
213 Note: In general, a format c_fix may be used in place of one
214 sed expression. However, it will need to be rewritten by
215 hand. For example:
216
217 sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
218 '@& || __GNUC__ >= 3@';
219
220 may be rewritten using a format c_fix as:
221
222 c_fix = format;
223 c_fix_arg = '%0 || __GNUC__ >= 3';
224 c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
225
226 Multiple sed substitution expressions probably ought to remain sed
227 expressions in order to maintain clarity. Also note that if the
228 second sed expression is the same as the first select expression,
229 then you may omit the second c_fix_arg. The select expression will
230 be picked up and used in its absence.
231
232EXAMPLES OF FIXES:
233==================
234
235 hackname = AAA_ki_iface;
236 replace; /* empty replacement -> no fixing the file */
237
238 When this ``fix'' is invoked, it will prevent any fixes
239 from being applied.
240
241 ------------------
242
243 hackname = AAB_svr4_no_varargs;
244 replace = "/* This file was generated by fixincludes. */\n"
245 "#ifndef _SYS_VARARGS_H\n"
246 "#define _SYS_VARARGS_H\n\n"
247
248 "#ifdef __STDC__\n"
249 "#include <stdarg.h>\n"
250 "#else\n"
251 "#include <varargs.h>\n"
252 "#endif\n\n"
253
254 "#endif /* _SYS_VARARGS_H */\n";
255
256 When this ``fix'' is invoked, the replacement text will be
257 emitted into the replacement include file. No further fixes
258 will be applied.
259
260 ------------------
261
262 hackname = hpux11_fabsf;
263 files = math.h;
264 select = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
265 bypass = "__cplusplus";
266
267 c_fix = format;
268 c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
269
270 test_text =
271 "# define fabsf(x) ((float)fabs((double)(float)(x)))\n";
272
273 This fix will ensure that the #define for fabs is wrapped
274 with C++ protection, providing the header is not already
275 C++ aware.
276
277 ------------------
278
2795. Testing fixes.
280
281 The brute force method is, of course, to configure and build
282 GCC. But you can also:
283
284 cd ${top_builddir}/gcc
285 rm -rf fixinc.sh include/ stmp-fixinc
286 make stmp-fixinc
287
288 I would really recommend, however:
289
290 cd ${top_builddir}/gcc/fixinc
291 make check
292
293 To do this, you *must* have autogen installed on your system.
294 The "check" step will proceed to construct a shell script that
295 will exercize all the fixes, using the sample test_text
296 provided with each fix. Once done, the changes made will
297 be compared against the changes saved in the source directory.
298 If you are changing the tests or fixes, the change will likely
299 be highlighted.
300