]>
Commit | Line | Data |
---|---|---|
af6f3906 UD |
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 | ||
dd7d45e8 | 102 | The files will be available via anonymous ftp from alpha.gnu.org, in |
af6f3906 UD |
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 | ||
dd7d45e8 | 113 | Please note that the snapshots on alpha.gnu.org and on |
af6f3906 | 114 | linux.kernel.org are not always in sync. Patches to some files might |
dd7d45e8 | 115 | appear a day a diff earlier or later on alpha than on kernel. |
af6f3906 UD |
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 | |
2eb45444 | 123 | from ftp.gnu.org in directory pub/gnu. |
af6f3906 UD |
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 | ||
71377958 UD |
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. | |
af6f3906 UD |
170 | |
171 | Do *not* send any questions about the snapshots or patches specific to the | |
2eb45444 | 172 | snapshots to bug-glibc@gnu.org. Nobody there will have any idea what |
af6f3906 UD |
173 | you are talking about and it will just cause confusion. |
174 | ||
175 | ||
176 | BUG REPORTS | |
177 | ----------- | |
178 | ||
dd7d45e8 | 179 | Send bug reports directly to Ulrich Drepper <drepper@gnu.org>. Please |
af6f3906 UD |
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 | |
dd7d45e8 | 207 | Ulrich Drepper <drepper@gnu.org>. Here are some simple guidelines for |
af6f3906 UD |
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 |