Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / maint.texi
1 @node Maintenance
2 @appendix Library Maintenance
3
4 @menu
5 * How to Install the GNU C Library::    How to configure, compile and install
6                                          the GNU C library.
7 * Reporting Bugs::                      How to report bugs (if you want to
8                                          get them fixed) and other troubles
9                                          you may have with the GNU C library.
10 * Compatibility with Traditional C::    Using the GNU C library with non-ANSI
11                                          C compilers.
12 * Defining New Locales::                How to define and install new named 
13                                          locales.
14 * Contributors to the GNU C Library::   Contributors to the GNU C Library.
15 @end menu
16
17
18 @node How to Install the GNU C Library
19 @appendixsec How to Install the GNU C Library
20 @cindex installing the library
21
22 Installation of the GNU C library is relatively simple.
23
24 You need the latest version of GNU @code{make}.  If you do not have
25 GNU @code{make}, life is more difficult.  We recommend porting GNU
26 @code{make} to your system rather than trying to install the GNU C
27 library without it.  @strong{Really.}@refill
28
29 To configure the GNU C library for your system, run the script
30 @file{configure} with @code{sh}.  You must give as an argument to the
31 script a word describing your system.  If you give no argument, the
32 script gives you a list of systems it knows about.
33
34 The configuration process takes a little while and prints out a slew of
35 messages telling you what it's doing.  These are probably not very
36 interesting to read, but you'll have nothing better to do while waiting
37 for it to finish.
38
39 If the configuration is successful, it will say @samp{Successfully
40 configured}.  If the configuration fails it will say @samp{Failed in
41 configuration}; you must then figure out the source of the problem and
42 either fix it or report it as a bug (@pxref{Reporting Bugs}).@refill
43
44 After successful configuration, simply run @code{make} to make the
45 library and related things.  If all goes well, you will end up with the
46 library archive in the file @file{libc.a}, ANSI C versions of the header
47 files in the @file{ansi/} subdirectory, and traditional C versions of
48 the header files in the @file{trad/} subdirectory.  Install the archive
49 and the header files in appropriate places.
50
51 @strong{Incomplete:} This section needs to give more details on what
52 those ``appropriate places'' are.  What are the default places to
53 install things, so that users need not tell the compiler and linker
54 explicitly where to search for these files?  If you install them
55 someplace else, what options should you tell users to use so that the
56 compiler and linker will find the files?
57
58
59 @node Reporting Bugs
60 @appendixsec Reporting Bugs
61 @cindex reporting bugs
62
63 There are probably bugs in the GNU C library.  If you report them,
64 they will get fixed.  If you don't, no one will ever know about them
65 and they will remain unfixed for all eternity, if not longer.
66
67 To report a bug, first you must find it.  Hopefully, this will be
68 the hard part.  Once you've found a bug, make sure it's really a
69 bug.  A good way to do this is to see if the GNU C library behaves
70 the same way some other C library does.  If so, probably you are
71 wrong and the libraries are right.  If not, one of the libraries is
72 probably wrong.
73
74 Once you're sure you've found a bug, try to narrow it down to the
75 smallest test case that reproduces the problem.  In the case of a C
76 library, you really only need to narrow it down to one library
77 function call, if possible.  This should not be too difficult.
78
79 The final step when you have a simple test case is to report the
80 bug.  When reporting a bug, send your test case, the results you
81 got, the results you expected, what you think the problem might be
82 (if you've thought of anything), your system type, and the version
83 of the GNU C library which you are using.
84
85 If you are not sure how a function should behave, and this manual
86 doesn't tell you, that's a bug in the documentation.  Report that too!
87
88 If you think you have found some way in which the GNU C library does not
89 conform to the ANSI and POSIX standards (@pxref{Standards and
90 Portability}), that is definitely a bug.  Report it!@refill
91
92 Send bug reports to Internet address @samp{bug-gnu-lib?@@prep.ai.mit.edu}
93 or UUCP path @samp{mit-eddie!prep.ai.mit.edu!bug-gnu-lib?}.  If you have
94 other problems with installation, use, or the documentation, please
95 report those as well.
96
97
98 @node Compatibility with Traditional C
99 @appendixsec Compatibility with Traditional C
100
101 Although the GNU C library implements the ANSI C library facilities,
102 you @emph{can} use the GNU C library with traditional, ``pre-ANSI'' C
103 compilers.  However, there are a couple things you need to watch out for.
104
105 You must include a different set of header files when compiling your
106 program using a traditional C compiler than when compiling with an ANSI
107 C compiler.  (This is because traditional C compilers do not understand
108 the function prototypes used in the ANSI C header files.  On the other
109 hand, if you are using an ANSI C compiler like GCC, you should use the
110 ANSI C header files because the prototypes permit the compiler to do a
111 better job of detecting errors in calls to library functions.)  You can
112 tell the C compiler what directories to search for header files by using
113 the @samp{-I} option.
114
115 You also need to be careful because the content and organization of the
116 GNU C library header files differs from that of traditional C
117 implementations.  This means you may need to make changes to your
118 program in order to get it to compile.
119
120 @strong{Incomplete:} Maybe list some specific things to watch out for
121 here, like: some functions from @file{math.h} have been moved to
122 @file{stdlib.h}; confusion between @file{string.h} and @file{strings.h};
123 and the like.  Look at Harbison & Steele's C book to get a more complete
124 list.
125
126 @node Defining New Locales
127 @appendixsec Defining New Locales
128
129 @strong{Incomplete:}  Fill in this section.  Presumably this is where
130 the things in @file{localeinfo.h} will be documented?
131
132
133 @node Contributors to the GNU C Library
134 @appendixsec Contributors to the GNU C Library
135
136 The GNU C library was written almost entirely by Roland McGrath.
137 Some parts of the library were contributed by other people.
138
139 @itemize @bullet
140 @item
141 The @code{getopt} function was written by Richard Stallman
142 and reworked by Roland McGrath.
143
144 @item
145 The random number generation functions @code{random}, @code{srandom},
146 @code{setstate} and @code{initstate}, which are also the basis for the
147 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
148 for the University of California at Berkeley and are copyrighted by the
149 Regents of the University of California.  They have undergone minor
150 changes to fit into the GNU C library and to be ANSI conformant, but the
151 functional code is Berkeley's.@refill
152
153 @item
154 The @code{qsort} function was written by Douglas C. Schmidt.
155
156 @item
157 The memory allocation functions @code{malloc}, @code{realloc} and
158 @code{free} and related code were written by Michael J. Haertel.
159 @end itemize