Changed bug reporting address from bug-gnu-utils to bug-glibc, to be
authorroland <roland>
Mon, 27 Jul 1992 23:54:30 +0000 (23:54 +0000)
committerroland <roland>
Mon, 27 Jul 1992 23:54:30 +0000 (23:54 +0000)
consistent with README.

Moved Source Layout out of Porting.

Moved description of configure's directory choices to Hierarchy
Conventions; updated that node lots.

Credit BSD for inet code.  Include BSD copyright terms.
Use @quotation for CMU terms.

manual/maint.texi

index e6bef94..8900321 100644 (file)
@@ -12,6 +12,8 @@
 * Reporting Bugs::        How to report bugs (if you want to
                              get them fixed) and other troubles
                              you may have with the GNU C library.
+* Source Layout::         How to add new functions or header files
+                             to the GNU C library.
 * Porting::               How to port the GNU C library to
                              a new machine or operating system.
 @c * Traditional C::         Using the GNU C library with
@@ -26,8 +28,8 @@
 Installation of the GNU C library is relatively simple.
 
 You need the latest version of GNU @code{make}.  Modifying the GNU C
-Library to work with other Make programs would be so hard that we
-recommend you port GNU Make instead.  @strong{Really.}@refill
+Library to work with other @code{make} programs would be so hard that we
+recommend you port GNU @code{make} instead.  @strong{Really.}@refill
 
 To configure the GNU C library for your system, run the shell script
 @file{configure} with @code{sh}.  Use an argument which is the
@@ -76,16 +78,19 @@ Use this option if you plan to use the GNU assembler, @code{gas}, when
 building the GNU C Library.  On some systems, the library may not build
 properly if you do @emph{not} use @code{gas}.
 
+@c extra blank line makes it look better
 @item --nfp
+
 Use this option if your computer lacks hardware floating point support.
 
 @item --prefix=@var{directory}
-Install machine-independent data files in @file{@var{directory}/lib}.
-(You can also set this in @file{configparms}; see below.)
+Install machine-independent data files in subdirectories of
+@file{@var{directory}}.  (You can also set this in @file{configparms};
+see below.)
 
 @item --exec_prefix=@var{directory}
