gcc/fixinc/README

   1
   2 FIXINCLUDES OPERATION
   3 =====================
   4
   5 See also:  http://autogen.linuxbox.com/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 new file named gcc/fixinc/inclhack.def.  A program called
  10 AutoGen (http://autogen.linuxbox.com) uses these definitions to
  11 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) and a script to drive the
  14 binary fixincl.sh).
  15
  16 If there is no special purpose script, then mkfixinc.sh will try to
  17 compile, link and test execute the binary version.  If it cannot be
  18 successfully built, the shell version will be used instead.  If
  19 mkfixinc.sh determines that your system needs machine-specific fixes
  20 that have not yet been applied to inclhack.def, it will install and
  21 use the current fixinc.* for that system instead.
  22
  23 Usually, the mkfixinc.sh script will be able to detect when
  24 the binary is not runable.  If you do have problems, however,
  25 please try configuring "--without-fast-fixincludes".  Thank you.
  26
  27 Regards,
  28         Bruce <autogen@linuxbox.com>
  29
  30
  31
  32 POSSIBLE PROBLEMS
  33 =================
  34
  35 There may be some systems on which the fixinc binary program appears
  36 to be functional, but fails to work.  If you are experiencing this
  37 problem, then copy the script ${src}/gcc/fixinc/inclhack.sh into
  38 ${builddir}/gcc/fixinc.sh and run make again.
  39
  40 And, *please* also report the problem with a description of
  41 the failure mode (symptoms) and the output from:
  42
  43         egcs/config.guess
  44
  45 to me:  Bruce Korb <autogen@linuxbox.com>
  46
  47
  48
  49 GCC MAINTAINER INFORMATION
  50 ==========================
  51
  52 If you are having some problem with a system header that is either
  53 broken by the manufacturer, or is broken by the fixinclude process,
  54 then you will need to alter or add information to the include fix
  55 definitions file, ``inclhack.def''.  Please also send relevant
  56 information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
  57 please, to me:  autogen@linuxbox.com.
  58
  59 Here are the rules for making fixes in the inclhack.def file:
  60
  61 1.  Every fix must have a "hackname" that is compatible with C syntax
  62     for variable names and is unique without regard to alphabetic case.
  63     Please keep them alphabetical by this name.  :-)
  64
  65 2.  If the problem is known to exist only in certain files,
  66     then name each such file with a "files = " entry.
  67
  68 3.  It is relatively expensive to fire off a process to fix a source
  69     file, therefore write apply tests to avoid unnecessary fix
  70     processes.  The preferred apply tests are "select", "bypass" and
  71     "c_test" because they are performed internally.  "test" sends
  72     a command to a server shell that actually fires off one or more
  73     processes to do the testing.  Avoid it, if you can, but it is
  74     still more efficient than a fix process.  Also available is
  75     "mach".  If the target machine matches any of the named
  76     globbing-style patterns, then the machine name test will pass.
  77     It is desired, however, to limit the use of this test.
  78
  79     These tests are required to:
  80
  81     1.  Be positive for all header files that require the fix.
  82
  83     It is desireable to:
  84
  85     2.  Be negative as often as possible whenever the fix is not
  86         required, avoiding the process overhead.
  87
  88     It is nice if:
  89
  90     3.  The expression is as simple as possible to both
  91         process and uderstand by people.  :-)
  92
  93         Please take advantage of the fact AutoGen will glue
  94         together string fragments.  It helps.  Also take note
  95         that double quote strings and single quote strings have
  96         different formation rules.  Double quote strings are
  97         a tiny superset of C string syntax.  Single quote strings
  98         follow shell single quote string formation rules, except
  99         that the backslash is processed before '\\', '\'' and '#'
 100         characters (using C character syntax).
 101
 102     Examples of test specifications:
 103
 104       hackname = broken_assert_stdio;
 105       files    = assert.h;
 106       select   = stderr;
 107       bypass   = "include.*stdio.h";
 108
 109     The ``broken_assert_stdio'' fix will be applied only to a file
 110     named "assert.h" if it contains the string "stderr" _and_ it
 111     does _not_ contain the expression "include.*stdio.h".
 112
 113       hackname = no_double_slash;
 114       c_test   = "double_slash";
 115
 116     The ``no_double_slash'' fix will be applied if the
 117     ``double_slash_test()'' function says to.  See ``fixtests.c''
 118     for documentation on how to include new functions into that
 119     module.
 120
 121 4.  There are currently four methods of fixing a file:
 122
 123     1.  a series of sed expressions.  Each will be an individual
 124         "-e" argument to a single invocation of sed.
 125
 126     2.  a shell script.  These scripts are _required_ to read all
 127         of stdin in order to avoid pipe stalls.  They may choose to
 128         discard the input.
 129
 130     3.  A C language subroutine method for both tests and fixes.
 131
 132     4.  Replacement text.  If the replacement is empty, then
 133         no fix is applied.  Otherwise, the replacement text is written
 134         to the output file and no further fixes are applied.
 135
 136         Replacement text "fixes" must be first in this file!!
 137
 138     Examples of fixes:
 139     ------------------
 140
 141       hackname = AAA_ki_iface;
 142       replace; /* empty replacement -> no fixing the file */
 143
 144     When this ``fix'' is invoked, it will prevent any fixes
 145     from being applied.
 146
 147     ------------------
 148
 149       hackname = AAB_svr4_no_varargs;
 150       replace  = "/* This file was generated by fixincludes.  */\n"
 151                  "#ifndef _SYS_VARARGS_H\n"
 152                  "#define _SYS_VARARGS_H\n\n"
 153
 154                  "#ifdef __STDC__\n"
 155                  "#include <stdarg.h>\n"
 156                  "#else\n"
 157                  "#include <varargs.h>\n"
 158                  "#endif\n\n"
 159
 160                  "#endif  /* _SYS_VARARGS_H */\n";
 161
 162     When this ``fix'' is invoked, the replacement text will be
 163     emitted into the replacement include file.  No further fixes
 164     will be applied.
 165
 166     ------------------
 167
 168       hackname = dec_intern_asm;
 169       files    = c_asm.h;
 170       sed = "/^[ \t]*float[ \t]*fasm/i\\\n#ifdef __DECC\n";
 171       sed = "/^[ \t]*#[ \t]*pragma[ \t]*intrinsic([ \t]*dasm/a\\\n"
 172             "#endif\n";
 173
 174     When this ``fix'' is invoked, sed will be run on the original
 175     file with two "-e" arguments.  Since these arguments have double
 176     quoted string values, the strings actually passed to ``sed''
 177     will have been processed in the same fashion that the C compiler
 178     processes its string specifications.  Including the concatenation
 179     of the two pieces of the second sed "-e" argument.
 180
 181     ------------------
 182
 183       hackname = m88k_multi_incl;
 184       shell    =
 185         "echo Fixing $file, to protect against multiple inclusion. >&2
 186         cpp_wrapper=`echo $file | sed -e 's,\\.,_,g' -e 's,/,_,g'`
 187         echo \"#ifndef __GCC_GOT_${cpp_wrapper}_\"
 188         echo \"#define __GCC_GOT_${cpp_wrapper}_\"
 189         cat
 190         echo \"#endif /* ! __GCC_GOT_${cpp_wrapper}_ */\"";
 191
 192     This is a shell script fix.  Note the ``cat'' without any arguments.
 193     This will drain stdin.  If the contents of the file were to be
 194     discarded, you would have to have something like ``cat > /dev/null''
 195     in the script.
 196
 197     ------------------
 198
 199       hackname = no_double_slash;
 200       c_fix    = "no_double_slash";
 201
 202     This specifies a fix to be supplied via a hand coded internal
 203     function named ``no_double_slash_fix()''.  See ``fixfixes.c''
 204     for documentation on how to include new functions into that
 205     module.
 206