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