README-alpha

   1                          GNU libc SNAPSHOT SYSTEM
   2                             (general info)
   3                            Updated 1997-9-26
   4
   5 WHAT ARE GNU libc SNAPSHOTS
   6 ---------------------------
   7
   8 Snapshots are an "image" of the main glibc 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 libc that is no more than one day older than
  11 the official source tree used by the libc 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 glibc, 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         glibc hosts and targets.  If a new bug is introduced in glibc 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 glibc 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 glibc'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 glibc 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 glibc
  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 glibc 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 glibc, 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 glibc 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 glibc 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 WHO SHOULD TRY THE SNAPSHOTS
  69 ----------------------------
  70
  71 Remember, these are snapshots not tested versions.  So if you use
  72 these versions you should be able to
  73
  74     o   make sure your system stays usable
  75
  76     o   locate and hopefully fix problems
  77
  78     o   to port glibc to a new target yourself
  79
  80 You should not use the snapshots if
  81
  82     o   your system is needed in a production environment which needs
  83         stability
  84
  85     o   you expect us to fix your problems since you somehow depend on them.
  86         You must be willing to fix the problems yourself, we don't want to
  87         see "I have problems, fix this" messages.
  88
  89
  90 HOW TO GET THE SNAPSHOTS
  91 ------------------------
  92
  93 At the moment we provide a full snapshot weekly (every sunday), so
  94 that users getting a snapshot for the first time, or updating after
  95 a long period of not updating, can get the latest version in a single
  96 operation.  Along with the full snapshot, we will provide incremental
  97 diffs on a nearly daily basis (whenever code changes).  Each daily
  98 diff will be relative to the source tree after applying all previous
  99 daily diffs.  The daily diffs are for people who have relatively low
 100 bandwidth ftp or uucp connections.
 101
 102 The files will be available via anonymous ftp from alpha.gnu.org, in
 103 directory /gnu/libc and on linux.kernel.org in /pub/software/libs/glibc.  The
 104 directories should look something like:
 105
 106         libc-970921.tar.gz
 107         libc-970917-970922.diff.gz
 108         libc-970922-970925.diff.gz
 109         .
 110         .
 111         .
 112
 113 Please note that the snapshots on alpha.gnu.org and on
 114 linux.kernel.org are not always in sync. Patches to some files might
 115 appear a day a diff earlier or later on alpha than on kernel.
 116 Use always alpha or always kernel but don't mix them.
 117
 118 There are sometimes additionally test releases of the add-ons available in
 119 these directories.  If a new version of an add-on is available it is normally
 120 required for the corresponding snapshot so always pay attention for these.
 121
 122 Note that we provide GNU gzip compressed files only.  You can ftp gzip
 123 from ftp.gnu.org in directory pub/gnu.
 124
 125 In some cases the dates for diffs and snapshots do not match like in the
 126 example above.  The full release is for 970921 but the patch is for
 127 970917-970922.  This only means that nothing changed between 970917 and 970922
 128 and that you have to use this patch on top of the 970921 snapshot since the
 129 patch is made on 970922.
 130
 131 Also, as the gcc developers did with their gcc snapshot system, even though we
 132 will make the snapshots available on a publically accessible ftp area, we ask
 133 that recipients not widely publicise their availability.  The motivation for
 134 this request is not to hoard them, but to avoid the situation where the
 135 general glibc user base naively attempts to use the snapshots, has trouble with
 136 them, complains publically, and the reputation of glibc declines because of a
 137 perception of instability or lack of quality control.
 138
 139
 140 GLIBC TEST SUITE
 141 ----------------
 142
 143 A test suite is distributed as an integral part of the snapshots.  A simple
 144 "make check" in your build directory is sufficient to run the tests.  glibc
 145 should pass all tests and if any fails, please report it.  A failure might not
 146 originate from a bug in glibc but also from bugs in the tools, e.g. with gcc
 147 2.7.2.x the math tests fail some of the tests because of compiler bugs.
 148
 149 Note that the test suite is still in its infancy.  The tests themselves only
 150 cover a small portion of libc features, and where tests do exist for a feature
 151 they are not exhaustive.  New tests are welcome.
 152
 153
 154 GETTING HELP, GLIBC DISCUSSIONS, etc
 155 ------------------------------------
 156
 157 People who want to help with glibc and who test out snapshots
 158 regularly should get on the libc-alpha@sourceware.cygnus.com mailing
 159 list by sending an email to libc-alpha-subscribe@sourceware.cygnus.com.
 160 This list is meant (as the name suggests) for the discussion of test
 161 releases and also reports for them.  People who are on this list are
 162 welcome to post questions of general interest.
 163
 164 People who are not only willing to test the snapshots but instead
 165 really want to help developing glibc should contact
 166 libc-hacker-subscribe@sourceware.cygnus.com.org to be put on the developers
 167 mailing list.  This list is really only meant for developers.  No
 168 questions about installation problems or other simple topics are
 169 wanted nor will they be answered.
 170
 171 Do *not* send any questions about the snapshots or patches specific to the
 172 snapshots to bug-glibc@gnu.org.  Nobody there will have any idea what
 173 you are talking about and it will just cause confusion.
 174
 175
 176 BUG REPORTS
 177 -----------
 178
 179 Send bug reports directly to Ulrich Drepper <drepper@gnu.org>.  Please
 180 do *not* use the glibcbug script for reporting bugs in the snapshots.
 181 glibcbug should only be used for problems with the official released versions.
 182 We don't like bug reports in the bug database because otherwise the impression
 183 of instability or lack of quality control of glibc as a whole might manifest
 184 in people's mind.
 185
 186 Note that since no testing is done on the snapshots, and snapshots may even be
 187 made when glibc is in an inconsistent state, it may not be unusual for an
 188 occasional snapshot to have a very obvious bug, such as failure to compile on
 189 *any* machine.  It is likely that such bugs will be fixed by the next
 190 snapshot, so it really isn't necessary to report them unless they persist for
 191 a couple of days.
 192
 193 Missing files should always be reported, since they usually mean there is a
 194 problem with the snapshot-generating process and we won't know about them
 195 unless someone tells us.
 196
 197 Bugs which are non-obvious, such as failure to compile on only a specific
 198 machine, a new machine dependent or obscure bug (particularly one not detected
 199 by the testsuite), etc should be reported when you discover them, or have a
 200 suggested patch to fix them.
 201
 202
 203 FORMAT FOR PATCHES
 204 ------------------
 205
 206 If you have a fix for a bug, or an enhancement to submit, send your patch to
 207 Ulrich Drepper <drepper@gnu.org>.  Here are some simple guidelines for
 208 submitting patches:
 209
 210     o   Use "unified diffs" for patches.  A typical command for generating
 211         context diffs is "diff -ru glibc-old glibc-patched".
 212
 213     o   Use the "minimalist approach" for patches.  That is, each patch
 214         should address only one particular bug, new feature, etc.  Do not
 215         save up many unrelated changes and submit them all in one big
 216         patch, since in general, the larger the patch the more difficult
 217         it is for us to decide if the patch is either correct or
 218         desirable.  And if we find something about the patch that needs
 219         to be corrected before it can be installed, we would have to reject
 220         the entire patch, which might contain changes which otherwise would
 221         be accepted if submitted separately.
 222
 223     o   Submit a sample ChangeLog entry with your patch.  See the existing
 224         glibc ChangeLog for examples of what a ChangeLog entry should look
 225         like.  The emacs command ^X4A will create a ChangeLog entry header
 226         for you.
 227
 228
 229 BUILDING SNAPSHOTS
 230 ------------------
 231
 232 The `best' way to build glibc is to use an extra directory, e.g.:
 233 tar xzf libc-970921.tar.gz
 234 mkdir build-glibc
 235 cd build-glibc
 236 ../libc-970921/configure ...
 237
 238 In this way you can easily clean up (since `make clean' doesn't work at
 239 the moment) and rebuild glibc.
 240
 241
 242 NECESSARY TOOLS
 243 ---------------
 244
 245 For the recommended versions of gcc, binutils, make, texinfo, gettext,
 246 autoconf and other tools which might be especially needed when using patches,
 247 please read the file INSTALL.
 248
 249
 250 HOW CAN YOU HELP
 251 ----------------
 252
 253 It helps already a lot if you just install glibc on your system and try to
 254 solve any problems.  You might want to look at the file `PROJECTS' and help
 255 with one of those projects, fix some bugs (see `BUGS' or the bug database),
 256 port to an unsupported platform, ...
 257
 258
 259 FURTHER DOCUMENTATION
 260 ---------------------
 261
 262 A lot of questions are answered in the FAQ.  The files `INSTALL', `README' and
 263 `NOTES' contain the most important documentation.  Furthermore glibc has its
 264 own 700+ pages info documentation, ...
 265
 266
 267
 268 And finally a word of caution: The libc is one of the most fundamental parts
 269 of your system - and these snapshots are untested and come without any
 270 guarantee or warranty.  You might be lucky and everything works or you might
 271 crash your system.  If you install a glibc snapshot as primary library, you
 272 should have a backup somewhere.
 273
 274 On many systems it is also a problem to replace the libc while the system is
 275 running.  In the worst case on broken OSes some systems crash.  On better
 276 systems you can move the old libc aside but removing it will cause problems
 277 since there are still processes using this libc image and so you might have to
 278 check the filesystem to get rid of the libc data.  One good alternative (which
 279 is also safer) is to use a chroot'ed environment.
 280
 281 Thanks for your help and support.
 282
 283 Thanks to Fred Fish from Cygnus for the original version of this text
 284 (for GDB).
 285
 286
 287 Ulrich Drepper