OSDN Git Service

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