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