gcc/fixinc/README

   1
   2 FIXINCLUDES OPERATION
   3 =====================
   4
   5 See also:  http://autogen.SourceForge.net/fixincludes
   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
  10 AutoGen (http://autogen.SourceForge.net, ver 4.x) uses these definitions
  11 to instantiate several different templates (gcc/fixinc/*.tpl) that then
  12 produces a fixincludes replacement shell script (inclhack.sh), a
  13 replacement binary program (fixincl.x).
  14
  15 If there is no special purpose script, then mkfixinc.sh will try to
  16 compile, link and execute the fixincl program.  Otherwise, it will
  17 install and use the current fixinc.* for that system instead.
  18 Also, on certain platforms (viz. those that do not have functional
  19 bidirectional pipes), the fixincl program is split into two.
  20 This should only concern you on DOS and BeOS.
  21
  22 Regards,
  23         Bruce <bkorb@gnu.org>
  24
  25
  26
  27 GCC MAINTAINER INFORMATION
  28 ==========================
  29
  30 If you are having some problem with a system header that is either
  31 broken by the manufacturer, or is broken by the fixinclude process,
  32 then you will need to alter or add information to the include fix
  33 definitions file, ``inclhack.def''.  Please also send relevant
  34 information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
  35 please, to me:  bkorb@gnu.org.
  36
  37 Once you have made your fix, it is necessary to have at least one
  38 test for it.  Specify the test with a "test_text" entry.  Run
  39 "make check" in the fixinc directory to verify both that your fix
  40 works (by correctly altering your test text) and that your fix
  41 does not suppress the work of other fixes.  You should readily
  42 be able to verify this as the "make check" process will print out
  43 context diffs of fixed files.  If everything looks fine, you can
  44 either use the diffs for a patch to the baseline files, or simply
  45 copy the result files (in the "tests/res/" subdirectory) into the
  46 baseline directory ("tests/base").
  47
  48 Here are the rules for making fixes in the inclhack.def file:
  49
  50 0.  If you are not the fixincludes maintainer, please send that
  51     person email about any changes you may want to make.  Thanks!
  52
  53 1.  Every fix must have a "hackname" that is compatible with C syntax
  54     for variable names and is unique without regard to alphabetic case.
  55     Please keep them alphabetical by this name.  :-)
  56
  57 2.  If the problem is known to exist only in certain files,
  58     then name each such file with a "files = " entry.
  59
  60 3.  It is relatively expensive to fire off a process to fix a source
  61     file, therefore write apply tests to avoid unnecessary fix
  62     processes.  The preferred apply tests are "select", "bypass" and
  63     "c_test" because they are performed internally.  "test" sends
  64     a command to a server shell that actually fires off one or more
  65     processes to do the testing.  Avoid it, if you can, but it is
  66     still more efficient than a fix process.  Also available is
  67     "mach".  If the target machine matches any of the named
  68     globbing-style patterns, then the machine name test will pass.
  69     It is desired, however, to limit the use of this test.
  70
  71     These tests are required to:
  72
  73     1.  Be positive for all header files that require the fix.
  74
  75     It is desireable to:
  76
  77     2.  Be negative as often as possible whenever the fix is not
  78         required, avoiding the process overhead.
  79
  80     It is nice if:
  81
  82     3.  The expression is as simple as possible to both
  83         process and understand by people.  :-)
  84
  85         Please take advantage of the fact AutoGen will glue
  86         together string fragments.  It helps.  Also take note
  87         that double quote strings and single quote strings have
  88         different formation rules.  Double quote strings are a
  89         tiny superset of ANSI-C string syntax.  Single quote
  90         strings follow shell single quote string formation
  91         rules, except that the backslash is processed before
  92         '\\', '\'' and '#' characters (using C character syntax).
  93
  94     Examples of test specifications:
  95
  96       hackname = broken_assert_stdio;
  97       files    = assert.h;
  98       select   = stderr;
  99       bypass   = "include.*stdio.h";
 100
 101     The ``broken_assert_stdio'' fix will be applied only to a file
 102     named "assert.h" if it contains the string "stderr" _and_ it
 103     does _not_ contain the expression "include.*stdio.h".
 104
 105       hackname = no_double_slash;
 106       c_test   = "double_slash";
 107
 108     The ``no_double_slash'' fix will be applied if the
 109     ``double_slash_test()'' function says to.  See ``fixtests.c''
 110     for documentation on how to include new functions into that
 111     module.
 112
 113 4.  There are currently four methods of fixing a file:
 114
 115     1.  a series of sed expressions.  Each will be an individual
 116         "-e" argument to a single invocation of sed.
 117
 118     2.  a shell script.  These scripts are _required_ to read all
 119         of stdin in order to avoid pipe stalls.  They may choose to
 120         discard the input.
 121
 122     3.  Replacement text.  If the replacement is empty, then no
 123         fix is applied.  Otherwise, the replacement text is
 124         written to the output file and no further fixes are
 125         applied.  If you really want a no-op file, replace the
 126         file with a comment.
 127
 128         Replacement text "fixes" must be first in this file!!
 129
 130     4.  A C language subroutine method for both tests and fixes.
 131         See ``fixtests.c'' for instructions on writing C-language
 132         applicability tests and ``fixfixes.c'' for C-language fixing.
 133         These files also contain tables that describe the currently
 134         implemented fixes and tests.
 135
 136     If at all possible, you should try to use one of the C language
 137     fixes as it is far more efficient.  There are currently five
 138     such fixes, three of which are very special purpose:
 139
 140     i) char_macro_def - This function repairs the definition of an
 141         ioctl macro that presumes CPP macro substitution within
 142         pairs of single quote characters.
 143
 144     ii) char_macro_use - This function repairs the usage of ioctl
 145         macros that no longer can wrap an argument with single quotes.
 146
 147     iii) machine_name - This function will look at "#if", "#ifdef",
 148         "#ifndef" and "#elif" directive lines and replace the first
 149         occurrence of a non-reserved name that is traditionally
 150         pre-defined by the native compiler.
 151
 152     The next two are for general use:
 153
 154     iv) wrap - wraps the entire file with "#ifndef", "#define" and
 155         "#endif" self-exclusionary text.  It also, optionally, inserts
 156         a prolog after the "#define" and an epilog just before the
 157         "#endif".  You can use this for a fix as follows:
 158
 159             c_fix     = wrap;
 160             c_fix_arg = "/* prolog text */";
 161             c_fix_arg = "/* epilog text */";
 162
 163         If you want an epilog without a prolog, set the first "c_fix_arg"
 164         to the empty string.  Both or the second "c_fix_arg"s may be
 165         omitted and the file will still be wrapped.
 166
 167         THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
 168
 169         If the regular expression '#if.*__need' is found, then it is
 170         assumed that the file needs to be read and interpreted more
 171         than once.  However, the prolog and epilog text (if any) will
 172         be inserted.
 173
 174     v) format - Replaces text selected with a regular expression with
 175         a specialized formating string.  The formatting works as follows:
 176         The format text is copied to the output until a '%' character
 177         is found.  If the character after the '%' is another '%', then
 178         one '%' is output and processing continues.  If the following
 179         character is not a digit, then the '%' and that character are
 180         copied and processing continues.  Finally, if the '%' *is*
 181         followed by a digit, that digit is used as an index into the
 182         regmatch_t array to replace the two characters with the matched
 183         text.  i.e.: "%0" is replaced by the full matching text, "%1"
 184         is the first matching sub-expression, etc.
 185
 186         This is used as follows:
 187
 188             c_fix     = format;
 189             c_fix_arg = "#ifndef %1\n%0\n#endif";
 190             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
 191
 192         This would wrap a traditional #define inside of a "#ifndef"/"#endif"
 193         pair.  The second "c_fix_arg" may be omitted *IF* there is
 194         a select clause and the first one matches the text you want
 195         replaced.  You may delete text by supplying an empty string for
 196         the format (the first "c_fix_arg").
 197
 198         Note: In general, a format c_fix may be used in place of one
 199         sed expression.  However, it will need to be rewritten by
 200         hand.  For example:
 201
 202         sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
 203                '@& || __GNUC__ >= 3@';
 204
 205         may be rewritten using a format c_fix as:
 206
 207         c_fix     = format;
 208         c_fix_arg = '%0 || __GNUC__ >= 3';
 209         c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
 210
 211         Multiple sed substitution expressions probably ought to remain sed
 212         expressions in order to maintain clarity.  Also note that if the
 213         second sed expression is the same as the first select expression,
 214         then you may omit the second c_fix_arg.  The select expression will
 215         be picked up and used in its absence.
 216
 217 EXAMPLES OF FIXES:
 218 ==================
 219
 220       hackname = AAA_ki_iface;
 221       replace; /* empty replacement -> no fixing the file */
 222
 223     When this ``fix'' is invoked, it will prevent any fixes
 224     from being applied.
 225
 226     ------------------
 227
 228       hackname = AAB_svr4_no_varargs;
 229       replace  = "/* This file was generated by fixincludes.  */\n"
 230                  "#ifndef _SYS_VARARGS_H\n"
 231                  "#define _SYS_VARARGS_H\n\n"
 232
 233                  "#ifdef __STDC__\n"
 234                  "#include <stdarg.h>\n"
 235                  "#else\n"
 236                  "#include <varargs.h>\n"
 237                  "#endif\n\n"
 238
 239                  "#endif  /* _SYS_VARARGS_H */\n";
 240
 241     When this ``fix'' is invoked, the replacement text will be
 242     emitted into the replacement include file.  No further fixes
 243     will be applied.
 244
 245     ------------------
 246
 247         hackname  = hpux11_fabsf;
 248         files     = math.h;
 249         select    = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
 250         bypass    = "__cplusplus";
 251
 252         c_fix     = format;
 253         c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
 254
 255         test_text =
 256         "#  define fabsf(x) ((float)fabs((double)(float)(x)))\n";
 257
 258     This fix will ensure that the #define for fabs is wrapped
 259     with C++ protection, providing the header is not already
 260     C++ aware.
 261
 262     ------------------
 263
 264 5.  Testing fixes.
 265
 266     The brute force method is, of course, to configure and build
 267     GCC.  But you can also:
 268
 269         cd ${top_builddir}/gcc
 270         rm -rf fixinc.sh include/ stmp-fixinc
 271         make stmp-fixinc
 272
 273     I would really recommend, however:
 274
 275         cd ${top_builddir}/gcc/fixinc
 276         make check
 277
 278     To do this, you *must* have autogen installed on your system.
 279     The "check" step will proceed to construct a shell script that
 280     will exercize all the fixes, using the sample test_text
 281     provided with each fix.  Once done, the changes made will
 282     be compared against the changes saved in the source directory.
 283     If you are changing the tests or fixes, the change will likely
 284     be highlighted.