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