| blob | 3e4e63f4a78e6242652f1e576daadedcd310733c |
2 FIXINCLUDES OPERATION
3 =====================
5 See also: http://autogen.SourceForge.net/fixinc.html
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 fixincludes/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.
17 Regards,
18 Bruce <bkorb@gnu.org>
22 GCC MAINTAINER INFORMATION
23 ==========================
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.
32 To make your fix, you will need to do several things:
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.
37 2. Edit "inclhack.def" to reflect the changes you need to make.
38 See below for information on how to make those changes.
40 3. Run the "genfixes" shell script to produce a new copy of
41 the "fixincl.x" file.
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 Do *NOT* specify test text for "wrap" or "replacement" fixes.
48 There is no real possibility that these fixes will fail.
49 If they do, you will surely know straight away.
51 5. Go into the fixincludes build directory and type, "make check".
52 You are guaranteed to have issues printed out as a result.
53 Look at the diffs produced. Make sure you have not clobbered
54 the proper functioning of a different fix. Make sure your
55 fix is properly tested and it does what it is supposed to do.
57 6. Now that you have the right things happening, synchronize the
58 $(srcdir)/tests/base directory with the $(builddir)/tests/res
59 directory. The output of "make check" will be some diffs that
60 should give you some hints about what to do.
62 7. Rerun "make check" and verify that there are no issues left.
65 MAKING CHANGES TO INCLHACK.DEF
66 ==============================
68 0. If you are not the fixincludes maintainer, please send that
69 person email about any changes you may want to make. Thanks!
71 1. Every fix must have a "hackname" that is compatible with C syntax
72 for variable names and is unique without regard to alphabetic case.
73 Please keep them alphabetical by this name. :-)
75 2. If the problem is known to exist only in certain files, then
76 identify the files with "files = " entries. If you use fnmatch(3C)
77 wild card characters in a "files" entry, be certain that the first
78 "files" entry has no such character. Otherwise, the "make check"
79 machinery will attempt to create files with those characters in the
80 name. That is inconvenient.
82 3. It is relatively expensive to fire off a process to fix a source
83 file, therefore write apply tests to avoid unnecessary fix
84 processes. The preferred apply tests are "select", "bypass", "mach"
85 and "c-test" because they are performed internally:
87 * select - Run a regex on the contents of the file being considered.
88 All such regex-es must match. Matching is done with
89 extended regular expressions.
91 * bypass - Run a regex on the contents of the file being considered.
92 No such regex may match.
94 * c_test - call a function in fixtests.c. See that file.
96 * files - the "fnmatch" pattern of the file(s) to examine for
97 the issue. There may be several copies of this attribute.
98 If the header lives in a /usr/include subdirectory, be
99 sure to include that subdirectory in the name. e.g. net/if.h
101 * mach - Match the output of config.guess against a series of fnmatch
102 patterns. It must match at least one of the patterns, unless
103 "not-machine" has also been specified. In that case, the
104 config.guess output must not match any of the patterns.
106 The next test is relatively slow because it must be handled in a
107 separate shell process. Some platforms do not support server shells,
108 so the whole process is even slower and more cumbersome there.
110 * test - These should be arguments to the program, "/bin/test".
111 You may perform multiple commands, if you enclose them
112 in backquotes and echo out valid test arguments. For
113 example, you might echo out '0 -eq 1' if you want a false
114 result, or '0 -eq 0' for a true result.
116 These tests are required to:
118 1. Be positive for all header files that require the fix.
120 It is desirable to:
122 2. Be negative as often as possible whenever the fix is not
123 required, avoiding the process overhead.
125 It is nice if:
127 3. The expression is as simple as possible to both
128 process and understand by people. :-)
130 Please take advantage of the fact AutoGen will glue
131 together string fragments. It helps. Also take note
132 that double quote strings and single quote strings have
133 different formation rules. Double quote strings are a
134 tiny superset of ANSI-C string syntax. Single quote
135 strings follow shell single quote string formation
136 rules, except that the backslash is processed before
137 '\\', '\'' and '#' characters (using C character syntax).
139 Each test must pass or the fix is not applied. For example,
140 all "select" expressions must be found and not one "bypass"
141 selection may be found.
143 Examples of test specifications:
145 hackname = broken_assert_stdio;
146 files = assert.h;
147 select = stderr;
148 bypass = "include.*stdio.h";
150 The ``broken_assert_stdio'' fix will be applied only to a file
151 named "assert.h" if it contains the string "stderr" _and_ it
152 does _not_ contain the expression "include.*stdio.h".
154 hackname = no_double_slash;
155 c_test = "double_slash";
157 The ``no_double_slash'' fix will be applied if the
158 ``double_slash_test()'' function says to. See ``fixtests.c''
159 for documentation on how to include new functions into that
160 module.
162 4. There are currently four methods of fixing a file:
164 1. a series of sed expressions. Each will be an individual
165 "-e" argument to a single invocation of sed. Unless you
166 need to use multiple or complex sed expressions, please
167 use the "replacement text" method instead.
169 2. a shell script. These scripts are _required_ to read all
170 of stdin in order to avoid pipe stalls. They may choose to
171 discard the input.
173 3. Replacement text. If the replacement is empty, then no
174 fix is applied. Otherwise, the replacement text is
175 written to the output file and no further fixes are
176 applied. If you really want a no-op file, replace the
177 file with a comment.
179 Replacement text "fixes" must be first in this file!!
181 4. A C language subroutine method for both tests and fixes.
182 See ``fixtests.c'' for instructions on writing C-language
183 applicability tests and ``fixfixes.c'' for C-language fixing.
184 These files also contain tables that describe the currently
185 implemented fixes and tests.
187 If at all possible, you should try to use one of the C language
188 fixes as it is far more efficient. There are currently five
189 such fixes, three of which are very special purpose:
191 i) char_macro_def - This function repairs the definition of an
192 ioctl macro that presumes CPP macro substitution within
193 pairs of single quote characters.
195 ii) char_macro_use - This function repairs the usage of ioctl
196 macros that no longer can wrap an argument with single quotes.
198 iii) machine_name - This function will look at "#if", "#ifdef",
199 "#ifndef" and "#elif" directive lines and replace the first
200 occurrence of a non-reserved name that is traditionally
201 pre-defined by the native compiler.
203 The next two are for general use:
205 iv) wrap - wraps the entire file with "#ifndef", "#define" and
206 "#endif" self-exclusionary text. It also, optionally, inserts
207 a prolog after the "#define" and an epilog just before the
208 "#endif". You can use this for a fix as follows:
210 c_fix = wrap;
211 c_fix_arg = "/* prolog text */";
212 c_fix_arg = "/* epilog text */";
214 If you want an epilog without a prolog, set the first "c_fix_arg"
215 to the empty string. Both or the second "c_fix_arg"s may be
216 omitted and the file will still be wrapped.
218 THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
220 If the regular expression '#if.*__need' is found, then it is
221 assumed that the file needs to be read and interpreted more
222 than once. However, the prolog and epilog text (if any) will
223 be inserted.
225 v) format - Replaces text selected with a regular expression with
226 a specialized formating string. The formatting works as follows:
227 The format text is copied to the output until a '%' character
228 is found. If the character after the '%' is another '%', then
229 one '%' is output and processing continues. If the following
230 character is not a digit, then the '%' and that character are
231 copied and processing continues. Finally, if the '%' *is*
232 followed by a digit, that digit is used as an index into the
233 regmatch_t array to replace the two characters with the matched
234 text. i.e.: "%0" is replaced by the full matching text, "%1"
235 is the first matching sub-expression, etc.
237 This is used as follows:
239 c_fix = format;
240 c_fix_arg = "#ifndef %1\n%0\n#endif";
241 c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
243 This would wrap a one line #define inside of a "#ifndef"/"#endif"
244 pair. The second "c_fix_arg" may be omitted *IF* there is at least
245 one select clause and the first one identifies the text you wish to
246 reformat. It will then be used as the second "c_fix_arg". You may
247 delete the selected text by supplying an empty string for the
248 replacement format (the first "c_fix_arg").
250 Note: In general, a format c_fix may be used in place of one
251 sed expression. However, it will need to be rewritten by
252 hand. For example:
254 sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
255 '@& || __GNUC__ >= 3@';
257 may be rewritten using a format c_fix as:
259 c_fix = format;
260 c_fix_arg = '%0 || __GNUC__ >= 3';
261 c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
263 Multiple sed substitution expressions probably ought to remain sed
264 expressions in order to maintain clarity. Also note that if the
265 second sed expression is the same as the first select expression,
266 then you may omit the second c_fix_arg. The select expression will
267 be picked up and used in its absence.
269 EXAMPLES OF FIXES:
270 ==================
272 hackname = AAA_ki_iface;
273 replace; /* empty replacement -> no fixing the file */
275 When this ``fix'' is invoked, it will prevent any fixes
276 from being applied.
278 ------------------
280 hackname = AAB_svr4_no_varargs;
281 replace = "/* This file was generated by fixincludes. */\n"
282 "#ifndef _SYS_VARARGS_H\n"
283 "#define _SYS_VARARGS_H\n\n"
285 "#ifdef __STDC__\n"
286 "#include <stdarg.h>\n"
287 "#else\n"
288 "#include <varargs.h>\n"
289 "#endif\n\n"
291 "#endif /* _SYS_VARARGS_H */\n";
293 When this ``fix'' is invoked, the replacement text will be
294 emitted into the replacement include file. No further fixes
295 will be applied.
297 ------------------
299 hackname = hpux11_fabsf;
300 files = math.h;
301 select = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
302 bypass = "__cplusplus";
304 c_fix = format;
305 c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
307 test_text =
308 "# define fabsf(x) ((float)fabs((double)(float)(x)))\n";
310 This fix will ensure that the #define for fabs is wrapped
311 with C++ protection, providing the header is not already
312 C++ aware.
314 ------------------
316 5. Testing fixes.
318 The brute force method is, of course, to configure and build
319 GCC. But you can also:
321 cd ${top_builddir}/gcc
322 rm -rf include-fixed/ stmp-fixinc
323 make stmp-fixinc
325 I would really recommend, however:
327 cd ${top_builddir}/fixincludes
328 make check
330 To do this, you *must* have autogen installed on your system.
331 The "check" step will proceed to construct a shell script that
332 will exercise all the fixes, using the sample test_text
333 provided with each fix. Once done, the changes made will
334 be compared against the changes saved in the source directory.
335 If you are changing the tests or fixes, the change will likely
336 be highlighted.