Commit | Line | Data |
---|---|---|
87fe2d9d FF |
1 | GDB SNAPSHOT SYSTEM |
2 | (general info) | |
51477494 | 3 | Updated 8/23/93 |
87fe2d9d FF |
4 | |
5 | WHAT ARE GDB SNAPSHOTS | |
838a1ac1 | 6 | ---------------------- |
87fe2d9d FF |
7 | |
8 | Snapshots are an "image" of the main GDB development tree, captured at a | |
51477494 FF |
9 | particular random instant in time. When you use the snapshots, you should be |
10 | able to maintain a local copy of GDB that is no more than one day older than | |
11 | the official source tree used by the GDB maintainers. | |
87fe2d9d | 12 | |
51477494 FF |
13 | The primary purpose of providing snapshots is to widen the group of motivated |
14 | developers that would like to help test, debug, and enhance GDB, by providing | |
15 | you with access to the "latest and greatest" source. This has several | |
16 | advantages, and several disadvantages. | |
87fe2d9d FF |
17 | |
18 | First the advantages: | |
19 | ||
20 | o Once we have a large base of motivated testers using the snapshots, | |
21 | this should provide good coverage across all currently supported | |
22 | GDB hosts and targets. If a new bug is introduced in GDB due to | |
23 | fixing another bug or ongoing development, it should become | |
24 | obvious much more quickly and get fixed before the next general | |
25 | net release. This should help to reduce the chances of GDB being | |
26 | released to the general public with a major bug that went unnoticed | |
27 | during the release cycle testing because they are machine dependent. | |
28 | We hope to greatly improve GDB's stability and reliability by | |
29 | involving more people and more execution environments in the | |
30 | prerelease testing. | |
31 | ||
32 | o With access to the latest source, any diffs that you send to fix | |
33 | bugs or add new features should be much easier for the GDB team | |
34 | to merge into the official source base (after suitable review | |
35 | of course). This encourages us to merge your changes quicker, | |
36 | while they are still "fresh". | |
37 | ||
38 | o Once your diffs are merged, you can obtain a new copy of GDB | |
39 | containing your changes almost immediately. Thus you do not | |
40 | have to maintain local copies of your changes for any longer | |
41 | than it takes to get them merged into the official source base. | |
42 | This encourages you to send in changes quicker. | |
43 | ||
44 | And the disadvantages: | |
45 | ||
46 | o The snapshot you get will be largely untested and of unknown quality. | |
47 | It may fail to configure or compile. It may have serious bugs. | |
48 | You should always keep a copy of the last known working version | |
49 | before updating to the current snapshot, or at least be able to | |
50 | regenerate a working version if the latest snapshot is unusable | |
51 | in your environment for some reason. | |
52 | ||
53 | If a production version of GDB has a bug and a snapshot has the fix, | |
54 | and you care about stability, you should put only the fix for that | |
55 | particular problem into your production version. Of course, if you | |
56 | are eager to test GDB, you can use the snapshot versions in your | |
57 | daily work, but users who have not been consulted about whether they | |
58 | feel like testing GDB should generally have something which is at | |
59 | least as bug free as the last released version. | |
60 | ||
61 | o Providing timely response to your questions, bug reports, and | |
62 | submitted patches will require the GDB development team to allocate | |
63 | time from an already thin time budget. Please try to help us make | |
64 | this time as productive as possible. See the section below about | |
65 | how to submit changes. | |
66 | ||
67 | ||
68 | HOW TO GET THE SNAPSHOTS | |
838a1ac1 | 69 | ------------------------ |
87fe2d9d | 70 | |
51477494 FF |
71 | The current plan is to provide a full snapshot daily, so that users getting a |
72 | snapshot for the first time, or updating after a long period of not updating, | |
73 | can get the latest version in a single operation. Along with the full | |
74 | snapshot, we will provide incremental diffs on a daily basis. Each daily diff | |
75 | will be relative to the source tree after applying all previous daily diffs. | |
76 | The daily diffs are for people who have relatively low bandwidth ftp or uucp | |
77 | connections. | |
87fe2d9d FF |
78 | |
79 | The files will be available via anonymous ftp from ftp.cygnus.com, in | |
80 | directory pub/gdb, and should look something like: | |
81 | ||
82 | gdb-930401.tar.z | |
83 | gdb-930401-930402.diff.z | |
84 | gdb-930402-930403.diff.z | |
85 | gdb-930403-930404.diff.z | |
86 | . | |
87 | . | |
88 | . | |
89 | ||
51477494 FF |
90 | At some point, the files should automatically appear during the evening as a |
91 | result of an automatically run process each evening. For the moment however, | |
92 | the process will be manually run by one of the gdb maintainers and the | |
93 | appropriate files moved to the ftp area at some convenient point during the | |
94 | day. | |
87fe2d9d | 95 | |
51477494 FF |
96 | Note that the current plan is to provide GNU gzip compressed files only. You |
97 | can ftp gzip from prep.ai.mit.edu in directory pub/gnu. | |
87fe2d9d | 98 | |
a3e0cf1e FF |
99 | Also, even though we will make the snapshots available on a publically |
100 | accessible ftp area, we ask that recipients not widely publicise their | |
101 | availability. The motivation for this request is not to hoard them, but to | |
102 | avoid the situation where the general GDB user base naively attempts to use | |
103 | the snapshots, has trouble with them, complains publically, and the reputation | |
104 | of GDB suffers because of a perception of instability or lack of quality | |
105 | control. | |
87fe2d9d FF |
106 | |
107 | ||
108 | GDB TEST SUITE | |
838a1ac1 | 109 | -------------- |
87fe2d9d | 110 | |
51477494 FF |
111 | A test suite is distributed as an integral part of the snapshots. However, to |
112 | use it you will need to get a copy of the dejagnu testing framework. | |
113 | Snapshots of dejagnu are available alongside the GDB snapshots, using the same | |
114 | naming conventions as the GDB snapshots. Once you have installed the dejagnu | |
115 | framework, a simple "make check" in the GDB directory should be sufficient to | |
116 | run the tests. | |
87fe2d9d | 117 | |
51477494 FF |
118 | Note that the test suite is still in its infancy. The test framework itself |
119 | might not install on your system if you have an environment that is not | |
120 | similar to one that the GDB developers already use. The tests themselves only | |
121 | cover a small portion of GDB features, and what tests do exist for a feature | |
122 | are not exhaustive. New tests are welcomed. | |
87fe2d9d FF |
123 | |
124 | ||
d240e671 FF |
125 | GETTING HELP, GDB DISCUSSIONS, etc |
126 | ---------------------------------- | |
127 | ||
128 | Mail sent to gdb-testers@cygnus.com goes to everyone on the list of gdb | |
129 | testers, which should include everyone getting the gdb snapshots. It is | |
51477494 FF |
130 | appropriate whenever you wish your mail to be seen by all the testers. This |
131 | would include announcements of any kind, notices of intent to implement a | |
132 | specific enhancement (to coordinate with other people on the list), etc. | |
133 | Before sending something to gdb-testers, ask yourself if what you are about to | |
134 | send would be something you would care to see show up in your mailbox if it | |
135 | was sent by someone else. | |
d240e671 FF |
136 | |
137 | Mail sent to gdb-patches@cygnus.com goes to gdb support people internal to | |
138 | Cygnus. Despite the name, it is appropriate for more than just patches. | |
139 | Questions about the snapshots, problems accessing the snapshots, bug reports | |
140 | without patches, requests for advice on how to track down a bug you have | |
141 | encountered, discussion about bug fixes or enhancements in progress, etc are | |
51477494 FF |
142 | all welcome in gdb-patches. Usually mail sent to gdb-patches will result in a |
143 | short private email discussion between you and one or more of the gdb | |
d240e671 | 144 | developers who can assist you with simple questions or handle your patches. |
51477494 FF |
145 | Note that gdb-patches is *not* a general gdb electronic support line. If you |
146 | are in need of such support, you probably should not be using the snapshots | |
147 | and should seek out one of the commercial suppliers of support for free | |
148 | software. | |
87fe2d9d | 149 | |
51477494 FF |
150 | Do *not* send any questions about the snapshots or patches specific to the |
151 | snapshots to bug-gdb@prep.ai.mit.edu (gateway'd to the usenet group | |
152 | gnu.gdb.bug). Nobody there will have any idea what you are talking about and | |
153 | it will just cause confusion. | |
87fe2d9d | 154 | |
d240e671 | 155 | |
225501b7 FF |
156 | BUG REPORTS |
157 | ----------- | |
158 | ||
159 | Send bug reports to gdb-patches@cygnus.com. | |
160 | ||
51477494 FF |
161 | Note that since no testing is done on the snapshots, and snapshots may even be |
162 | made when gdb is in an inconsistent state, it may not be unusual for an | |
163 | occasional snapshot to have a very obvious bug, such as failure to compile on | |
164 | *any* machine. It is likely that such bugs will be fixed by the next | |
165 | snapshot, so it really isn't necessary to report them unless they persist for | |
166 | a couple days. | |
225501b7 | 167 | |
51477494 FF |
168 | Missing files should always be reported, since they usually mean there is a |
169 | problem with the snapshot-generating process and we won't know about them | |
170 | unless someone tells us. | |
7edd8068 | 171 | |
51477494 FF |
172 | Bugs which are non-obvious, such as failure to compile on only a specific |
173 | machine, a new machine dependent or obscure bug (particularly one not detected | |
174 | by the testsuite), etc should be reported when you discover them, or have a | |
175 | suggested patch to fix them. | |
225501b7 FF |
176 | |
177 | ||
d240e671 FF |
178 | FORMAT FOR PATCHES |
179 | ------------------ | |
180 | ||
51477494 FF |
181 | If you have a fix for a bug, or an enhancement to submit, send your patch to |
182 | gdb-patches@cygnus.com. Here are some simple guidelines for submitting | |
183 | patches: | |
87fe2d9d FF |
184 | |
185 | o Use "context diffs" for patches. A typical command for generating | |
186 | context diffs is "diff -rc gdb-old gdb-new". | |
187 | ||
188 | o Use the "minimalist approach" for patches. That is, each patch | |
189 | should address only one particular bug, new feature, etc. Do not | |
190 | save up many unrelated changes and submit them all in one big | |
191 | patch, since in general, the larger the patch the more difficult | |
192 | it is for us to decide if the patch is either correct or | |
193 | desirable. And if we find something about the patch that needs | |
194 | to be corrected before it can be installed, we would have to reject | |
195 | the entire patch, which might contain changes which otherwise would | |
196 | be accepted if submitted separately. | |
197 | ||
198 | o Submit a sample ChangeLog entry with your patch. See the existing | |
199 | GDB ChangeLog for examples of what a ChangeLog entry should look | |
200 | like. The emacs command ^X4A will create a ChangeLog entry header | |
201 | for you. | |
202 | ||
838a1ac1 | 203 | |
0f805efc | 204 | BISON and BYACC |
838a1ac1 | 205 | --------------- |
0f805efc | 206 | |
7508b5b2 | 207 | GDB's language parsers are all portable, and can be compiled with bison, |
51477494 FF |
208 | byacc, traditional Unix yacc, or other compatible parser generators. For |
209 | various reasons, Cygnus uses byacc rather than bison by default. When a | |
210 | general gdb distribution is made, this default is switched back to bison. The | |
211 | snapshots follow the Cygnus default. Your options, if you do not already have | |
212 | byacc installed, include: | |
0f805efc FF |
213 | |
214 | o Hack the upper level Makefile.in lines that look like: | |
215 | ||
216 | BISON = `if [ -f $${rootme}/byacc/byacc ] ; \ | |
217 | then echo $${rootme}/byacc/byacc ; \ | |
218 | else echo byacc ; \ <== change | |
219 | fi` | |
220 | ||
7508b5b2 | 221 | to replace "byacc" with either "yacc" or "bison -y". |
0f805efc FF |
222 | |
223 | o Fetch the byacc snapshot from the same location as the gdb snapshots | |
224 | and install byacc. | |
225 | ||
226 | o Specify BISON=yacc on the make command line to override the default. | |
227 | ||
228 | ||
838a1ac1 FF |
229 | UNIX MAKE and GNU MAKE |
230 | ---------------------- | |
231 | ||
51477494 FF |
232 | When you build gdb in the same directory as the source, you should be able to |
233 | use any available "make" that has traditional UNIX make functionality. If you | |
234 | build gdb in a separate directory tree from the source, using the configure | |
235 | "--srcdir" option, then only GNU make is fully supported, although other makes | |
236 | with complete VPATH support should work (SunOS make for example). | |
838a1ac1 FF |
237 | |
238 | ||
239 | ||
87fe2d9d FF |
240 | Thanks for your help and support. |
241 | ||
242 | -Fred Fish | |
243 | Cygnus Support |