89628b16dc8f59bc9294d6c6b572fa98d146a5c1
[kopensolaris-gnu/glibc.git] / manual / maint.texi
1 @c \input /gd/gnu/doc/texinfo
2 @c This is for making the `INSTALL' file for the distribution.
3 @c Makeinfo ignores it when processing the file from the include.
4 @setfilename INSTALL
5
6 @node Maintenance, Copying, Summary of Library Facilities, Top
7 @appendix Library Maintenance
8
9 @menu
10 * Installation::          How to configure, compile and
11                              install the GNU C library.
12 * Reporting Bugs::        How to report bugs (if you want to
13                              get them fixed) and other troubles
14                              you may have with the GNU C library.
15 * Porting::               How to port the GNU C library to
16                              a new machine or operating system.
17 @c * Traditional C::         Using the GNU C library with
18 @c                              non-ANSI C compilers.
19 * Contributors::          Contributors to the GNU C Library.
20 @end menu
21
22 @node Installation
23 @appendixsec How to Install the GNU C Library
24 @cindex installing the library
25
26 Installation of the GNU C library is relatively simple.
27
28 You need the latest version of GNU @code{make}.  Modifying the GNU C
29 Library to work with other Make programs would be so hard that we
30 recommend you port GNU Make instead.  @strong{Really.}@refill
31
32 To configure the GNU C library for your system, run the shell script
33 @file{configure} with @code{sh}.  Use an argument which is the
34 conventional GNU name for your system configuration---for example,
35 @samp{sparc-sun-sunos4.1}, for a Sun 4 running Sunos 4.1.
36 @xref{Installation, Installation, Installing GNU CC, gcc.info, Using and
37 Porting GNU CC}, for a full description of standard GNU configuration
38 names.
39
40 The GNU C Library currently supports configurations that match the
41 following patterns:
42
43 @example
44 sparc-sun-sunos4.@var{n}
45 m68k-hp-bsd4.3
46 m68k-sun-sunos4.@var{n}
47 m68k-sony-bsd4.3
48 mips-dec-ultrix4.2
49 @end example
50
51 While no other configurations are supported, there are handy aliases for
52 these few.  (These aliases work in other GNU software as well.)
53
54 @example
55 sun4-sunos4.@var{n}
56 hp320-bsd4.3
57 sun3-sunos4.@var{n}
58 news
59 decstation-ultrix
60 @end example
61
62 Here are some options that you should specify (if appropriate) when
63 you run @code{configure}:
64
65 @table @samp
66 @item --with-gnu-ld
67 Use this option if you plan to use GNU ld to link programs with the GNU
68 C Library.  (we strongly recommend that you do.)
69
70 @item --nfp
71 Use this option if your computer lacks hardware floating point support.
72 @end table
73
74 The simplest way to run @code{configure} is to do it in the directory
75 that contains the library sources.  This prepares to build the library
76 in that very directory.
77
78 You can prepare to build the library in some other directory by going
79 to that other directory to run @code{configure}.  In order to run
80 configure, you will have to specify a directory for it, like this:
81
82 @example
83 mkdir ../hp320
84 cd ../hp320
85 ../src/configure hp320-bsd4.3
86 @end example
87
88 @noindent
89 @code{configure} looks for the sources in whatever directory you
90 specified for finding @code{configure} itself.  It does not matter where
91 in the file system the source and build directories are---as long as you
92 specify the source directory when you run @code{configure}, you will get
93 the proper results.
94
95 This feature let you keep sources and binaries in different
96 directories, and that makes it easy to build the library for several
97 different machines from the same set of sources.  Simply create a 
98 build directory for each target machine, and run @code{configure} in
99 that directory specifying the target machine's configuration name.
100
101 The library has a number of special-purpose configuration parameters.
102 These are defined in the file @file{Makeconfig}; see the comments in
103 that file for the details.
104
105 But don't edit the file @file{Makeconfig} yourself---instead, create a
106 file @file{configparms} in the directory where you are building the
107 library, and define in that file the parameters you want to specify.
108 @file{configparms} should @emph{not} be an edited copy of
109 @file{Makeconfig}; specify only the parameters that you want to
110 override.
111
112 Some of the machine-dependent code for some machines uses extensions in
113 the GNU C compiler, so you may need to compile the library with GCC.
114 (In fact, all of the existing complete ports require GCC.)
115
116 To build the library and header files, type @code{make}.  This will
117 produce a lot of output, some of which looks like errors from
118 @code{make} (but isn't).  Look for error messages from @code{make}
119 containing @samp{***}.  Those indicate that something is really wrong.
120 Using the @samp{-w} option to @code{make} may make the output easier to
121 understand (this option tells @code{make} to print messages telling you
122 what subdirectories it is working on).@refill
123
124 To install the library and header files, type @code{make install}, after
125 setting the installation directories in @file{configparms}.  This will
126 build things if necessary, before installing them.@refill
127
128 @node Reporting Bugs
129 @appendixsec Reporting Bugs
130 @cindex reporting bugs
131
132 There are probably bugs in the GNU C library.  If you report them,
133 they will get fixed.  If you don't, no one will ever know about them
134 and they will remain unfixed for all eternity, if not longer.
135
136 To report a bug, first you must find it.  Hopefully, this will be the
137 hard part.  Once you've found a bug, make sure it's really a bug.  A
138 good way to do this is to see if the GNU C library behaves the same way
139 some other C library does.  If so, probably you are wrong and the
140 libraries are right (but not necessarily).  If not, one of the libraries
141 is probably wrong.
142
143 Once you're sure you've found a bug, try to narrow it down to the
144 smallest test case that reproduces the problem.  In the case of a C
145 library, you really only need to narrow it down to one library
146 function call, if possible.  This should not be too difficult.
147
148 The final step when you have a simple test case is to report the
149 bug.  When reporting a bug, send your test case, the results you
150 got, the results you expected, what you think the problem might be
151 (if you've thought of anything), your system type, and the version
152 of the GNU C library which you are using.
153
154 If you are not sure how a function should behave, and this manual
155 doesn't tell you, that's a bug in the manual.  Report that too!
156 If the function's behavior disagrees with the manual, then either the
157 library or the manual has a bug, so report the disagreement.
158
159 If you think you have found some way in which the GNU C library does not
160 conform to the ANSI and POSIX standards (@pxref{Standards and
161 Portability}), that is definitely a bug.  Report it!@refill
162
163 Send bug reports to Internet address @samp{bug-gnu-libc@@prep.ai.mit.edu}
164 or UUCP path @samp{mit-eddie!prep.ai.mit.edu!bug-gnu-libc}.  If you have
165 other problems with installation, use, or the documentation, please
166 report those as well.
167
168 @node Porting
169 @appendixsec Porting the GNU C Library
170
171 The GNU C library is written to be easily portable to a variety of
172 machines and operating systems.  Machine- and operating system-dependent
173 functions are well separated to make it easy to add implementations for
174 new machines or operating systems.  This section describes the layout of
175 the library source tree and explains the mechanisms used to select
176 machine-dependent code to use.
177
178 The process of building the library is driven by the makefiles, which
179 make heavy use of special features of GNU Make.  The makefiles are very
180 complex, and you probably don't want to try to understand them.  But
181 what they do is fairly straightforward, and only requires that you
182 define a few variables in the right places.
183
184 The library sources are divided into subdirectories, grouped by topic.
185 The @file{string} subdirectory has all the string-manipulation
186 functions, @file{stdio} has all the standard I/O functions, etc.
187
188 Each subdirectory contains a simple makefile, called @file{Makefile},
189 which defines a few Make variables and then includes the global
190 makefile @file{Rules} with a line like:
191
192 @example
193 include ../Rules
194 @end example
195
196 @noindent
197 The basic variables that a subdirectory makefile defines are:
198
199 @table @code
200 @item subdir
201 The name of the subdirectory, for example @file{stdio}.
202 This variable @emph{must} be defined.
203
204 @item headers
205 The names of the header files in this section of the library,
206 such as @file{stdio.h}.
207
208 @item routines
209 @itemx aux
210 The names of the modules (source files) in this section of the library.
211 These should be simple names, such as @samp{strlen} (rather than
212 complete file names, such as @file{strlen.c}).  Use @code{routines} for
213 modules that define functions in the library, and @code{aux} for
214 auxiliary modules containing things like data definitions.  But the
215 values of @code{routines} and @code{aux} are concatenated, so there
216 really is no practical difference.@refill
217
218 @item tests
219 The names of test programs for this section of the library.  These
220 should be simple names, such as @samp{tester} (rather than complete file
221 names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
222 run all the test programs.  If a test program needs input, put the test
223 data in a file called @file{@var{test-program}.input}; it will given to
224 the test program on its standard input.  If a test program wants to be
225 run with arguments, put the arguments (all on a single line) in a file
226 called @file{@var{test-program}.args}.@refill
227
228 @item others
229 The names of ``other'' in programs associated with this section of the
230 library.  These are programs which are not tests per se, but are other
231 small programs included with the library.  These are built by @samp{make
232 others}.@refill
233
234 @item install-lib
235 @itemx install-data
236 @itemx install
237 Files to be installed by @w{@samp{make install}}.  Things listed in
238 @samp{install-lib} are installed in the directory specified by
239 @samp{libdir} in @file{Makeconfig} (@pxref{Installation}).  Files listed
240 in @code{install-data} are installed in the directory specified by
241 @samp{datadir} in @file{configparms} or @file{Makeconfig}.  Files listed
242 in @code{install} are installed in the directory specified by
243 @samp{bindir} in @file{Makeconfig}.@refill
244
245 @item distribute
246 Other files from this subdirectory which should be put into a
247 distribution tar file.  The source and header files listed in the other
248 standard variables, and the makefile itself, need not be listed here.
249 Only define @code{distribute} if there are files used in an unusual way
250 that should go into the distribution.
251 @end table
252
253 All the machine-dependent and operating system-dependent files in the
254 library are in the subdirectory @file{sysdeps} under the top-level
255 library source directory.  This directory contains a hierarchy of
256 subdirectories (@pxref{Hierarchy Conventions}).
257
258 Each subdirectory of @file{sysdeps} contains source files for a
259 particular machine or operating system, or for a class of machine or
260 operating system (for example, systems by a particular vendor, or all
261 machines that use IEEE floating-point format).  A configuration
262 specifies an ordered list of these subdirectories.  Each subdirectory
263 implicitly appends its parent directory to the list.  For example,
264 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
265 list @file{unix/bsd/vax unix/bsd unix}.  A subdirectory can also specify
266 that it implies other subdirectories which are not directly above it in
267 the directory hierarchy.  If the file @file{Implies} exists in a
268 subdirectory, it lists other subdirectories of @file{sysdeps} which are
269 appended to the list, appearing after the subdirectory containing the
270 @file{Implies} file.  Lines in an @file{Implies} file that begin with a
271 @samp{#} character are ignored as comments.  For example,
272 @file{unix/bsd/Implies} contains:@refill
273
274 @example
275 # BSD has Internet-related things.
276 inet
277 @end example
278
279 @noindent
280 and @file{unix/Implies} contains:
281
282 @example
283 posix
284 @end example
285
286 @noindent
287 So the final list is @file{unix/bsd/vax unix/bsd vax unix/inet unix posix}.
288
289 A GNU configuration name has three parts: the CPU type, the
290 manufacturer's name, and the operating system.  @file{configure} uses
291 these to pick the list of system-dependent directories to look for.  If
292 the @samp{-nfp} option is not passed to @file{configure}, the directory
293 @file{@var{machine}/fpu} is used.  The operating system usually has a
294 @dfn{base operating system}; this is used like an additional parameter,
295 and is the most significant one.  For example, if the operating system
296 is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.  The
297 algorithm is simple; read @file{configure} to see the details.
298
299 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
300 and @file{stub}.  These two are always implicitly appended to the list
301 of subdirectories (in that order), so you needn't put them in an
302 @file{Implies} file, and you should not create any subdirectories under
303 them.  @file{generic} is for things that can be implemented in
304 machine-independent C, using only other machine-independent functions in
305 the C library.  @file{stub} is for @dfn{stub} versions of functions
306 which cannot be implemented on a particular machine or operating system.
307 The stub functions always return an error, and set @code{errno} to
308 @code{ENOSYS} (Function not implemented).  @xref{Error Reporting}.
309
310 A source file is known to be system-dependent by its having a version in
311 @file{generic} or @file{stub}; every system-dependent function should
312 have either a generic or stub implementation (there is no point in
313 having both).
314
315 If you come across a file that is in one of the main source directories
316 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
317 operating system-dependent version of it, move the file into
318 @file{sysdeps/generic} and write your new implementation in the
319 appropriate system-specific subdirectory.  Note that if a file is to be
320 system-dependent, it @emph{must not} appear in one of the main source
321 directories.@refill
322
323 There are a few special files that may exist in each subdirectory of
324 @file{sysdeps}:
325
326 @table @file
327 @item Makefile
328 A makefile for this machine or operating system, or class of machine or
329 operating system.  This file is included by the library makefile
330 @file{Makerules}, which is used by the top-level makefile and the
331 subdirectory makefiles.  It can change the variables set in the
332 including makefile or add new rules.  It can use GNU Make conditional
333 commands based on the variable @samp{subdir} (see above) to select
334 different sets of variables and rules for different sections of the
335 library.  It can also set the Make variable @samp{sysdep-routines}, to
336 specify extra modules to be included in the library.  You should use
337 @samp{sysdep-routines} rather than adding modules to @samp{routines}
338 because the latter is used in determining what to distribute for each
339 subdirectory of the main source tree.@refill
340
341 Each makefile in a subdirectory in the ordered list of subdirectories to
342 be searched is included in order.  Since several system-dependent
343 makefiles may be included, each should append to @samp{sysdep-routines}
344 rather than simply setting it:
345
346 @example
347 sysdep-routines := $(sysdep-routines) foo bar
348 @end example
349
350 @item Subdirs
351 This file contains the names of new whole subdirectories under the
352 top-level library source tree that should be included for this system.
353 These subdirectories are treated just like the system-independent
354 subdirectories in the library source tree, such as @file{stdio} and
355 @file{math}.
356
357 Use this when there are whole new sets of routines and header files that
358 should go into the library for the system this subdirectory of
359 @file{sysdeps} implements.  For example,
360 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
361 directory contains various network-oriented operations which only make
362 sense to put in the library on systems that support the Internet.@refill
363
364 @item Dist
365 This file contains the names of files (relative the the subdirectory of
366 @file{sysdeps} in which it appears) which should be included in the
367 distribution.  List any new files used by rules in the @file{Makefile}
368 in the same directory, or header files used by the source files in that
369 directory.  You don't need to list files that are implementations
370 (either C or assembly source) of routines whose names are given in the
371 machine-independent makefiles in the main source tree.
372 @end table
373
374 That is the general system for how system-dependencies are isolated.
375 The rest of this section describes details of particular implementations
376 for classes of systems, and how existing classes and systems are
377 organized.
378
379 @menu
380 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
381 * Porting to Unix::             Porting the library to an average
382                                    Unix-like system.
383 @end menu
384
385 @node Hierarchy Conventions
386 @appendixsubsec The Layout of the @file{sysdeps} Directory Hierarchy
387
388 Different machine architectures are generally at the top level of the
389 @file{sysdeps} directory tree.  For example, @file{sysdeps/sparc} and
390 @file{sysdeps/m68k}.  These contain files specific to those machine
391 architectures (perhaps with subdirectories for specialization of those
392 architectures, such as @file{sysdeps/m68k/68881}), but not specific to
393 any particular operating system.
394
395 Files specific to a particular operating system on a particular machine
396 should be in a subdirectory in the section of the hierarchy for the
397 operating system, usually with an @file{Implies} file referring to the
398 top-level subdirectory under @file{sysdeps} for the particular machine.
399 For example, @file{unix/bsd/hp9k3bsd} implies @file{m68k}.@refill
400
401 There are a few directories at the top level of the @file{sysdeps}
402 hierarchy that are not for particular machine architectures.
403
404 @table @file
405 @item generic
406 @itemx stub
407 As described above (@pxref{Porting}), these are the two subdirectories
408 that every configuration uses, usually last.
409
410 @item ieee754
411 This directory is for code using the IEEE 754 floating-point format,
412 where the C type @code{float} is IEEE 754 single-precision format, and
413 @code{double} is IEEE 754 double-precision format.  Usually this is
414 directory is referred to in the @file{Implies} file in a machine
415 architecture-specific directory, such as @file{m68k/Implies}.
416
417 @item posix
418 This directory contains implementations of things in the library in
419 terms of POSIX.1 functions.  This includes some of the POSIX.1 functions
420 themselves.  Of course, POSIX.1 cannot be completely implemented in
421 terms of itself, so a configuration using just @file{posix} cannot be
422 complete.
423
424 @item unix
425 This is the directory for Unix-like things.  See @xref{Porting to Unix}.
426 @file{unix} implies @file{posix}.
427
428 @item mach
429 This is the directory for things based on the Mach microkernel from CMU
430 (including the GNU operating system).  Other basic operating systems
431 (VMS, for example) would have their own directories at the top level of
432 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
433 @end table
434
435 @node Porting to Unix
436 @appendixsubsec Porting the GNU C Library to Unix Systems
437
438 Most Unix systems are fundamentally very similar.  There are variations
439 between different machines, and variations in what facilities are
440 provided by the kernel.  But the interface to the operating system
441 facilities is, for the most part, pretty uniform and simple.
442
443 The code for Unix systems is in the directory @file{unix}, at the top
444 level of the @file{sysdeps} hierarchy.  This directory contains
445 subdirectories (and subdirectory trees) for various Unix variants.
446
447 The routines which are system calls in most Unix systems are implemented
448 in assembly code in files in @file{sysdeps/unix}.  These files are named
449 with a suffix of @samp{.S}; for example, @file{__open.S}.  Files ending
450 in @samp{.S} are run through the C preprocessor before being fed to the
451 assembler.
452
453 These files all use a set of macros that should be defined in
454 @file{sysdep.h}.  The file @file{sysdep.h} in @file{sysdeps/unix}
455 partially defines them; a file @file{sysdep.h} in another directory must
456 finish defining them for the particular machine and operating system
457 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
458 @file{sysdep.h} implementations to see what these macros are and what
459 they should do.@refill
460
461 The system-specific makefile for the @file{unix} directory,
462 @file{sysdeps/unix/Makefile}, gives rules to generate several files from
463 the Unix system you are building the library on (which is assumed to be
464 the target system you are building the library @emph{for}).  All the
465 generated files are put in the directory where the object files are
466 kept; they should not affect the source tree itself.  The files
467 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
468 @file{errlist.c} (for the @file{stdio} section of the library).
469
470 @ignore
471 @c This section might be a good idea if it is finished,
472 @c but there's no point including it as it stands. --rms
473 @node Traditional C
474 @appendixsec Compatibility with Traditional C
475
476 @c ??? This section is really short now.  Want to keep it? --roland
477
478 Although the GNU C library implements the ANSI C library facilities, you
479 @emph{can} use the GNU C library with traditional, ``pre-ANSI'' C
480 compilers.  However, you need to be careful because the content and
481 organization of the GNU C library header files differs from that of
482 traditional C implementations.  This means you may need to make changes
483 to your program in order to get it to compile.
484 @end ignore
485
486 @node Contributors,  , Traditional C Compatibility, Maintenance
487 @appendixsec Contributors to the GNU C Library
488
489 The GNU C library was written almost entirely by Roland McGrath.
490 Some parts of the library were contributed by other people.
491
492 @itemize @bullet
493 @item
494 The @code{getopt} and related functions were written by
495 Richard Stallman, David J. MacKenzie, and Roland McGrath.
496
497 @item
498 The random number generation functions @code{random}, @code{srandom},
499 @code{setstate} and @code{initstate}, which are also the basis for the
500 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
501 for the University of California at Berkeley and are copyrighted by the
502 Regents of the University of California.  They have undergone minor
503 changes to fit into the GNU C library and to fit the ANSI C standard,
504 but the functional code is Berkeley's.@refill
505
506 @item
507 Most of the math functions are taken from 4.4 BSD, and are
508 copyrighted by the Regents of the University of California.
509 They have been modified only slightly to work with the GNU C library.
510
511 @item
512 The merge sort function @code{qsort} was written by Michael J. Haertel.
513
514 @item
515 The quick sort function used as a fallback by @code{qsort} was written
516 by Douglas C. Schmidt.
517
518 @item
519 The memory allocation functions @code{malloc}, @code{realloc} and
520 @code{free} and related code were written by Michael J. Haertel.
521
522 @item
523 Fast implementations of many of the string functions (@code{memcpy},
524 @code{strlen}, etc.) were written by
525 @tex
526 Torbj\"orn
527 @end tex
528 @ifinfo
529 Torbjorn
530 @end ifinfo
531 Granlund.@refill
532
533 @item
534 Some of the support code for Mach is taken from Mach 3.0, from CMU,
535 and is under the following copyright terms:
536
537 @display
538 Mach Operating System
539 Copyright (c) 1991,1990,1989 Carnegie Mellon University
540 All Rights Reserved.
541
542 Permission to use, copy, modify and distribute this software and its
543 documentation is hereby granted, provided that both the copyright
544 notice and this permission notice appear in all copies of the
545 software, derivative works or modified versions, and any portions
546 thereof, and that both notices appear in supporting documentation.
547
548 CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
549 CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
550 ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
551
552 Carnegie Mellon requests users of this software to return to
553
554  Software Distribution Coordinator  or  Software.Distribution@@CS.CMU.EDU
555  School of Computer Science
556  Carnegie Mellon University
557  Pittsburgh PA 15213-3890
558
559 any improvements or extensions that they make and grant Carnegie Mellon
560 the rights to redistribute these changes.
561 @end display
562
563 @item
564 The @file{tar.h} header file was written by David J. MacKenzie.
565
566 @item
567 The port to the MIPS DECStation was contributed by Brendan Kehoe and Ian
568 Lance Taylor.
569
570 @item
571 The DES encryption function @code{crypt} and related code was donated by
572 Michael Glad.
573 @end itemize
574
575 @c @bye