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