| GNU libc SNAPSHOT SYSTEM |
| (general info) |
| Updated 1997-9-26 |
| |
| WHAT ARE GNU libc SNAPSHOTS |
| --------------------------- |
| |
| Snapshots are an "image" of the main glibc development tree, captured at a |
| particular random instant in time. When you use the snapshots, you should be |
| able to maintain a local copy of libc that is no more than one day older than |
| the official source tree used by the libc maintainers. |
| |
| The primary purpose of providing snapshots is to widen the group of motivated |
| developers that would like to help test, debug, and enhance glibc, by providing |
| you with access to the "latest and greatest" source. This has several |
| advantages, and several disadvantages. |
| |
| First the advantages: |
| |
| o Once we have a large base of motivated testers using the snapshots, |
| this should provide good coverage across all currently supported |
| glibc hosts and targets. If a new bug is introduced in glibc due to |
| fixing another bug or ongoing development, it should become |
| obvious much more quickly and get fixed before the next general |
| net release. This should help to reduce the chances of glibc being |
| released to the general public with a major bug that went unnoticed |
| during the release cycle testing because they are machine dependent. |
| We hope to greatly improve glibc's stability and reliability by |
| involving more people and more execution environments in the |
| prerelease testing. |
| |
| o With access to the latest source, any diffs that you send to fix |
| bugs or add new features should be much easier for the glibc team |
| to merge into the official source base (after suitable review |
| of course). This encourages us to merge your changes quicker, |
| while they are still "fresh". |
| |
| o Once your diffs are merged, you can obtain a new copy of glibc |
| containing your changes almost immediately. Thus you do not |
| have to maintain local copies of your changes for any longer |
| than it takes to get them merged into the official source base. |
| This encourages you to send in changes quicker. |
| |
| And the disadvantages: |
| |
| o The snapshot you get will be largely untested and of unknown quality. |
| It may fail to configure or compile. It may have serious bugs. |
| You should always keep a copy of the last known working version |
| before updating to the current snapshot, or at least be able to |
| regenerate a working version if the latest snapshot is unusable |
| in your environment for some reason. |
| |
| If a production version of glibc has a bug and a snapshot has the fix, |
| and you care about stability, you should put only the fix for that |
| particular problem into your production version. Of course, if you |
| are eager to test glibc, you can use the snapshot versions in your |
| daily work, but users who have not been consulted about whether they |
| feel like testing glibc should generally have something which is at |
| least as bug free as the last released version. |
| |
| o Providing timely response to your questions, bug reports, and |
| submitted patches will require the glibc development team to allocate |
| time from an already thin time budget. Please try to help us make |
| this time as productive as possible. See the section below about |
| how to submit changes. |
| |
| |
| WHO SHOULD TRY THE SNAPSHOTS |
| ---------------------------- |
| |
| Remember, these are snapshots not tested versions. So if you use |
| these versions you should be able to |
| |
| o make sure your system stays usable |
| |
| o locate and hopefully fix problems |
| |
| o to port glibc to a new target yourself |
| |
| You should not use the snapshots if |
| |
| o your system is needed in a production environment which needs |
| stability |
| |
| o you expect us to fix your problems since you somehow depend on them. |
| You must be willing to fix the problems yourself, we don't want to |
| see "I have problems, fix this" messages. |
| |
| |
| HOW TO GET THE SNAPSHOTS |
| ------------------------ |
| |
| At the moment we provide a full snapshot weekly (every sunday), so |
| that users getting a snapshot for the first time, or updating after |
| a long period of not updating, can get the latest version in a single |
| operation. Along with the full snapshot, we will provide incremental |
| diffs on a nearly daily basis (whenever code changes). Each daily |
| diff will be relative to the source tree after applying all previous |
| daily diffs. The daily diffs are for people who have relatively low |
| bandwidth ftp or uucp connections. |
| |
| The files will be available via anonymous ftp from alpha.gnu.org, in |
| directory /gnu/libc and on linux.kernel.org in /pub/software/libs/glibc. The |
| directories should look something like: |
| |
| libc-970921.tar.gz |
| libc-970917-970922.diff.gz |
| libc-970922-970925.diff.gz |
| . |
| . |
| . |
| |
| Please note that the snapshots on alpha.gnu.org and on |
| linux.kernel.org are not always in sync. Patches to some files might |
| appear a day a diff earlier or later on alpha than on kernel. |
| Use always alpha or always kernel but don't mix them. |
| |
| There are sometimes additionally test releases of the add-ons available in |
| these directories. If a new version of an add-on is available it is normally |
| required for the corresponding snapshot so always pay attention for these. |
| |
| Note that we provide GNU gzip compressed files only. You can ftp gzip |
| from ftp.gnu.org in directory pub/gnu. |
| |
| In some cases the dates for diffs and snapshots do not match like in the |
| example above. The full release is for 970921 but the patch is for |
| 970917-970922. This only means that nothing changed between 970917 and 970922 |
| and that you have to use this patch on top of the 970921 snapshot since the |
| patch is made on 970922. |
| |
| Also, as the gcc developers did with their gcc snapshot system, even though we |
| will make the snapshots available on a publically accessible ftp area, we ask |
| that recipients not widely publicise their availability. The motivation for |
| this request is not to hoard them, but to avoid the situation where the |
| general glibc user base naively attempts to use the snapshots, has trouble with |
| them, complains publically, and the reputation of glibc declines because of a |
| perception of instability or lack of quality control. |
| |
| |
| GLIBC TEST SUITE |
| ---------------- |
| |
| A test suite is distributed as an integral part of the snapshots. A simple |
| "make check" in your build directory is sufficient to run the tests. glibc |
| should pass all tests and if any fails, please report it. A failure might not |
| originate from a bug in glibc but also from bugs in the tools, e.g. with gcc |
| 2.7.2.x the math tests fail some of the tests because of compiler bugs. |
| |
| Note that the test suite is still in its infancy. The tests themselves only |
| cover a small portion of libc features, and where tests do exist for a feature |
| they are not exhaustive. New tests are welcome. |
| |
| |
| GETTING HELP, GLIBC DISCUSSIONS, etc |
| ------------------------------------ |
| |
| People who want to help with glibc and who test out snapshots regularly should |
| get on the libc-alpha@cygnus.com mailing list by sending an email to |
| libc-alpha-request@cygnus.com. This list is meant (as the name suggests) |
| for the discussion of test releases and also reports for them. People who are |
| on this list are welcome to post questions of general interest. |
| |
| People who are not only willing to test the snapshots but instead really want |
| to help developing glibc should contact libc-hacker-request@cygnus.com.org to |
| be put on the developers mailing list. This list is really only meant for |
| developers. No questions about installation problems or other simple topics |
| are wanted nor will they be answered. |
| |
| Do *not* send any questions about the snapshots or patches specific to the |
| snapshots to bug-glibc@gnu.org. Nobody there will have any idea what |
| you are talking about and it will just cause confusion. |
| |
| |
| BUG REPORTS |
| ----------- |
| |
| Send bug reports directly to Ulrich Drepper <drepper@gnu.org>. Please |
| do *not* use the glibcbug script for reporting bugs in the snapshots. |
| glibcbug should only be used for problems with the official released versions. |
| We don't like bug reports in the bug database because otherwise the impression |
| of instability or lack of quality control of glibc as a whole might manifest |
| in people's mind. |
| |
| Note that since no testing is done on the snapshots, and snapshots may even be |
| made when glibc is in an inconsistent state, it may not be unusual for an |
| occasional snapshot to have a very obvious bug, such as failure to compile on |
| *any* machine. It is likely that such bugs will be fixed by the next |
| snapshot, so it really isn't necessary to report them unless they persist for |
| a couple of days. |
| |
| Missing files should always be reported, since they usually mean there is a |
| problem with the snapshot-generating process and we won't know about them |
| unless someone tells us. |
| |
| Bugs which are non-obvious, such as failure to compile on only a specific |
| machine, a new machine dependent or obscure bug (particularly one not detected |
| by the testsuite), etc should be reported when you discover them, or have a |
| suggested patch to fix them. |
| |
| |
| FORMAT FOR PATCHES |
| ------------------ |
| |
| If you have a fix for a bug, or an enhancement to submit, send your patch to |
| Ulrich Drepper <drepper@gnu.org>. Here are some simple guidelines for |
| submitting patches: |
| |
| o Use "unified diffs" for patches. A typical command for generating |
| context diffs is "diff -ru glibc-old glibc-patched". |
| |
| o Use the "minimalist approach" for patches. That is, each patch |
| should address only one particular bug, new feature, etc. Do not |
| save up many unrelated changes and submit them all in one big |
| patch, since in general, the larger the patch the more difficult |
| it is for us to decide if the patch is either correct or |
| desirable. And if we find something about the patch that needs |
| to be corrected before it can be installed, we would have to reject |
| the entire patch, which might contain changes which otherwise would |
| be accepted if submitted separately. |
| |
| o Submit a sample ChangeLog entry with your patch. See the existing |
| glibc ChangeLog for examples of what a ChangeLog entry should look |
| like. The emacs command ^X4A will create a ChangeLog entry header |
| for you. |
| |
| |
| BUILDING SNAPSHOTS |
| ------------------ |
| |
| The `best' way to build glibc is to use an extra directory, e.g.: |
| tar xzf libc-970921.tar.gz |
| mkdir build-glibc |
| cd build-glibc |
| ../libc-970921/configure ... |
| |
| In this way you can easily clean up (since `make clean' doesn't work at |
| the moment) and rebuild glibc. |
| |
| |
| NECESSARY TOOLS |
| --------------- |
| |
| For the recommended versions of gcc, binutils, make, texinfo, gettext, |
| autoconf and other tools which might be especially needed when using patches, |
| please read the file INSTALL. |
| |
| |
| HOW CAN YOU HELP |
| ---------------- |
| |
| It helps already a lot if you just install glibc on your system and try to |
| solve any problems. You might want to look at the file `PROJECTS' and help |
| with one of those projects, fix some bugs (see `BUGS' or the bug database), |
| port to an unsupported platform, ... |
| |
| |
| FURTHER DOCUMENTATION |
| --------------------- |
| |
| A lot of questions are answered in the FAQ. The files `INSTALL', `README' and |
| `NOTES' contain the most important documentation. Furthermore glibc has its |
| own 700+ pages info documentation, ... |
| |
| |
| |
| And finally a word of caution: The libc is one of the most fundamental parts |
| of your system - and these snapshots are untested and come without any |
| guarantee or warranty. You might be lucky and everything works or you might |
| crash your system. If you install a glibc snapshot as primary library, you |
| should have a backup somewhere. |
| |
| On many systems it is also a problem to replace the libc while the system is |
| running. In the worst case on broken OSes some systems crash. On better |
| systems you can move the old libc aside but removing it will cause problems |
| since there are still processes using this libc image and so you might have to |
| check the filesystem to get rid of the libc data. One good alternative (which |
| is also safer) is to use a chroot'ed environment. |
| |
| Thanks for your help and support. |
| |
| Thanks to Fred Fish from Cygnus for the original version of this text |
| (for GDB). |
| |
| |
| Ulrich Drepper |