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