summary refs log tree commit diff
path: root/README-alpha
blob: d13b9f7191d9589bb2fb9e6243a46f9b5830cbe2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
			 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 prep.ai.mit.edu 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@gnu.org mailing list by sending an email to
libc-alpha-request@gnu.org.  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@gnu.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@prep.ai.mit.edu.  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