Commit | Line | Data |
---|---|---|
87fe2d9d FF |
1 | GDB SNAPSHOT SYSTEM |
2 | (general info) | |
225501b7 | 3 | Updated 5/24/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 | |
9 | particular random instant in time. When you use the snapshots, you should | |
10 | be able to maintain a local copy of GDB that is no more than one day older | |
11 | than the official source tree used by the GDB maintainers. | |
12 | ||
13 | The primary purpose of providing snapshots is to widen the group of | |
14 | motivated developers that would like to help test, debug, and enhance GDB, | |
15 | by providing you with access to the "latest and greatest" source. | |
16 | This has several advantages, and several disadvantages. | |
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 FF |
70 | |
71 | The current plan is to provide a full snapshot once weekly, and incremental | |
72 | diffs on a daily basis. Each daily diff will be relative to the source | |
73 | tree for the previous day after applying all incremental diffs to date. | |
74 | ||
75 | The files will be available via anonymous ftp from ftp.cygnus.com, in | |
76 | directory pub/gdb, and should look something like: | |
77 | ||
78 | gdb-930401.tar.z | |
79 | gdb-930401-930402.diff.z | |
80 | gdb-930402-930403.diff.z | |
81 | gdb-930403-930404.diff.z | |
82 | . | |
83 | . | |
84 | . | |
85 | ||
86 | At some point, the files should automatically appear during the evening | |
87 | as a result of an automatically run process each evening. For the moment | |
88 | however, the process will be manually run by one of the gdb maintainers | |
89 | and the appropriate files moved to the ftp area at some convenient point | |
90 | during the day. | |
91 | ||
d240e671 FF |
92 | Note that the current plan is to provide GNU gzip compressed files only. |
93 | You can ftp gzip from prep.ai.mit.edu in directory pub/gnu. | |
87fe2d9d FF |
94 | |
95 | Also, as the gcc developers did with their gcc snapshot system, even though | |
96 | we will make the snapshots available on a publically accessible ftp area, | |
97 | we ask that recipients not widely publicise their availability. The motivation | |
98 | for this request is not to hoard them, but to avoid the situation where | |
99 | the general GDB user base naively attempts to use the snapshots, has trouble | |
100 | with them, complains publically, and the reputation of GDB declines because | |
101 | of a perception of instability or lack of quality control. | |
102 | ||
103 | ||
104 | GDB TEST SUITE | |
838a1ac1 | 105 | -------------- |
87fe2d9d FF |
106 | |
107 | A test suite is distributed as an integral part of the snapshots. However, | |
108 | to use it you will need to get a copy of the dejagnu testing framework. | |
109 | Snapshots of dejagnu are available alongside the GDB snapshots, using | |
110 | the same naming conventions as the GDB snapshots. Once you have installed | |
111 | the dejagnu framework, a simple "make check" in the GDB directory should | |
112 | be sufficient to run the tests. | |
113 | ||
114 | Note that the test suite is still in its infancy. The test framework | |
115 | itself might not install on your system if you have an environment that | |
116 | is not similar to one that the GDB developers already use. The tests | |
117 | themselves only cover a small portion of GDB features, and what tests | |
118 | do exist for a feature are not exhaustive. New tests are welcomed. | |
119 | ||
120 | ||
d240e671 FF |
121 | GETTING HELP, GDB DISCUSSIONS, etc |
122 | ---------------------------------- | |
123 | ||
124 | Mail sent to gdb-testers@cygnus.com goes to everyone on the list of gdb | |
125 | testers, which should include everyone getting the gdb snapshots. It is | |
126 | appropriate whenever you wish your mail to be seen by all the testers. | |
127 | This would include announcements of any kind, notices of intent to implement | |
128 | a specific enhancement (to coordinate with other people on the list), etc. | |
129 | Before sending something to gdb-testers, ask yourself if what you are about | |
130 | to send would be something you would care to see show up in your mailbox if | |
131 | it was sent by someone else. | |
132 | ||
133 | Mail sent to gdb-patches@cygnus.com goes to gdb support people internal to | |
134 | Cygnus. Despite the name, it is appropriate for more than just patches. | |
135 | Questions about the snapshots, problems accessing the snapshots, bug reports | |
136 | without patches, requests for advice on how to track down a bug you have | |
137 | encountered, discussion about bug fixes or enhancements in progress, etc are | |
138 | all welcome in gdb-patches. Usually mail sent to gdb-patches will result in | |
139 | a short private email discussion between you and one or more of the gdb | |
140 | developers who can assist you with simple questions or handle your patches. | |
141 | Note that gdb-patches is *not* a general gdb electronic support line. | |
142 | If you are in need of such support, you probably should not be using the | |
143 | snapshots and should seek out one of the commercial suppliers of support | |
144 | for free software. | |
87fe2d9d FF |
145 | |
146 | Do *not* send any questions about the snapshots or patches specific to | |
147 | the snapshots to bug-gdb@prep.ai.mit.edu (gateway'd to the usenet group | |
148 | gnu.gdb.bug). Nobody there will have any idea what you are talking about | |
149 | and it will just cause confusion. | |
150 | ||
d240e671 | 151 | |
225501b7 FF |
152 | BUG REPORTS |
153 | ----------- | |
154 | ||
155 | Send bug reports to gdb-patches@cygnus.com. | |
156 | ||
157 | Note that since no testing is done on the snapshots, and snapshots may even | |
158 | be made when gdb is in an inconsistent state, it may not be unusual for an | |
159 | occasional snapshot to have a very obvious bug, such as failure to compile | |
160 | on *any* machine. It is likely that such bugs will be fixed by the next | |
161 | snapshot, so it really isn't necessary to report them unless they persist | |
162 | for a couple days. | |
163 | ||
164 | Bugs which are non-obvious, such as failure to compile on only a specific | |
165 | machine, a new machine dependent bug (particularly one not detected by the | |
166 | testsuite), missing machine dependent files, etc should be reported when | |
167 | you discover them, or have a suggested patch to fix them. | |
168 | ||
169 | ||
d240e671 FF |
170 | FORMAT FOR PATCHES |
171 | ------------------ | |
172 | ||
173 | If you have a fix for a bug, or an enhancement to submit, send your | |
174 | patch to gdb-patches@cygnus.com. Here are some simple guidelines for | |
175 | submitting patches: | |
87fe2d9d FF |
176 | |
177 | o Use "context diffs" for patches. A typical command for generating | |
178 | context diffs is "diff -rc gdb-old gdb-new". | |
179 | ||
180 | o Use the "minimalist approach" for patches. That is, each patch | |
181 | should address only one particular bug, new feature, etc. Do not | |
182 | save up many unrelated changes and submit them all in one big | |
183 | patch, since in general, the larger the patch the more difficult | |
184 | it is for us to decide if the patch is either correct or | |
185 | desirable. And if we find something about the patch that needs | |
186 | to be corrected before it can be installed, we would have to reject | |
187 | the entire patch, which might contain changes which otherwise would | |
188 | be accepted if submitted separately. | |
189 | ||
190 | o Submit a sample ChangeLog entry with your patch. See the existing | |
191 | GDB ChangeLog for examples of what a ChangeLog entry should look | |
192 | like. The emacs command ^X4A will create a ChangeLog entry header | |
193 | for you. | |
194 | ||
838a1ac1 | 195 | |
0f805efc | 196 | BISON and BYACC |
838a1ac1 | 197 | --------------- |
0f805efc | 198 | |
7508b5b2 FF |
199 | GDB's language parsers are all portable, and can be compiled with bison, |
200 | byacc, traditional Unix yacc, or other compatible parser generators. | |
0f805efc FF |
201 | For various reasons, Cygnus uses byacc rather than bison by default. When |
202 | a general gdb distribution is made, this default is switched back to bison. | |
203 | The snapshots follow the Cygnus default. Your options, if you do not already | |
204 | have byacc installed, include: | |
205 | ||
206 | o Hack the upper level Makefile.in lines that look like: | |
207 | ||
208 | BISON = `if [ -f $${rootme}/byacc/byacc ] ; \ | |
209 | then echo $${rootme}/byacc/byacc ; \ | |
210 | else echo byacc ; \ <== change | |
211 | fi` | |
212 | ||
7508b5b2 | 213 | to replace "byacc" with either "yacc" or "bison -y". |
0f805efc FF |
214 | |
215 | o Fetch the byacc snapshot from the same location as the gdb snapshots | |
216 | and install byacc. | |
217 | ||
218 | o Specify BISON=yacc on the make command line to override the default. | |
219 | ||
220 | ||
838a1ac1 FF |
221 | UNIX MAKE and GNU MAKE |
222 | ---------------------- | |
223 | ||
224 | When you build gdb in the same directory as the source, you should be able | |
225 | to use any available "make" that has traditional UNIX make functionality. | |
226 | If you build gdb in a separate directory tree from the source, using the | |
c66429de | 227 | configure "--srcdir" option, then only GNU make is fully supported, although |
838a1ac1 FF |
228 | other makes with complete VPATH support should work (SunOS make for example). |
229 | ||
230 | ||
231 | ||
87fe2d9d FF |
232 | Thanks for your help and support. |
233 | ||
234 | -Fred Fish | |
235 | Cygnus Support | |
236 |