-Install the library and other machine-dependent files in
-@file{@var{directory}/lib}.  (You can also set this in
+Install the library and other machine-dependent files in subdirectories
+of @file{@var{directory}}.  (You can also set this in
 @file{configparms}; see below.)
 @end table
 
@@ -110,7 +115,7 @@ in the file system the source and build directories are---as long as you
 specify the source directory when you run @code{configure}, you will get
 the proper results.
 
-This feature let you keep sources and binaries in different
+This feature lets you keep sources and binaries in different
 directories, and that makes it easy to build the library for several
 different machines from the same set of sources.  Simply create a 
 build directory for each target machine, and run @code{configure} in
@@ -123,7 +128,7 @@ that file for the details.
 But don't edit the file @file{Makeconfig} yourself---instead, create a
 file @file{configparms} in the directory where you are building the
 library, and define in that file the parameters you want to specify.
-@file{configparms} should @emph{not} be an edited copy of
+@file{configparms} should @strong{not} be an edited copy of
 @file{Makeconfig}; specify only the parameters that you want to
 override.
 
@@ -169,34 +174,30 @@ got, the results you expected, what you think the problem might be
 (if you've thought of anything), your system type, and the version
 of the GNU C library which you are using.
 
+@ignore @c this makes no sense for `INSTALL' before the manual is out. --rm
 If you are not sure how a function should behave, and this manual
 doesn't tell you, that's a bug in the manual.  Report that too!
 If the function's behavior disagrees with the manual, then either the
 library or the manual has a bug, so report the disagreement.
+@end ignore
 
 If you think you have found some way in which the GNU C library does not
 conform to the ANSI and POSIX standards (@pxref{Standards and
 Portability}), that is definitely a bug.  Report it!@refill
 
-Send bug reports to Internet address @samp{bug-gnu-libc@@prep.ai.mit.edu}
-or UUCP path @samp{mit-eddie!prep.ai.mit.edu!bug-gnu-libc}.  If you have
-other problems with installation, use, or the documentation, please
-report those as well.
+Send bug reports to the Internet address
+@samp{bug-glibc@@prep.ai.mit.edu} or the UUCP path
+@samp{mit-eddie!prep.ai.mit.edu!bug-glibc}.  If you have other problems
+with installation, use, or the documentation, please report those as
+well.@refill
 
-@node Porting
-@appendixsec Porting the GNU C Library
-
-The GNU C library is written to be easily portable to a variety of
-machines and operating systems.  Machine- and operating system-dependent
-functions are well separated to make it easy to add implementations for
-new machines or operating systems.  This section describes the layout of
-the library source tree and explains the mechanisms used to select
-machine-dependent code to use.
+@node Source Layout
+@appendixsec Adding New Functions
 
 The process of building the library is driven by the makefiles, which
-make heavy use of special features of GNU Make.  The makefiles are very
-complex, and you probably don't want to try to understand them.  But
-what they do is fairly straightforward, and only requires that you
+make heavy use of special features of GNU @code{make}.  The makefiles
+are very complex, and you probably don't want to try to understand them.
+But what they do is fairly straightforward, and only requires that you
 define a few variables in the right places.
 
 The library sources are divided into subdirectories, grouped by topic.
@@ -204,7 +205,7 @@ The @file{string} subdirectory has all the string-manipulation
 functions, @file{stdio} has all the standard I/O functions, etc.
 
 Each subdirectory contains a simple makefile, called @file{Makefile},
-which defines a few Make variables and then includes the global
+which defines a few @code{make} variables and then includes the global
 makefile @file{Rules} with a line like:
 
 @example
@@ -217,7 +218,7 @@ The basic variables that a subdirectory makefile defines are:
 @table @code
 @item subdir
 The name of the subdirectory, for example @file{stdio}.
-This variable @emph{must} be defined.
+This variable @strong{must} be defined.
 
 @item headers
 The names of the header files in this section of the library,
@@ -230,7 +231,7 @@ These should be simple names, such as @samp{strlen} (rather than
 complete file names, such as @file{strlen.c}).  Use @code{routines} for
 modules that define functions in the library, and @code{aux} for
 auxiliary modules containing things like data definitions.  But the
-values of @code{routines} and @code{aux} are concatenated, so there
+values of @code{routines} and @code{aux} are just concatenated, so there
 really is no practical difference.@refill
 
 @item tests
@@ -238,16 +239,16 @@ The names of test programs for this section of the library.  These
 should be simple names, such as @samp{tester} (rather than complete file
 names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
 run all the test programs.  If a test program needs input, put the test
-data in a file called @file{@var{test-program}.input}; it will given to
+data in a file called @file{@var{test-program}.input}; it will be given to
 the test program on its standard input.  If a test program wants to be
 run with arguments, put the arguments (all on a single line) in a file
 called @file{@var{test-program}.args}.@refill
 
 @item others
-The names of ``other'' in programs associated with this section of the
+The names of ``other'' programs associated with this section of the
 library.  These are programs which are not tests per se, but are other
-small programs included with the library.  These are built by @samp{make
-others}.@refill
+small programs included with the library.  They are built by
+@w{@samp{make others}}.@refill
 
 @item install-lib
 @itemx install-data
@@ -262,12 +263,22 @@ in @code{install} are installed in the directory specified by
 
 @item distribute
 Other files from this subdirectory which should be put into a
-distribution tar file.  The source and header files listed in the other
-standard variables, and the makefile itself, need not be listed here.
+distribution tar file.  You need not list here the makefile itself or
+the source and header files listed in the other standard variables.
 Only define @code{distribute} if there are files used in an unusual way
 that should go into the distribution.
 @end table
 
+@node Porting
+@appendixsec Porting the GNU C Library
+
+The GNU C library is written to be easily portable to a variety of
+machines and operating systems.  Machine- and operating system-dependent
+functions are well separated to make it easy to add implementations for
+new machines or operating systems.  This section describes the layout of
+the library source tree and explains the mechanisms used to select
+machine-dependent code to use.
+
 All the machine-dependent and operating system-dependent files in the
 library are in the subdirectory @file{sysdeps} under the top-level
 library source directory.  This directory contains a hierarchy of
@@ -276,7 +287,7 @@ subdirectories (@pxref{Hierarchy Conventions}).
 Each subdirectory of @file{sysdeps} contains source files for a
 particular machine or operating system, or for a class of machine or
 operating system (for example, systems by a particular vendor, or all
-machines that use IEEE floating-point format).  A configuration
+machines that use IEEE 754 floating-point format).  A configuration
 specifies an ordered list of these subdirectories.  Each subdirectory
 implicitly appends its parent directory to the list.  For example,
 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
@@ -288,15 +299,12 @@ appended to the list, appearing after the subdirectory containing the
 @file{Implies} file.  Lines in an @file{Implies} file that begin with a
 @samp{#} character are ignored as comments.  For example,
 @file{unix/bsd/Implies} contains:@refill
-
 @example
 # BSD has Internet-related things.
-inet
+unix/inet
 @end example
-
 @noindent
 and @file{unix/Implies} contains:
-
 @example
 posix
 @end example
@@ -304,16 +312,6 @@ posix
 @noindent
 So the final list is @file{unix/bsd/vax unix/bsd vax unix/inet unix posix}.
 
-A GNU configuration name has three parts: the CPU type, the
-manufacturer's name, and the operating system.  @file{configure} uses
-these to pick the list of system-dependent directories to look for.  If
-the @samp{-nfp} option is not passed to @file{configure}, the directory
-@file{@var{machine}/fpu} is used.  The operating system usually has a
-@dfn{base operating system}; this is used like an additional parameter,
-and is the most significant one.  For example, if the operating system
-is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.  The
-algorithm is simple; read @file{configure} to see the details.
-
 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
 and @file{stub}.  These two are always implicitly appended to the list
 of subdirectories (in that order), so you needn't put them in an
@@ -335,7 +333,7 @@ If you come across a file that is in one of the main source directories
 operating system-dependent version of it, move the file into
 @file{sysdeps/generic} and write your new implementation in the
 appropriate system-specific subdirectory.  Note that if a file is to be
-system-dependent, it @emph{must not} appear in one of the main source
+system-dependent, it @strong{must not} appear in one of the main source
 directories.@refill
 
 There are a few special files that may exist in each subdirectory of
@@ -347,14 +345,14 @@ A makefile for this machine or operating system, or class of machine or
 operating system.  This file is included by the library makefile
 @file{Makerules}, which is used by the top-level makefile and the
 subdirectory makefiles.  It can change the variables set in the
-including makefile or add new rules.  It can use GNU Make conditional
-commands based on the variable @samp{subdir} (see above) to select
-different sets of variables and rules for different sections of the
-library.  It can also set the Make variable @samp{sysdep-routines}, to
-specify extra modules to be included in the library.  You should use
-@samp{sysdep-routines} rather than adding modules to @samp{routines}
-because the latter is used in determining what to distribute for each
-subdirectory of the main source tree.@refill
+including makefile or add new rules.  It can use GNU @code{make}
+conditional directives based on the variable @samp{subdir} (see above) to
+select different sets of variables and rules for different sections of
+the library.  It can also set the @code{make} variable
+@samp{sysdep-routines}, to specify extra modules to be included in the
+library.  You should use @samp{sysdep-routines} rather than adding
+modules to @samp{routines} because the latter is used in determining
+what to distribute for each subdirectory of the main source tree.@refill
 
 Each makefile in a subdirectory in the ordered list of subdirectories to
 be searched is included in order.  Since several system-dependent
@@ -390,9 +388,11 @@ machine-independent makefiles in the main source tree.
 @end table
 
 That is the general system for how system-dependencies are isolated.
-The rest of this section describes details of particular implementations
-for classes of systems, and how existing classes and systems are
-organized.
+@iftex
+The next section explains how to decide what directories in
+@file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
+the library to Unix variants.
+@end iftex
 
 @menu
 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
@@ -403,18 +403,67 @@ organized.
 @node Hierarchy Conventions
 @appendixsubsec The Layout of the @file{sysdeps} Directory Hierarchy
 
+A GNU configuration name has three parts: the CPU type, the
+manufacturer's name, and the operating system.  @file{configure} uses
+these to pick the list of system-dependent directories to look for.  If
+the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
+directory @file{@var{machine}/fpu} is also used.  The operating system
+often has a @dfn{base operating system}; for example, if the operating
+system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
+The algorithm used to pick the list of directories is simple:
+@file{configure} makes a list of the base operating system,
+manufacturer, CPU type, and operating system, in that order.  It then
+concatenates all these together with slashes in between, to produce a
+directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
+results in @file{unix/bsd/sun/sparc/sunos4.1}.  @file{configure} then
+tries removing each element of the list in turn, so
+@file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
+Since the precise version number of the operating system is often not
+important, and it would be very inconvenient, for example, to have
+identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
+@file{configure} tries successively less specific operating system names
+by removing trailing suffixes starting with a period.
+
+Here is the complete list of directories that would be tried for the
+configuration @samp{sparc-sun-sunos4.1}:
+
+@example
+@group
+sparc/fpu
+unix/bsd/sun/sunos4.1/sparc
+unix/bsd/sun/sunos4.1
+unix/bsd/sun/sunos4/sparc
+unix/bsd/sun/sunos4
+unix/bsd/sun/sparc
+unix/bsd/sun
+unix/bsd/sunos4.1/sparc
+unix/bsd/sunos4.1
+unix/bsd/sunos4/sparc
+unix/bsd/sunos4
+unix/bsd/sparc
+unix/bsd
+sun/sunos4.1/sparc
+sun/sunos4.1
+sun/sunos4/sparc
+sun/sunos4
+sun/sparc
+sun
+sunos4.1/sparc
+sunos4.1
+sunos4/sparc
+sunos4
+sparc
+@end group
+@end example
+
 Different machine architectures are generally at the top level of the
-@file{sysdeps} directory tree.  For example, @file{sysdeps/sparc} and
-@file{sysdeps/m68k}.  These contain files specific to those machine
-architectures (perhaps with subdirectories for specialization of those
-architectures, such as @file{sysdeps/m68k/68881}), but not specific to
-any particular operating system.
-
-Files specific to a particular operating system on a particular machine
-should be in a subdirectory in the section of the hierarchy for the
-operating system, usually with an @file{Implies} file referring to the
-top-level subdirectory under @file{sysdeps} for the particular machine.
-For example, @file{unix/bsd/hp9k3bsd} implies @file{m68k}.@refill
+@file{sysdeps} directory tree.  For example, @w{@file{sysdeps/sparc}}
+and @w{@file{sysdeps/m68k}}.  These contain files specific to those
+machine architectures, but not specific to any particular operating
+system.  There might be subdirectories for specializations of those
+architectures, such as @w{@file{sysdeps/m68k/68020}}. Code which is
+specific to the floating-point coprocessor used with a particular
+machine should go in @w{@file{sysdeps/@var{machine}/fpu}}.
 
 There are a few directories at the top level of the @file{sysdeps}
 hierarchy that are not for particular machine architectures.
@@ -423,21 +472,21 @@ hierarchy that are not for particular machine architectures.
 @item generic
 @itemx stub
 As described above (@pxref{Porting}), these are the two subdirectories
-that every configuration uses, usually last.
+that every configuration implicitly uses after all others.
 
 @item ieee754
 This directory is for code using the IEEE 754 floating-point format,
 where the C type @code{float} is IEEE 754 single-precision format, and
-@code{double} is IEEE 754 double-precision format.  Usually this is
+@code{double} is IEEE 754 double-precision format.  Usually this
 directory is referred to in the @file{Implies} file in a machine
 architecture-specific directory, such as @file{m68k/Implies}.
 
 @item posix
 This directory contains implementations of things in the library in
-terms of POSIX.1 functions.  This includes some of the POSIX.1 functions
-themselves.  Of course, POSIX.1 cannot be completely implemented in
-terms of itself, so a configuration using just @file{posix} cannot be
-complete.
+terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
+functions themselves.  Of course, @sc{POSIX.1} cannot be completely
+implemented in terms of itself, so a configuration using just
+@file{posix} cannot be complete.
 
 @item unix
 This is the directory for Unix-like things.  See @xref{Porting to Unix}.
@@ -462,15 +511,15 @@ The code for Unix systems is in the directory @file{unix}, at the top
 level of the @file{sysdeps} hierarchy.  This directory contains
 subdirectories (and subdirectory trees) for various Unix variants.
 
-The routines which are system calls in most Unix systems are implemented
-in assembly code in files in @file{sysdeps/unix}.  These files are named
-with a suffix of @samp{.S}; for example, @file{__open.S}.  Files ending
-in @samp{.S} are run through the C preprocessor before being fed to the
-assembler.
+The functions which are system calls in most Unix systems are
+implemented in assembly code in files in @file{sysdeps/unix}.  These
+files are named with a suffix of @samp{.S}; for example,
+@file{__open.S}.  Files ending in @samp{.S} are run through the C
+preprocessor before being fed to the assembler.
 
 These files all use a set of macros that should be defined in
-@file{sysdep.h}.  The file @file{sysdep.h} in @file{sysdeps/unix}
-partially defines them; a file @file{sysdep.h} in another directory must
+@file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
+partially defines them; a @file{sysdep.h} file in another directory must
 finish defining them for the particular machine and operating system
 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
 @file{sysdep.h} implementations to see what these macros are and what
@@ -501,7 +550,7 @@ traditional C implementations.  This means you may need to make changes
 to your program in order to get it to compile.
 @end ignore
 
-@node Contributors,  , Traditional C Compatibility, Maintenance
+@node Contributors
 @appendixsec Contributors to the GNU C Library
 
 The GNU C library was written almost entirely by Roland McGrath.
@@ -509,8 +558,61 @@ Some parts of the library were contributed by other people.
 
 @itemize @bullet
 @item
-The @code{getopt} and related functions were written by
-Richard Stallman, David J. MacKenzie, and Roland McGrath.
+The @code{getopt} function and related code were written by
+@w{Richard Stallman}, @w{David J. MacKenzie}, and @w{Roland McGrath}.
+
+@item
+Most of the math functions are taken from 4.4 BSD; they have been
+modified only slightly to work with the GNU C library.  The
+Internet-related code (most of the @file{inet} subdirectory) and several
+other miscellaneous functions and header files have been included with
+little or no modification.
+
+All code incorporated from 4.4 BSD is under the following copyright:
+
+@quotation
+@display
+Copyright @copyright{} 1991 Regents of the University of California.
+All rights reserved.
+@end display
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+@enumerate
+@item
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+@item
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+@item
+All advertising materials mentioning features or use of this software
+must display the following acknowledgement:
+@quotation
+       This product includes software developed by the University of
+       California, Berkeley and its contributors.
+@end quotation
+@item
+Neither the name of the University nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+@end enumerate
+
+@sc{this software is provided by the regents and contributors ``as is'' and
+any express or implied warranties, including, but not limited to, the
+implied warranties of merchantability and fitness for a particular purpose
+are disclaimed.  in no event shall the regents or contributors be liable
+for any direct, indirect, incidental, special, exemplary, or consequential
+damages (including, but not limited to, procurement of substitute goods
+or services; loss of use, data, or profits; or business interruption)
+however caused and on any theory of liability, whether in contract, strict
+liability, or tort (including negligence or otherwise) arising in any way
+out of the use of this software, even if advised of the possibility of
+such damage.}
+@end quotation
 
 @item
 The random number generation functions @code{random}, @code{srandom},
@@ -522,11 +624,6 @@ changes to fit into the GNU C library and to fit the ANSI C standard,
 but the functional code is Berkeley's.@refill
 
 @item
-Most of the math functions are taken from 4.4 BSD, and are
-copyrighted by the Regents of the University of California.
-They have been modified only slightly to work with the GNU C library.
-
-@item
 The merge sort function @code{qsort} was written by Michael J. Haertel.
 
 @item
@@ -549,13 +646,15 @@ Torbjorn
 Granlund.@refill
 
 @item
-Some of the support code for Mach is taken from Mach 3.0, from CMU,
+Some of the support code for Mach is taken from Mach 3.0 by CMU,
 and is under the following copyright terms:
 
+@quotation
 @display
 Mach Operating System
-Copyright (c) 1991,1990,1989 Carnegie Mellon University
+Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
 All Rights Reserved.
+@end display
 
 Permission to use, copy, modify and distribute this software and its
 documentation is hereby granted, provided that both the copyright
@@ -563,21 +662,25 @@ notice and this permission notice appear in all copies of the
 software, derivative works or modified versions, and any portions
 thereof, and that both notices appear in supporting documentation.
 
-CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
-CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
-ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
+@sc{carnegie mellon allows free use of this software in its ``as is''
+condition.  carnegie mellon disclaims any liability of any kind for
+any damages whatsoever resulting from the use of this software.}
 
 Carnegie Mellon requests users of this software to return to
 
- Software Distribution Coordinator  or  Software.Distribution@@CS.CMU.EDU
+@display
+ Software Distribution Coordinator
  School of Computer Science
  Carnegie Mellon University
  Pittsburgh PA 15213-3890
-
-any improvements or extensions that they make and grant Carnegie Mellon
-the rights to redistribute these changes.
 @end display
 
+@noindent
+or @samp{Software.Distribution@@CS.CMU.EDU} any improvements or
+extensions that they make and grant Carnegie Mellon the rights to
+redistribute these changes.
+@end quotation
+
 @item
 The @file{tar.h} header file was written by David J. MacKenzie.
 
@@ -586,11 +689,14 @@ The port to the MIPS DECStation was contributed by Brendan Kehoe and Ian
 Lance Taylor.
 
 @item
-The DES encryption function @code{crypt} and related code was donated by
-Michael Glad.
+The DES encryption function @code{crypt} and related functions were
+donated by Michael Glad.
 
 @item
 The @code{ftw} function was contributed by Ian Lance Taylor.
+
+@item
+The code to support SunOS shared libraries was contributed by Tom Quinn.
 @end itemize
 
 @c @bye