gdb/doc/snapshots.readme

   1                          GDB SNAPSHOT SYSTEM
   2                             (general info)
   3                            Updated 8/23/93
   4
   5 WHAT ARE GDB SNAPSHOTS
   6 ----------------------
   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 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.
  12
  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.
  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
  69 ------------------------
  70
  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.
  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
  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.
  95
  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.
  98
  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.
 106
 107
 108 GDB TEST SUITE
 109 --------------
 110
 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.
 117
 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.
 123
 124
 125 GETTING HELP, GDB DISCUSSIONS, etc
 126 ----------------------------------
 127
 128 Mail sent to gdb-testers@cygnus.com goes to everyone on the list of
 129 gdb testers, which should include everyone getting the gdb snapshots.
 130 It is appropriate whenever you wish your mail to be seen by all the
 131 testers.  This would include announcements of any kind, notices of
 132 intent to implement a specific enhancement (to coordinate with other
 133 people on the list), etc.  Before sending something to gdb-testers,
 134 ask yourself if what you are about to send would be something you
 135 would care to see show up in your mailbox if it was sent by someone
 136 else.  For administrative things ("remove me from gdb-testers", etc.),
 137 send mail to gdb-testers-request@cygnus.com.
 138
 139 Mail sent to gdb-patches@cygnus.com goes to gdb support people internal to
 140 Cygnus.  Despite the name, it is appropriate for more than just patches.
 141 Questions about the snapshots, problems accessing the snapshots, bug reports
 142 without patches, requests for advice on how to track down a bug you have
 143 encountered, discussion about bug fixes or enhancements in progress, etc are
 144 all welcome in gdb-patches.  Usually mail sent to gdb-patches will result in a
 145 short private email discussion between you and one or more of the gdb
 146 developers who can assist you with simple questions or handle your patches.
 147 Note that gdb-patches is *not* a general gdb electronic support line.  If you
 148 are in need of such support, you probably should not be using the snapshots
 149 and should seek out one of the commercial suppliers of support for free
 150 software.
 151
 152 Do *not* send any questions about the snapshots or patches specific to the
 153 snapshots to bug-gdb@prep.ai.mit.edu (gateway'd to the usenet group
 154 gnu.gdb.bug).  Nobody there will have any idea what you are talking about and
 155 it will just cause confusion.
 156
 157
 158 BUG REPORTS
 159 -----------
 160
 161 Send bug reports to gdb-patches@cygnus.com.
 162
 163 Note that since no testing is done on the snapshots, and snapshots may even be
 164 made when gdb is in an inconsistent state, it may not be unusual for an
 165 occasional snapshot to have a very obvious bug, such as failure to compile on
 166 *any* machine.  It is likely that such bugs will be fixed by the next
 167 snapshot, so it really isn't necessary to report them unless they persist for
 168 a couple days.
 169
 170 Missing files should always be reported, since they usually mean there is a
 171 problem with the snapshot-generating process and we won't know about them
 172 unless someone tells us.
 173
 174 Bugs which are non-obvious, such as failure to compile on only a specific
 175 machine, a new machine dependent or obscure bug (particularly one not detected
 176 by the testsuite), etc should be reported when you discover them, or have a
 177 suggested patch to fix them.
 178
 179
 180 FORMAT FOR PATCHES
 181 ------------------
 182
 183 If you have a fix for a bug, or an enhancement to submit, send your patch to
 184 gdb-patches@cygnus.com.  Here are some simple guidelines for submitting
 185 patches:
 186
 187     o   Use "context diffs" for patches.  A typical command for generating
 188         context diffs is "diff -rc gdb-old gdb-new".
 189
 190     o   Use the "minimalist approach" for patches.  That is, each patch
 191         should address only one particular bug, new feature, etc.  Do not
 192         save up many unrelated changes and submit them all in one big
 193         patch, since in general, the larger the patch the more difficult
 194         it is for us to decide if the patch is either correct or
 195         desirable.  And if we find something about the patch that needs
 196         to be corrected before it can be installed, we would have to reject
 197         the entire patch, which might contain changes which otherwise would
 198         be accepted if submitted separately.
 199
 200     o   Submit a sample ChangeLog entry with your patch.  See the existing
 201         GDB ChangeLog for examples of what a ChangeLog entry should look
 202         like.  The emacs command ^X4A will create a ChangeLog entry header
 203         for you.
 204
 205
 206 BISON and BYACC
 207 ---------------
 208
 209 GDB's language parsers are all portable, and can be compiled with bison,
 210 byacc, traditional Unix yacc, or other compatible parser generators.  For
 211 various reasons, Cygnus uses byacc rather than bison by default.  When a
 212 general gdb distribution is made, this default is switched back to bison.  The
 213 snapshots follow the Cygnus default.  Your options, if you do not already have
 214 byacc installed, include:
 215
 216     o   Hack the upper level Makefile.in lines that look like:
 217
 218         BISON = `if [ -f $${rootme}/byacc/byacc ] ; \
 219                     then echo $${rootme}/byacc/byacc ; \
 220                     else echo byacc ; \                         <== change
 221                 fi`
 222
 223         to replace "byacc" with either "yacc" or "bison -y".
 224
 225     o   Fetch the byacc snapshot from the same location as the gdb snapshots
 226         and install byacc.
 227
 228     o   Specify BISON=yacc on the make command line to override the default.
 229
 230
 231 UNIX MAKE and GNU MAKE
 232 ----------------------
 233
 234 When you build gdb in the same directory as the source, you should be able to
 235 use any available "make" that has traditional UNIX make functionality.  If you
 236 build gdb in a separate directory tree from the source, using the configure
 237 "--srcdir" option, then only GNU make is fully supported, although other makes
 238 with complete VPATH support should work (SunOS make for example).
 239
 240
 241
 242 Thanks for your help and support.
 243
 244 -Fred Fish
 245  Cygnus Support