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 fixincludes/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 fixincludes 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, synchronize 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, then 73 identify the files with "files = " entries. If you use fnmatch(3C) 74 wild card characters in a "files" entry, be certain that the first 75 "files" entry has no such character. Otherwise, the "make check" 76 machinery will attempt to create files with those characters in the 77 name. That is inconvenient. 78 793. It is relatively expensive to fire off a process to fix a source 80 file, therefore write apply tests to avoid unnecessary fix 81 processes. The preferred apply tests are "select", "bypass", "mach" 82 and "c-test" because they are performed internally: 83 84 * select - Run a regex on the contents of the file being considered. 85 All such regex-es must match. Matching is done with 86 extended regular expressions. 87 88 * bypass - Run a regex on the contents of the file being considered. 89 No such regex may match. 90 91 * c_test - call a function in fixtests.c. See that file. 92 93 * files - the "fnmatch" pattern of the file(s) to examine for 94 the issue. There may be several copies of this attribute. 95 If the header lives in a /usr/include subdirectory, be 96 sure to include that subdirectory in the name. e.g. net/if.h 97 98 * mach - Match the output of config.guess against a series of fnmatch 99 patterns. It must match at least one of the patterns, unless 100 "not-machine" has also been specified. In that case, the 101 config.guess output must not match any of the patterns. 102 103 The next test is relatively slow because it must be handled in a 104 separate shell process. Some platforms do not support server shells, 105 so the whole process is even slower and more cumbersome there. 106 107 * test - These should be arguments to the program, "/bin/test". 108 You may perform multiple commands, if you enclose them 109 in backquotes and echo out valid test arguments. For 110 example, you might echo out '0 -eq 1' if you want a false 111 result, or '0 -eq 0' for a true result. 112 113 These tests are required to: 114 115 1. Be positive for all header files that require the fix. 116 117 It is desirable to: 118 119 2. Be negative as often as possible whenever the fix is not 120 required, avoiding the process overhead. 121 122 It is nice if: 123 124 3. The expression is as simple as possible to both 125 process and understand by people. :-) 126 127 Please take advantage of the fact AutoGen will glue 128 together string fragments. It helps. Also take note 129 that double quote strings and single quote strings have 130 different formation rules. Double quote strings are a 131 tiny superset of ANSI-C string syntax. Single quote 132 strings follow shell single quote string formation 133 rules, except that the backslash is processed before 134 '\\', '\'' and '#' characters (using C character syntax). 135 136 Each test must pass or the fix is not applied. For example, 137 all "select" expressions must be found and not one "bypass" 138 selection may be found. 139 140 Examples of test specifications: 141 142 hackname = broken_assert_stdio; 143 files = assert.h; 144 select = stderr; 145 bypass = "include.*stdio.h"; 146 147 The ``broken_assert_stdio'' fix will be applied only to a file 148 named "assert.h" if it contains the string "stderr" _and_ it 149 does _not_ contain the expression "include.*stdio.h". 150 151 hackname = no_double_slash; 152 c_test = "double_slash"; 153 154 The ``no_double_slash'' fix will be applied if the 155 ``double_slash_test()'' function says to. See ``fixtests.c'' 156 for documentation on how to include new functions into that 157 module. 158 1594. There are currently four methods of fixing a file: 160 161 1. a series of sed expressions. Each will be an individual 162 "-e" argument to a single invocation of sed. 163 164 2. a shell script. These scripts are _required_ to read all 165 of stdin in order to avoid pipe stalls. They may choose to 166 discard the input. 167 168 3. Replacement text. If the replacement is empty, then no 169 fix is applied. Otherwise, the replacement text is 170 written to the output file and no further fixes are 171 applied. If you really want a no-op file, replace the 172 file with a comment. 173 174 Replacement text "fixes" must be first in this file!! 175 176 4. A C language subroutine method for both tests and fixes. 177 See ``fixtests.c'' for instructions on writing C-language 178 applicability tests and ``fixfixes.c'' for C-language fixing. 179 These files also contain tables that describe the currently 180 implemented fixes and tests. 181 182 If at all possible, you should try to use one of the C language 183 fixes as it is far more efficient. There are currently five 184 such fixes, three of which are very special purpose: 185 186 i) char_macro_def - This function repairs the definition of an 187 ioctl macro that presumes CPP macro substitution within 188 pairs of single quote characters. 189 190 ii) char_macro_use - This function repairs the usage of ioctl 191 macros that no longer can wrap an argument with single quotes. 192 193 iii) machine_name - This function will look at "#if", "#ifdef", 194 "#ifndef" and "#elif" directive lines and replace the first 195 occurrence of a non-reserved name that is traditionally 196 pre-defined by the native compiler. 197 198 The next two are for general use: 199 200 iv) wrap - wraps the entire file with "#ifndef", "#define" and 201 "#endif" self-exclusionary text. It also, optionally, inserts 202 a prolog after the "#define" and an epilog just before the 203 "#endif". You can use this for a fix as follows: 204 205 c_fix = wrap; 206 c_fix_arg = "/* prolog text */"; 207 c_fix_arg = "/* epilog text */"; 208 209 If you want an epilog without a prolog, set the first "c_fix_arg" 210 to the empty string. Both or the second "c_fix_arg"s may be 211 omitted and the file will still be wrapped. 212 213 THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER: 214 215 If the regular expression '#if.*__need' is found, then it is 216 assumed that the file needs to be read and interpreted more 217 than once. However, the prolog and epilog text (if any) will 218 be inserted. 219 220 v) format - Replaces text selected with a regular expression with 221 a specialized formating string. The formatting works as follows: 222 The format text is copied to the output until a '%' character 223 is found. If the character after the '%' is another '%', then 224 one '%' is output and processing continues. If the following 225 character is not a digit, then the '%' and that character are 226 copied and processing continues. Finally, if the '%' *is* 227 followed by a digit, that digit is used as an index into the 228 regmatch_t array to replace the two characters with the matched 229 text. i.e.: "%0" is replaced by the full matching text, "%1" 230 is the first matching sub-expression, etc. 231 232 This is used as follows: 233 234 c_fix = format; 235 c_fix_arg = "#ifndef %1\n%0\n#endif"; 236 c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*"; 237 238 This would wrap a one line #define inside of a "#ifndef"/"#endif" 239 pair. The second "c_fix_arg" may be omitted *IF* there is at least 240 one select clause and the first one identifies the text you wish to 241 reformat. It will then be used as the second "c_fix_arg". You may 242 delete the selected text by supplying an empty string for the 243 replacement format (the first "c_fix_arg"). 244 245 Note: In general, a format c_fix may be used in place of one 246 sed expression. However, it will need to be rewritten by 247 hand. For example: 248 249 sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$' 250 '@& || __GNUC__ >= 3@'; 251 252 may be rewritten using a format c_fix as: 253 254 c_fix = format; 255 c_fix_arg = '%0 || __GNUC__ >= 3'; 256 c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'; 257 258 Multiple sed substitution expressions probably ought to remain sed 259 expressions in order to maintain clarity. Also note that if the 260 second sed expression is the same as the first select expression, 261 then you may omit the second c_fix_arg. The select expression will 262 be picked up and used in its absence. 263 264EXAMPLES OF FIXES: 265================== 266 267 hackname = AAA_ki_iface; 268 replace; /* empty replacement -> no fixing the file */ 269 270 When this ``fix'' is invoked, it will prevent any fixes 271 from being applied. 272 273 ------------------ 274 275 hackname = AAB_svr4_no_varargs; 276 replace = "/* This file was generated by fixincludes. */\n" 277 "#ifndef _SYS_VARARGS_H\n" 278 "#define _SYS_VARARGS_H\n\n" 279 280 "#ifdef __STDC__\n" 281 "#include <stdarg.h>\n" 282 "#else\n" 283 "#include <varargs.h>\n" 284 "#endif\n\n" 285 286 "#endif /* _SYS_VARARGS_H */\n"; 287 288 When this ``fix'' is invoked, the replacement text will be 289 emitted into the replacement include file. No further fixes 290 will be applied. 291 292 ------------------ 293 294 hackname = hpux11_fabsf; 295 files = math.h; 296 select = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*"; 297 bypass = "__cplusplus"; 298 299 c_fix = format; 300 c_fix_arg = "#ifndef __cplusplus\n%0\n#endif"; 301 302 test_text = 303 "# define fabsf(x) ((float)fabs((double)(float)(x)))\n"; 304 305 This fix will ensure that the #define for fabs is wrapped 306 with C++ protection, providing the header is not already 307 C++ aware. 308 309 ------------------ 310 3115. Testing fixes. 312 313 The brute force method is, of course, to configure and build 314 GCC. But you can also: 315 316 cd ${top_builddir}/gcc 317 rm -rf fixinc.sh include/ stmp-fixinc 318 make stmp-fixinc 319 320 I would really recommend, however: 321 322 cd ${top_builddir}/fixincludes 323 make check 324 325 To do this, you *must* have autogen installed on your system. 326 The "check" step will proceed to construct a shell script that 327 will exercise all the fixes, using the sample test_text 328 provided with each fix. Once done, the changes made will 329 be compared against the changes saved in the source directory. 330 If you are changing the tests or fixes, the change will likely 331 be highlighted. 332