fixincludes/README

   1
   2 FIXINCLUDES OPERATION
   3 =====================
   4
   5 See also:  http://autogen.SourceForge.net/fixinc.html
   6
   7 The set of fixes required was distilled down to just the data required
   8 to specify what needed to happen for each fix.  Those data were edited
   9 into a file named gcc/fixinc/inclhack.def.  A program called AutoGen
  10 (http://autogen.SourceForge.net) uses these definitions to instantiate
  11 several different templates that then produces code for a fixinclude
  12 program (fixincl.x) and a shell script to test its functioning.  On
  13 certain platforms (viz. those that do not have functional bidirectional
  14 pipes), the fixincl program is split into two.  This should only concern
  15 you on DOS and BeOS.
  16
  17 Regards,
  18         Bruce <bkorb@gnu.org>
  19
  20
  21
  22 GCC MAINTAINER INFORMATION
  23 ==========================
  24
  25 If you are having some problem with a system header that is either
  26 broken by the manufacturer, or is broken by the fixinclude process,
  27 then you will need to alter or add information to the include fix
  28 definitions file, ``inclhack.def''.  Please also send relevant
  29 information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
  30 please, to me:  bkorb@gnu.org.
  31
  32 To make your fix, you will need to do several things:
  33
  34 1.  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
  37 2.  Edit "inclhack.def" to reflect the changes you need to make.
  38     See below for information on how to make those changes.
  39
  40 3.  Run the "genfixes" shell script to produce a new copy of
  41     the "fixincl.x" file.
  42
  43 4.  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
  48 5.  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
  54 6.  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
  59 7.  Rerun "make check" and verify that there are no issues left.
  60
  61
  62 MAKING CHANGES TO INCLHACK.DEF
  63 ==============================
  64
  65 0.  If you are not the fixincludes maintainer, please send that
  66     person email about any changes you may want to make.  Thanks!
  67
  68 1.  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
  72 2.  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
  79 3.  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.
  86
  87     * bypass - Run a regex on the contents of the file being considered.
  88                No such regex may match.
  89
  90     * c-test - call a function in fixtests.c.  See that file.
  91
  92     * mach   - Match the output of config.conf against a series of fnmatch
  93                patterns.  It must match at least one of the patterns, unless
  94                "not-machine" has also been specified.  In that case, the
  95                config.conf output must not match any of the patterns.
  96
  97     The next test is relatively slow because it must be handled in a
  98     separate shell process.  Some platforms do not support server shells,
  99     so the whole process is even slower and more cumbersome there.
 100
 101     * test   - These should be arguments to the program, "/bin/test".
 102                You may perform multiple commands, if you enclose them
 103                in backquotes and echo out valid test arguments.  For
 104                example, you might echo out '0 -eq 1' if you want a false
 105                result, or '0 -eq 0' for a true result.
 106
 107     These tests are required to:
 108
 109     1.  Be positive for all header files that require the fix.
 110
 111     It is desireable to:
 112
 113     2.  Be negative as often as possible whenever the fix is not
 114         required, avoiding the process overhead.
 115
 116     It is nice if:
 117
 118     3.  The expression is as simple as possible to both
 119         process and understand by people.  :-)
 120
 121         Please take advantage of the fact AutoGen will glue
 122         together string fragments.  It helps.  Also take note
 123         that double quote strings and single quote strings have
 124         different formation rules.  Double quote strings are a
 125         tiny superset of ANSI-C string syntax.  Single quote
 126         strings follow shell single quote string formation
 127         rules, except that the backslash is processed before
 128         '\\', '\'' and '#' characters (using C character syntax).
 129
 130     Each test must pass or the fix is not applied.  For example,
 131     all "select" expressions must be found and not one "bypass"
 132     selection may be found.
 133
 134     Examples of test specifications:
 135
 136       hackname = broken_assert_stdio;
 137       files    = assert.h;
 138       select   = stderr;
 139       bypass   = "include.*stdio.h";
 140
 141     The ``broken_assert_stdio'' fix will be applied only to a file
 142     named "assert.h" if it contains the string "stderr" _and_ it
 143     does _not_ contain the expression "include.*stdio.h".
 144
 145       hackname = no_double_slash;
 146       c_test   = "double_slash";
 147
 148     The ``no_double_slash'' fix will be applied if the
 149     ``double_slash_test()'' function says to.  See ``fixtests.c''
 150     for documentation on how to include new functions into that
 151     module.
 152
 153 4.  There are currently four methods of fixing a file:
 154
 155     1.  a series of sed expressions.  Each will be an individual
 156         "-e" argument to a single invocation of sed.
 157
 158     2.  a shell script.  These scripts are _required_ to read all
 159         of stdin in order to avoid pipe stalls.  They may choose to
 160         discard the input.
 161
 162     3.  Replacement text.  If the replacement is empty, then no
 163         fix is applied.  Otherwise, the replacement text is
 164         written to the output file and no further fixes are
 165         applied.  If you really want a no-op file, replace the
 166         file with a comment.
 167
 168         Replacement text "fixes" must be first in this file!!
 169
 170     4.  A C language subroutine method for both tests and fixes.
 171         See ``fixtests.c'' for instructions on writing C-language
 172         applicability tests and ``fixfixes.c'' for C-language fixing.
 173         These files also contain tables that describe the currently
 174         implemented fixes and tests.
 175
 176     If at all possible, you should try to use one of the C language
 177     fixes as it is far more efficient.  There are currently five
 178     such fixes, three of which are very special purpose:
 179
 180     i) char_macro_def - This function repairs the definition of an
 181         ioctl macro that presumes CPP macro substitution within
 182         pairs of single quote characters.
 183
 184     ii) char_macro_use - This function repairs the usage of ioctl
 185         macros that no longer can wrap an argument with single quotes.
 186
 187     iii) machine_name - This function will look at "#if", "#ifdef",
 188         "#ifndef" and "#elif" directive lines and replace the first
 189         occurrence of a non-reserved name that is traditionally
 190         pre-defined by the native compiler.
 191
 192     The next two are for general use:
 193
 194     iv) wrap - wraps the entire file with "#ifndef", "#define" and
 195         "#endif" self-exclusionary text.  It also, optionally, inserts
 196         a prolog after the "#define" and an epilog just before the
 197         "#endif".  You can use this for a fix as follows:
 198
 199             c_fix     = wrap;
 200             c_fix_arg = "/* prolog text */";
 201             c_fix_arg = "/* epilog text */";
 202
 203         If you want an epilog without a prolog, set the first "c_fix_arg"
 204         to the empty string.  Both or the second "c_fix_arg"s may be
 205         omitted and the file will still be wrapped.
 206
 207         THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
 208
 209         If the regular expression '#if.*__need' is found, then it is
 210         assumed that the file needs to be read and interpreted more
 211         than once.  However, the prolog and epilog text (if any) will
 212         be inserted.
 213
 214     v) format - Replaces text selected with a regular expression with
 215         a specialized formating string.  The formatting works as follows:
 216         The format text is copied to the output until a '%' character
 217         is found.  If the character after the '%' is another '%', then
 218         one '%' is output and processing continues.  If the following
 219         character is not a digit, then the '%' and that character are
 220         copied and processing continues.  Finally, if the '%' *is*
 221         followed by a digit, that digit is used as an index into the
 222         regmatch_t array to replace the two characters with the matched
 223         text.  i.e.: "%0" is replaced by the full matching text, "%1"
 224         is the first matching sub-expression, etc.
 225
 226         This is used as follows:
 227
 228             c_fix     = format;
 229             c_fix_arg = "#ifndef %1\n%0\n#endif";
 230             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
 231
 232         This would wrap a traditional #define inside of a "#ifndef"/"#endif"
 233         pair.  The second "c_fix_arg" may be omitted *IF* there is
 234         a select clause and the first one matches the text you want
 235         replaced.  You may delete text by supplying an empty string for
 236         the format (the first "c_fix_arg").
 237
 238         Note: In general, a format c_fix may be used in place of one
 239         sed expression.  However, it will need to be rewritten by
 240         hand.  For example:
 241
 242         sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
 243                '@& || __GNUC__ >= 3@';
 244
 245         may be rewritten using a format c_fix as:
 246
 247         c_fix     = format;
 248         c_fix_arg = '%0 || __GNUC__ >= 3';
 249         c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
 250
 251         Multiple sed substitution expressions probably ought to remain sed
 252         expressions in order to maintain clarity.  Also note that if the
 253         second sed expression is the same as the first select expression,
 254         then you may omit the second c_fix_arg.  The select expression will
 255         be picked up and used in its absence.
 256
 257 EXAMPLES OF FIXES:
 258 ==================
 259
 260       hackname = AAA_ki_iface;
 261       replace; /* empty replacement -> no fixing the file */
 262
 263     When this ``fix'' is invoked, it will prevent any fixes
 264     from being applied.
 265
 266     ------------------
 267
 268       hackname = AAB_svr4_no_varargs;
 269       replace  = "/* This file was generated by fixincludes.  */\n"
 270                  "#ifndef _SYS_VARARGS_H\n"
 271                  "#define _SYS_VARARGS_H\n\n"
 272
 273                  "#ifdef __STDC__\n"
 274                  "#include <stdarg.h>\n"
 275                  "#else\n"
 276                  "#include <varargs.h>\n"
 277                  "#endif\n\n"
 278
 279                  "#endif  /* _SYS_VARARGS_H */\n";
 280
 281     When this ``fix'' is invoked, the replacement text will be
 282     emitted into the replacement include file.  No further fixes
 283     will be applied.
 284
 285     ------------------
 286
 287         hackname  = hpux11_fabsf;
 288         files     = math.h;
 289         select    = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
 290         bypass    = "__cplusplus";
 291
 292         c_fix     = format;
 293         c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
 294
 295         test_text =
 296         "#  define fabsf(x) ((float)fabs((double)(float)(x)))\n";
 297
 298     This fix will ensure that the #define for fabs is wrapped
 299     with C++ protection, providing the header is not already
 300     C++ aware.
 301
 302     ------------------
 303
 304 5.  Testing fixes.
 305
 306     The brute force method is, of course, to configure and build
 307     GCC.  But you can also:
 308
 309         cd ${top_builddir}/gcc
 310         rm -rf fixinc.sh include/ stmp-fixinc
 311         make stmp-fixinc
 312
 313     I would really recommend, however:
 314
 315         cd ${top_builddir}/gcc/fixinc
 316         make check
 317
 318     To do this, you *must* have autogen installed on your system.
 319     The "check" step will proceed to construct a shell script that
 320     will exercise all the fixes, using the sample test_text
 321     provided with each fix.  Once done, the changes made will
 322     be compared against the changes saved in the source directory.
 323     If you are changing the tests or fixes, the change will likely
 324     be highlighted.