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