OSDN Git Service

Clarify how tests are handled
[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,
73     then name each such file with a "files = " entry.
74
75 3.  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     Each test must pass or the fix is not applied.  For example,
110     all "select" expressions must be found and not one "bypass"
111     selection may be found.
112
113     Examples of test specifications:
114
115       hackname = broken_assert_stdio;
116       files    = assert.h;
117       select   = stderr;
118       bypass   = "include.*stdio.h";
119
120     The ``broken_assert_stdio'' fix will be applied only to a file
121     named "assert.h" if it contains the string "stderr" _and_ it
122     does _not_ contain the expression "include.*stdio.h".
123
124       hackname = no_double_slash;
125       c_test   = "double_slash";
126
127     The ``no_double_slash'' fix will be applied if the
128     ``double_slash_test()'' function says to.  See ``fixtests.c''
129     for documentation on how to include new functions into that
130     module.
131
132 4.  There are currently four methods of fixing a file:
133
134     1.  a series of sed expressions.  Each will be an individual
135         "-e" argument to a single invocation of sed.
136
137     2.  a shell script.  These scripts are _required_ to read all
138         of stdin in order to avoid pipe stalls.  They may choose to
139         discard the input.
140
141     3.  Replacement text.  If the replacement is empty, then no
142         fix is applied.  Otherwise, the replacement text is
143         written to the output file and no further fixes are
144         applied.  If you really want a no-op file, replace the
145         file with a comment.
146
147         Replacement text "fixes" must be first in this file!!
148
149     4.  A C language subroutine method for both tests and fixes.
150         See ``fixtests.c'' for instructions on writing C-language
151         applicability tests and ``fixfixes.c'' for C-language fixing.
152         These files also contain tables that describe the currently
153         implemented fixes and tests.
154
155     If at all possible, you should try to use one of the C language
156     fixes as it is far more efficient.  There are currently five
157     such fixes, three of which are very special purpose:
158
159     i) char_macro_def - This function repairs the definition of an
160         ioctl macro that presumes CPP macro substitution within
161         pairs of single quote characters.
162
163     ii) char_macro_use - This function repairs the usage of ioctl
164         macros that no longer can wrap an argument with single quotes.
165
166     iii) machine_name - This function will look at "#if", "#ifdef",
167         "#ifndef" and "#elif" directive lines and replace the first
168         occurrence of a non-reserved name that is traditionally
169         pre-defined by the native compiler.
170
171     The next two are for general use:
172
173     iv) wrap - wraps the entire file with "#ifndef", "#define" and
174         "#endif" self-exclusionary text.  It also, optionally, inserts
175         a prolog after the "#define" and an epilog just before the
176         "#endif".  You can use this for a fix as follows:
177
178             c_fix     = wrap;
179             c_fix_arg = "/* prolog text */";
180             c_fix_arg = "/* epilog text */";
181
182         If you want an epilog without a prolog, set the first "c_fix_arg"
183         to the empty string.  Both or the second "c_fix_arg"s may be
184         omitted and the file will still be wrapped.
185
186         THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
187
188         If the regular expression '#if.*__need' is found, then it is
189         assumed that the file needs to be read and interpreted more
190         than once.  However, the prolog and epilog text (if any) will
191         be inserted.
192
193     v) format - Replaces text selected with a regular expression with
194         a specialized formating string.  The formatting works as follows:
195         The format text is copied to the output until a '%' character
196         is found.  If the character after the '%' is another '%', then
197         one '%' is output and processing continues.  If the following
198         character is not a digit, then the '%' and that character are
199         copied and processing continues.  Finally, if the '%' *is*
200         followed by a digit, that digit is used as an index into the
201         regmatch_t array to replace the two characters with the matched
202         text.  i.e.: "%0" is replaced by the full matching text, "%1"
203         is the first matching sub-expression, etc.
204
205         This is used as follows:
206
207             c_fix     = format;
208             c_fix_arg = "#ifndef %1\n%0\n#endif";
209             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
210
211         This would wrap a traditional #define inside of a "#ifndef"/"#endif"
212         pair.  The second "c_fix_arg" may be omitted *IF* there is
213         a select clause and the first one matches the text you want
214         replaced.  You may delete text by supplying an empty string for
215         the format (the first "c_fix_arg").
216
217         Note: In general, a format c_fix may be used in place of one
218         sed expression.  However, it will need to be rewritten by
219         hand.  For example:
220
221         sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
222                '@& || __GNUC__ >= 3@';
223
224         may be rewritten using a format c_fix as:
225
226         c_fix     = format;
227         c_fix_arg = '%0 || __GNUC__ >= 3';
228         c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
229
230         Multiple sed substitution expressions probably ought to remain sed
231         expressions in order to maintain clarity.  Also note that if the
232         second sed expression is the same as the first select expression,
233         then you may omit the second c_fix_arg.  The select expression will
234         be picked up and used in its absence.
235
236 EXAMPLES OF FIXES:
237 ==================
238
239       hackname = AAA_ki_iface;
240       replace; /* empty replacement -> no fixing the file */
241
242     When this ``fix'' is invoked, it will prevent any fixes
243     from being applied.
244
245     ------------------
246
247       hackname = AAB_svr4_no_varargs;
248       replace  = "/* This file was generated by fixincludes.  */\n"
249                  "#ifndef _SYS_VARARGS_H\n"
250                  "#define _SYS_VARARGS_H\n\n"
251
252                  "#ifdef __STDC__\n"
253                  "#include <stdarg.h>\n"
254                  "#else\n"
255                  "#include <varargs.h>\n"
256                  "#endif\n\n"
257
258                  "#endif  /* _SYS_VARARGS_H */\n";
259
260     When this ``fix'' is invoked, the replacement text will be
261     emitted into the replacement include file.  No further fixes
262     will be applied.
263
264     ------------------
265
266         hackname  = hpux11_fabsf;
267         files     = math.h;
268         select    = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
269         bypass    = "__cplusplus";
270
271         c_fix     = format;
272         c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
273
274         test_text =
275         "#  define fabsf(x) ((float)fabs((double)(float)(x)))\n";
276
277     This fix will ensure that the #define for fabs is wrapped
278     with C++ protection, providing the header is not already
279     C++ aware.
280
281     ------------------
282
283 5.  Testing fixes.
284
285     The brute force method is, of course, to configure and build
286     GCC.  But you can also:
287
288         cd ${top_builddir}/gcc
289         rm -rf fixinc.sh include/ stmp-fixinc
290         make stmp-fixinc
291
292     I would really recommend, however:
293
294         cd ${top_builddir}/gcc/fixinc
295         make check
296
297     To do this, you *must* have autogen installed on your system.
298     The "check" step will proceed to construct a shell script that
299     will exercise all the fixes, using the sample test_text
300     provided with each fix.  Once done, the changes made will
301     be compared against the changes saved in the source directory.
302     If you are changing the tests or fixes, the change will likely
303     be highlighted.