OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gcc-4.2.2/] [fixincludes/] [README] - Blame information for rev 816

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 38 julius
 
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 
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 \n"
273
                 "#else\n"
274
                 "#include \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.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.