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