Daily bump.
[official-gcc.git] / gcc / README-bugs
blob06e15bb8af708d6ab812b58b75d79798f2e8e9e9
1 The purpose of GCC pretesting is to verify that the new GCC
2 distribution, about to be released, works properly on your system *with
3 no change whatever*, when installed following the precise
4 recommendations that come with the distribution.
6 Here are some guidelines on how to do pretesting so as to make it
7 helpful.  All of them follow from common sense together with the
8 nature of the purpose and the situation.
10 * It is absolutely vital that you mention even the smallest change or
11 departure from the standard sources and installation procedure.
13 Otherwise, you are not testing the same program that I wrote.  Testing
14 a different program is usually of no use whatever.  It can even cause
15 trouble if you fail to tell me that you tested some other program
16 instead of what I know as GCC.  I might think that GCC works, when in
17 fact it has not been properly tried, and might have a glaring fault.
19 * Even changing the compilation options counts as a change in the
20 program.  The GCC sources specify which compilation options to use.
21 Some of them are specified in makefiles, and some in machine-specific
22 configuration files.
24 You have ways to override this--but if you do, then you are not
25 testing what ordinary users will do.  Therefore, when pretesting, it
26 is vital to test with the default compilation options.
28 (It is okay to test with nonstandard options as well as testing with
29 the standard ones.)
31 * The machine and system configuration files of GCC are parts of
32 GCC.  So when you test GCC, you need to do it with the
33 configuration files that come with GCC.
35 If GCC does not come with configuration files for a certain machine,
36 and you test it with configuration files that don't come with GCC,
37 this is effectively changing GCC.  Because the crucial fact about
38 the planned release is that, without changes, it doesn't work on that
39 machine.
41 To make GCC work on that machine, I would need to install new
42 configuration files.  That is not out of the question, since it is
43 safe--it certainly won't break any other machines that already work.
44 But you will have to rush me the legal papers to give the FSF
45 permission to use a large piece of text.
47 * Look for recommendations for your system.
49 You can find these recommendations in the Installation node of the
50 manual, and in the file INSTALL.  (These two files have the same text.)
52 These files say which configuration name to use for your machine, so
53 use the ones that are recommended.  If you guess, you might guess
54 wrong and encounter spurious difficulties.  What's more, if you don't
55 follow the recommendations then you aren't helping to test that its
56 recommendations are valid.
58 These files may describe other things that you need to do to make GCC
59 work on your machine.  If so, you should follow these recommendations
60 also, for the same reason.
62 Also look at the Trouble chapter of the manual for items that
63 pertain to your machine.
65 * Don't delay sending information.
67 When you find a problem, please double check it if you can do so
68 quickly.  But don't spend a long time double-checking.  A good rule is
69 always to tell me about every problem on the same day you encounter
70 it, even if that means you can't find a solution before you report the
71 problem.
73 I'd much rather hear about a problem today and a solution tomorrow
74 than get both of them tomorrow at the same time.
76 * Make each bug report self-contained.
78 If you refer back to another message, whether from you or from someone
79 else, then it will be necessary for anyone who wants to investigate
80 the bug to find the other message.  This may be difficult, it is
81 probably time-consuming.
83 To help me save time, simply copy the relevant parts of any previous
84 messages into your own bug report.
86 In particular, if I ask you for more information because a bug report
87 was incomplete, it is best to send me the *entire* collection of
88 relevant information, all together.  If you send just the additional
89 information, that makes me do extra work.  There is even a risk that
90 I won't remember what question you are sending me the answer to.
92 * Always be precise when talking about changes you have made.  Show
93 things rather than describing them.  Use exact filenames (relative to
94 the main directory of the distribution), not partial ones.  For
95 example, say "I changed Makefile" rather than "I changed the
96 makefile".  Instead of saying "I defined the MUMBLE macro", send a
97 diff that shows your change.
99 * Always use `diff -c' to make diffs.  If you don't include context,
100 it may be hard for me to figure out where you propose to make the
101 changes.  I might have to ignore your patch because I can't tell what
102 it means.
104 * When you write a fix, keep in mind that I can't install a change
105 that would break other systems.
107 People often suggest fixing a problem by changing machine-independent
108 files such as toplev.c to do something special that a particular
109 system needs.  Sometimes it is totally obvious that such changes would
110 break GCC for almost all users.  I can't possibly make a change like
111 that.  All I can do is send it back to you and ask you to find a fix
112 that is safe to install.
114 Sometimes people send fixes that *might* be an improvement in
115 general--but it is hard to be sure of this.  I can install such
116 changes some of the time, but not during pretest, when I am trying to
117 get a new version to work reliably as quickly as possible.
119 The safest changes for me to install are changes to the configuration
120 files for a particular machine.  At least I know those can't create
121 bugs on other machines.
123 * Don't try changing GCC unless it fails to work if you don't change it.
125 * Don't even suggest changes that would only make GCC cleaner.
126 Every change I install could introduce a bug, so I won't install
127 a change unless I see it is necessary.
129 * If you would like to suggest changes for purposes other than fixing
130 serious bugs, don't wait till pretest time.  Instead, send them just
131 after I make a release.  That's the best time for me to install them.
133 * In some cases, if you don't follow these guidelines, your
134 information might still be useful, but I might have to do more work to
135 make use of it.  Unfortunately, I am so far behind in my work that I
136 just can't get the job done unless you help me to do it efficiently.
139                                 Thank you
140                                    rms
142 Local Variables:
143 mode: text
144 End: