OSDN Git Service

2009-08-28 Bruce Korb <bkorb@gnu.org>
[pf3gnuchains/gcc-fork.git] / fixincludes / README
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     * files  - the "fnmatch" pattern of the file(s) to examine for
93                the issue.  There may be several copies of this attribute.
94                If the header lives in a /usr/include subdirectory, be
95                sure to include that subdirectory in the name. e.g. net/if.h
96
97     * mach   - Match the output of config.conf against a series of fnmatch
98                patterns.  It must match at least one of the patterns, unless
99                "not-machine" has also been specified.  In that case, the
100                config.conf output must not match any of the patterns.
101
102     The next test is relatively slow because it must be handled in a
103     separate shell process.  Some platforms do not support server shells,
104     so the whole process is even slower and more cumbersome there.
105
106     * test   - These should be arguments to the program, "/bin/test".
107                You may perform multiple commands, if you enclose them
108                in backquotes and echo out valid test arguments.  For
109                example, you might echo out '0 -eq 1' if you want a false
110                result, or '0 -eq 0' for a true result.
111
112     These tests are required to:
113
114     1.  Be positive for all header files that require the fix.
115
116     It is desireable to:
117
118     2.  Be negative as often as possible whenever the fix is not
119         required, avoiding the process overhead.
120
121     It is nice if:
122
123     3.  The expression is as simple as possible to both
124         process and understand by people.  :-)
125
126         Please take advantage of the fact AutoGen will glue
127         together string fragments.  It helps.  Also take note
128         that double quote strings and single quote strings have
129         different formation rules.  Double quote strings are a
130         tiny superset of ANSI-C string syntax.  Single quote
131         strings follow shell single quote string formation
132         rules, except that the backslash is processed before
133         '\\', '\'' and '#' characters (using C character syntax).
134
135     Each test must pass or the fix is not applied.  For example,
136     all "select" expressions must be found and not one "bypass"
137     selection may be found.
138
139     Examples of test specifications:
140
141       hackname = broken_assert_stdio;
142       files    = assert.h;
143       select   = stderr;
144       bypass   = "include.*stdio.h";
145
146     The ``broken_assert_stdio'' fix will be applied only to a file
147     named "assert.h" if it contains the string "stderr" _and_ it
148     does _not_ contain the expression "include.*stdio.h".
149
150       hackname = no_double_slash;
151       c_test   = "double_slash";
152
153     The ``no_double_slash'' fix will be applied if the
154     ``double_slash_test()'' function says to.  See ``fixtests.c''
155     for documentation on how to include new functions into that
156     module.
157
158 4.  There are currently four methods of fixing a file:
159
160     1.  a series of sed expressions.  Each will be an individual
161         "-e" argument to a single invocation of sed.
162
163     2.  a shell script.  These scripts are _required_ to read all
164         of stdin in order to avoid pipe stalls.  They may choose to
165         discard the input.
166
167     3.  Replacement text.  If the replacement is empty, then no
168         fix is applied.  Otherwise, the replacement text is
169         written to the output file and no further fixes are
170         applied.  If you really want a no-op file, replace the
171         file with a comment.
172
173         Replacement text "fixes" must be first in this file!!
174
175     4.  A C language subroutine method for both tests and fixes.
176         See ``fixtests.c'' for instructions on writing C-language
177         applicability tests and ``fixfixes.c'' for C-language fixing.
178         These files also contain tables that describe the currently
179         implemented fixes and tests.
180
181     If at all possible, you should try to use one of the C language
182     fixes as it is far more efficient.  There are currently five
183     such fixes, three of which are very special purpose:
184
185     i) char_macro_def - This function repairs the definition of an
186         ioctl macro that presumes CPP macro substitution within
187         pairs of single quote characters.
188
189     ii) char_macro_use - This function repairs the usage of ioctl
190         macros that no longer can wrap an argument with single quotes.
191
192     iii) machine_name - This function will look at "#if", "#ifdef",
193         "#ifndef" and "#elif" directive lines and replace the first
194         occurrence of a non-reserved name that is traditionally
195         pre-defined by the native compiler.
196
197     The next two are for general use:
198
199     iv) wrap - wraps the entire file with "#ifndef", "#define" and
200         "#endif" self-exclusionary text.  It also, optionally, inserts
201         a prolog after the "#define" and an epilog just before the
202         "#endif".  You can use this for a fix as follows:
203
204             c_fix     = wrap;
205             c_fix_arg = "/* prolog text */";
206             c_fix_arg = "/* epilog text */";
207
208         If you want an epilog without a prolog, set the first "c_fix_arg"
209         to the empty string.  Both or the second "c_fix_arg"s may be
210         omitted and the file will still be wrapped.
211
212         THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
213
214         If the regular expression '#if.*__need' is found, then it is
215         assumed that the file needs to be read and interpreted more
216         than once.  However, the prolog and epilog text (if any) will
217         be inserted.
218
219     v) format - Replaces text selected with a regular expression with
220         a specialized formating string.  The formatting works as follows:
221         The format text is copied to the output until a '%' character
222         is found.  If the character after the '%' is another '%', then
223         one '%' is output and processing continues.  If the following
224         character is not a digit, then the '%' and that character are
225         copied and processing continues.  Finally, if the '%' *is*
226         followed by a digit, that digit is used as an index into the
227         regmatch_t array to replace the two characters with the matched
228         text.  i.e.: "%0" is replaced by the full matching text, "%1"
229         is the first matching sub-expression, etc.
230
231         This is used as follows:
232
233             c_fix     = format;
234             c_fix_arg = "#ifndef %1\n%0\n#endif";
235             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
236
237         This would wrap a one line #define inside of a "#ifndef"/"#endif"
238         pair.  The second "c_fix_arg" may be omitted *IF* there is at least
239         one select clause and the first one identifies the text you wish to
240         reformat.  It will then be used as the second "c_fix_arg".  You may
241         delete the selected text by supplying an empty string for the
242         replacement format (the first "c_fix_arg").
243
244         Note: In general, a format c_fix may be used in place of one
245         sed expression.  However, it will need to be rewritten by
246         hand.  For example:
247
248         sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
249                '@& || __GNUC__ >= 3@';
250
251         may be rewritten using a format c_fix as:
252
253         c_fix     = format;
254         c_fix_arg = '%0 || __GNUC__ >= 3';
255         c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
256
257         Multiple sed substitution expressions probably ought to remain sed
258         expressions in order to maintain clarity.  Also note that if the
259         second sed expression is the same as the first select expression,
260         then you may omit the second c_fix_arg.  The select expression will
261         be picked up and used in its absence.
262
263 EXAMPLES OF FIXES:
264 ==================
265
266       hackname = AAA_ki_iface;
267       replace; /* empty replacement -> no fixing the file */
268
269     When this ``fix'' is invoked, it will prevent any fixes
270     from being applied.
271
272     ------------------
273
274       hackname = AAB_svr4_no_varargs;
275       replace  = "/* This file was generated by fixincludes.  */\n"
276                  "#ifndef _SYS_VARARGS_H\n"
277                  "#define _SYS_VARARGS_H\n\n"
278
279                  "#ifdef __STDC__\n"
280                  "#include <stdarg.h>\n"
281                  "#else\n"
282                  "#include <varargs.h>\n"
283                  "#endif\n\n"
284
285                  "#endif  /* _SYS_VARARGS_H */\n";
286
287     When this ``fix'' is invoked, the replacement text will be
288     emitted into the replacement include file.  No further fixes
289     will be applied.
290
291     ------------------
292
293         hackname  = hpux11_fabsf;
294         files     = math.h;
295         select    = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
296         bypass    = "__cplusplus";
297
298         c_fix     = format;
299         c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
300
301         test_text =
302         "#  define fabsf(x) ((float)fabs((double)(float)(x)))\n";
303
304     This fix will ensure that the #define for fabs is wrapped
305     with C++ protection, providing the header is not already
306     C++ aware.
307
308     ------------------
309
310 5.  Testing fixes.
311
312     The brute force method is, of course, to configure and build
313     GCC.  But you can also:
314
315         cd ${top_builddir}/gcc
316         rm -rf fixinc.sh include/ stmp-fixinc
317         make stmp-fixinc
318
319     I would really recommend, however:
320
321         cd ${top_builddir}/gcc/fixinc
322         make check
323
324     To do this, you *must* have autogen installed on your system.
325     The "check" step will proceed to construct a shell script that
326     will exercise all the fixes, using the sample test_text
327     provided with each fix.  Once done, the changes made will
328     be compared against the changes saved in the source directory.
329     If you are changing the tests or fixes, the change will likely
330     be highlighted.