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