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