1 2FIXINCLUDES OPERATION 3===================== 4 5See also: http://autogen.SourceForge.net/fixinc.html 6 7The set of fixes required was distilled down to just the data required 8to specify what needed to happen for each fix. Those data were edited 9into a file named gcc/fixinc/inclhack.def. A program called AutoGen 10(http://autogen.SourceForge.net) uses these definitions to instantiate 11several different templates that then produces code for a fixinclude 12program (fixincl.x) and a shell script to test its functioning. On 13certain platforms (viz. those that do not have functional bidirectional 14pipes), the fixincl program is split into two. This should only concern 15you on DOS and BeOS. 16 17Regards, 18 Bruce <bkorb@gnu.org> 19 20 21 22GCC MAINTAINER INFORMATION 23========================== 24 25If you are having some problem with a system header that is either 26broken by the manufacturer, or is broken by the fixinclude process, 27then you will need to alter or add information to the include fix 28definitions file, ``inclhack.def''. Please also send relevant 29information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and, 30please, to me: bkorb@gnu.org. 31 32To make your fix, you will need to do several things: 33 341. 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 372. Edit "inclhack.def" to reflect the changes you need to make. 38 See below for information on how to make those changes. 39 403. Run the "genfixes" shell script to produce a new copy of 41 the "fixincl.x" file. 42 434. 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 485. 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 546. 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 597. Rerun "make check" and verify that there are no issues left. 60 61 62MAKING CHANGES TO INCLHACK.DEF 63============================== 64 650. If you are not the fixincludes maintainer, please send that 66 person email about any changes you may want to make. Thanks! 67 681. 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 722. If the problem is known to exist only in certain files, 73 then name each such file with a "files = " entry. 74 753. 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. The available 79 tests are: 80 81 * select - Run a regex on the contents of the file being considered. 82 All such regex-es must match. 83 84 * bypass - Run a regex on the contents of the file being considered. 85 No such regex may match. 86 87 * c_test - call a function in fixtests.c. See that file. 88 89 The next two tests are relatively slow because they must be handled 90 in a separate shell process. Some platforms do not support server 91 shells, so the whole process is even slower and more cumbersome there. 92 93 * mach - Match the output of config.conf against a series of globbing 94 patterns. It must match at least one of the patterns, unless 95 "not-machine" has also been specified. If that has been 96 specified, then the config.conf output may not match any of 97 the patterns. 98 99 * test - These should be arguments to the program, "/bin/test". 100 You may perform multiple commands, if you enclose them 101 in backquotes and echo out valid test arguments. For 102 example, you might echo out '0 -eq 1' if you want a false 103 result, or '0 -eq 0' for a true result. 104 105 These tests are required to: 106 107 1. Be positive for all header files that require the fix. 108 109 It is desireable to: 110 111 2. Be negative as often as possible whenever the fix is not 112 required, avoiding the process overhead. 113 114 It is nice if: 115 116 3. The expression is as simple as possible to both 117 process and understand by people. :-) 118 119 Please take advantage of the fact AutoGen will glue 120 together string fragments. It helps. Also take note 121 that double quote strings and single quote strings have 122 different formation rules. Double quote strings are a 123 tiny superset of ANSI-C string syntax. Single quote 124 strings follow shell single quote string formation 125 rules, except that the backslash is processed before 126 '\\', '\'' and '#' characters (using C character syntax). 127 128 Each test must pass or the fix is not applied. For example, 129 all "select" expressions must be found and not one "bypass" 130 selection may be found. 131 132 Examples of test specifications: 133 134 hackname = broken_assert_stdio; 135 files = assert.h; 136 select = stderr; 137 bypass = "include.*stdio.h"; 138 139 The ``broken_assert_stdio'' fix will be applied only to a file 140 named "assert.h" if it contains the string "stderr" _and_ it 141 does _not_ contain the expression "include.*stdio.h". 142 143 hackname = no_double_slash; 144 c_test = "double_slash"; 145 146 The ``no_double_slash'' fix will be applied if the 147 ``double_slash_test()'' function says to. See ``fixtests.c'' 148 for documentation on how to include new functions into that 149 module. 150 1514. There are currently four methods of fixing a file: 152 153 1. a series of sed expressions. Each will be an individual 154 "-e" argument to a single invocation of sed. 155 156 2. a shell script. These scripts are _required_ to read all 157 of stdin in order to avoid pipe stalls. They may choose to 158 discard the input. 159 160 3. Replacement text. If the replacement is empty, then no 161 fix is applied. Otherwise, the replacement text is 162 written to the output file and no further fixes are 163 applied. If you really want a no-op file, replace the 164 file with a comment. 165 166 Replacement text "fixes" must be first in this file!! 167 168 4. A C language subroutine method for both tests and fixes. 169 See ``fixtests.c'' for instructions on writing C-language 170 applicability tests and ``fixfixes.c'' for C-language fixing. 171 These files also contain tables that describe the currently 172 implemented fixes and tests. 173 174 If at all possible, you should try to use one of the C language 175 fixes as it is far more efficient. There are currently five 176 such fixes, three of which are very special purpose: 177 178 i) char_macro_def - This function repairs the definition of an 179 ioctl macro that presumes CPP macro substitution within 180 pairs of single quote characters. 181 182 ii) char_macro_use - This function repairs the usage of ioctl 183 macros that no longer can wrap an argument with single quotes. 184 185 iii) machine_name - This function will look at "#if", "#ifdef", 186 "#ifndef" and "#elif" directive lines and replace the first 187 occurrence of a non-reserved name that is traditionally 188 pre-defined by the native compiler. 189 190 The next two are for general use: 191 192 iv) wrap - wraps the entire file with "#ifndef", "#define" and 193 "#endif" self-exclusionary text. It also, optionally, inserts 194 a prolog after the "#define" and an epilog just before the 195 "#endif". You can use this for a fix as follows: 196 197 c_fix = wrap; 198 c_fix_arg = "/* prolog text */"; 199 c_fix_arg = "/* epilog text */"; 200 201 If you want an epilog without a prolog, set the first "c_fix_arg" 202 to the empty string. Both or the second "c_fix_arg"s may be 203 omitted and the file will still be wrapped. 204 205 THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER: 206 207 If the regular expression '#if.*__need' is found, then it is 208 assumed that the file needs to be read and interpreted more 209 than once. However, the prolog and epilog text (if any) will 210 be inserted. 211 212 v) format - Replaces text selected with a regular expression with 213 a specialized formating string. The formatting works as follows: 214 The format text is copied to the output until a '%' character 215 is found. If the character after the '%' is another '%', then 216 one '%' is output and processing continues. If the following 217 character is not a digit, then the '%' and that character are 218 copied and processing continues. Finally, if the '%' *is* 219 followed by a digit, that digit is used as an index into the 220 regmatch_t array to replace the two characters with the matched 221 text. i.e.: "%0" is replaced by the full matching text, "%1" 222 is the first matching sub-expression, etc. 223 224 This is used as follows: 225 226 c_fix = format; 227 c_fix_arg = "#ifndef %1\n%0\n#endif"; 228 c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*"; 229 230 This would wrap a traditional #define inside of a "#ifndef"/"#endif" 231 pair. The second "c_fix_arg" may be omitted *IF* there is 232 a select clause and the first one matches the text you want 233 replaced. You may delete text by supplying an empty string for 234 the format (the first "c_fix_arg"). 235 236 Note: In general, a format c_fix may be used in place of one 237 sed expression. However, it will need to be rewritten by 238 hand. For example: 239 240 sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$' 241 '@& || __GNUC__ >= 3@'; 242 243 may be rewritten using a format c_fix as: 244 245 c_fix = format; 246 c_fix_arg = '%0 || __GNUC__ >= 3'; 247 c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'; 248 249 Multiple sed substitution expressions probably ought to remain sed 250 expressions in order to maintain clarity. Also note that if the 251 second sed expression is the same as the first select expression, 252 then you may omit the second c_fix_arg. The select expression will 253 be picked up and used in its absence. 254 255EXAMPLES OF FIXES: 256================== 257 258 hackname = AAA_ki_iface; 259 replace; /* empty replacement -> no fixing the file */ 260 261 When this ``fix'' is invoked, it will prevent any fixes 262 from being applied. 263 264 ------------------ 265 266 hackname = AAB_svr4_no_varargs; 267 replace = "/* This file was generated by fixincludes. */\n" 268 "#ifndef _SYS_VARARGS_H\n" 269 "#define _SYS_VARARGS_H\n\n" 270 271 "#ifdef __STDC__\n" 272 "#include <stdarg.h>\n" 273 "#else\n" 274 "#include <varargs.h>\n" 275 "#endif\n\n" 276 277 "#endif /* _SYS_VARARGS_H */\n"; 278 279 When this ``fix'' is invoked, the replacement text will be 280 emitted into the replacement include file. No further fixes 281 will be applied. 282 283 ------------------ 284 285 hackname = hpux11_fabsf; 286 files = math.h; 287 select = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*"; 288 bypass = "__cplusplus"; 289 290 c_fix = format; 291 c_fix_arg = "#ifndef __cplusplus\n%0\n#endif"; 292 293 test_text = 294 "# define fabsf(x) ((float)fabs((double)(float)(x)))\n"; 295 296 This fix will ensure that the #define for fabs is wrapped 297 with C++ protection, providing the header is not already 298 C++ aware. 299 300 ------------------ 301 3025. Testing fixes. 303 304 The brute force method is, of course, to configure and build 305 GCC. But you can also: 306 307 cd ${top_builddir}/gcc 308 rm -rf fixinc.sh include/ stmp-fixinc 309 make stmp-fixinc 310 311 I would really recommend, however: 312 313 cd ${top_builddir}/gcc/fixinc 314 make check 315 316 To do this, you *must* have autogen installed on your system. 317 The "check" step will proceed to construct a shell script that 318 will exercise all the fixes, using the sample test_text 319 provided with each fix. Once done, the changes made will 320 be compared against the changes saved in the source directory. 321 If you are changing the tests or fixes, the change will likely 322 be highlighted. 323