gdb/doc/snapshots.readme

   1                          GDB SNAPSHOT SYSTEM
   2                             (general info)
   3                             Updated 5/24/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
  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
  69 ------------------------
  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
  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.
  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
 105 --------------
 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
 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.
 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
 151
 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 Missing files should always be reported, since they usually mean there
 165 is a problem with the snapshot-generating process and we won't know
 166 about them unless someone tells us.
 167
 168 Bugs which are non-obvious, such as failure to compile on only a
 169 specific machine, a new machine dependent or obscure bug (particularly
 170 one not detected by the testsuite), etc should be reported when you
 171 discover them, or have a suggested patch to fix them.
 172
 173
 174 FORMAT FOR PATCHES
 175 ------------------
 176
 177 If you have a fix for a bug, or an enhancement to submit, send your
 178 patch to gdb-patches@cygnus.com.  Here are some simple guidelines for
 179 submitting patches:
 180
 181     o   Use "context diffs" for patches.  A typical command for generating
 182         context diffs is "diff -rc gdb-old gdb-new".
 183
 184     o   Use the "minimalist approach" for patches.  That is, each patch
 185         should address only one particular bug, new feature, etc.  Do not
 186         save up many unrelated changes and submit them all in one big
 187         patch, since in general, the larger the patch the more difficult
 188         it is for us to decide if the patch is either correct or
 189         desirable.  And if we find something about the patch that needs
 190         to be corrected before it can be installed, we would have to reject
 191         the entire patch, which might contain changes which otherwise would
 192         be accepted if submitted separately.
 193
 194     o   Submit a sample ChangeLog entry with your patch.  See the existing
 195         GDB ChangeLog for examples of what a ChangeLog entry should look
 196         like.  The emacs command ^X4A will create a ChangeLog entry header
 197         for you.
 198
 199
 200 BISON and BYACC
 201 ---------------
 202
 203 GDB's language parsers are all portable, and can be compiled with bison,
 204 byacc, traditional Unix yacc, or other compatible parser generators.
 205 For various reasons, Cygnus uses byacc rather than bison by default.  When
 206 a general gdb distribution is made, this default is switched back to bison.
 207 The snapshots follow the Cygnus default.  Your options, if you do not already
 208 have byacc installed, include:
 209
 210     o   Hack the upper level Makefile.in lines that look like:
 211
 212         BISON = `if [ -f $${rootme}/byacc/byacc ] ; \
 213                     then echo $${rootme}/byacc/byacc ; \
 214                     else echo byacc ; \                         <== change
 215                 fi`
 216
 217         to replace "byacc" with either "yacc" or "bison -y".
 218
 219     o   Fetch the byacc snapshot from the same location as the gdb snapshots
 220         and install byacc.
 221
 222     o   Specify BISON=yacc on the make command line to override the default.
 223
 224
 225 UNIX MAKE and GNU MAKE
 226 ----------------------
 227
 228 When you build gdb in the same directory as the source, you should be able
 229 to use any available "make" that has traditional UNIX make functionality.
 230 If you build gdb in a separate directory tree from the source, using the
 231 configure "--srcdir" option, then only GNU make is fully supported, although
 232 other makes with complete VPATH support should work (SunOS make for example).
 233
 234
 235
 236 Thanks for your help and support.
 237
 238 -Fred Fish
 239  Cygnus Support
 240