477 lines
21 KiB
Plaintext
477 lines
21 KiB
Plaintext
This is Info file INSTALL, produced by Makeinfo-1.44 from the input
|
||
file manual/maint.texinfo.
|
||
|
||
|
||
Library Maintenance
|
||
********************
|
||
|
||
|
||
|
||
How to Install the GNU C Library
|
||
=================================
|
||
|
||
Installation of the GNU C library is relatively simple.
|
||
|
||
You need the latest version of GNU `make'. If you do not have GNU
|
||
`make', life is more difficult. We recommend porting GNU `make' to
|
||
your system rather than trying to install the GNU C library without
|
||
it. *Really.*
|
||
|
||
To configure the GNU C library for your system, run the script
|
||
`configure' with `sh'. You must give as an argument to the script a
|
||
word describing your system, such as `sun4' or `hp300'.
|
||
|
||
By default, the `configure' script will set things up to build
|
||
things into a subdirectory of the library source directory whose name
|
||
is the name of the system you configure for. For example,
|
||
`configure sun4' creates and uses a directory called `sun4'. If you
|
||
give a second argument to `configure', that is used as the directory
|
||
name instead.
|
||
|
||
You can build for several machines from the same source directory,
|
||
by specifying the subdirectory that `configure' created when you
|
||
configured for that machine in the `make' variable `ARCH'. For
|
||
example, use `make ARCH=sun4', or put `ARCH=sun4' in your environment.
|
||
If you don't specify a value for `ARCH', the variable `machine' is
|
||
used if defined; otherwise `make' will build for the configuration
|
||
most recently configured for.
|
||
|
||
Now edit the file `Makeconfig' to set the compilation parameters,
|
||
and what directories to install the library and header files in. See
|
||
the comments in `Makeconfig' for the details. If you are building for
|
||
several machines, you can put just the values specific to a particular
|
||
machine in a file called `Makeconfig' in the object directory for that
|
||
machine (for example, `sun4/Makeconfig'). This should *not* be an
|
||
edited copy of `Makeconfig'. Make a new file containing just the
|
||
variables in `Makeconfig' that you want to set specially for the
|
||
particular machine. These values will override the values defined in
|
||
`Makeconfig'.
|
||
|
||
Some of the machine-dependent code for some machines uses
|
||
extensions in the GNU C compiler, so you may need to compile the
|
||
library with GCC. (In fact, all of the existing complete ports
|
||
require GCC.) If possible, you should use the GNU linker, GNU `ld',
|
||
when linking programs with the GNU C library. If you are going to use
|
||
GNU `ld', be sure to specify `-DHAVE_GNU_LD' in `Makeconfig'.
|
||
|
||
To build the library and header files, type `make'. This will
|
||
produce a lot of output, some of which looks like errors from `make'
|
||
(but isn't). Look for error messages from `make' containing `***'.
|
||
Those indicate that something is really wrong. Using the `-w' option
|
||
to `make' may make the output easier to understand (this option tells
|
||
`make' to print messages telling you what subdirectories it is working
|
||
on).
|
||
|
||
To install the library and header files, type `make install', after
|
||
setting the installation directories in `Makeconfig' (or
|
||
`MACHINE/Makeconfig'). This will build things if necessary, before
|
||
installing them.
|
||
|
||
|
||
Reporting Bugs
|
||
===============
|
||
|
||
There are probably bugs in the GNU C library. If you report them,
|
||
they will get fixed. If you don't, no one will ever know about them
|
||
and they will remain unfixed for all eternity, if not longer.
|
||
|
||
To report a bug, first you must find it. Hopefully, this will be
|
||
the hard part. Once you've found a bug, make sure it's really a bug.
|
||
A good way to do this is to see if the GNU C library behaves the same
|
||
way some other C library does. If so, probably you are wrong and the
|
||
libraries are right. If not, one of the libraries is probably wrong.
|
||
|
||
Once you're sure you've found a bug, try to narrow it down to the
|
||
smallest test case that reproduces the problem. In the case of a C
|
||
library, you really only need to narrow it down to one library
|
||
function call, if possible. This should not be too difficult.
|
||
|
||
The final step when you have a simple test case is to report the
|
||
bug. When reporting a bug, send your test case, the results you 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.
|
||
|
||
If you think you have found some way in which the GNU C library
|
||
does not conform to the ANSI and POSIX standards (*note Standards and
|
||
Portability::.), that is definitely a bug. Report it!
|
||
|
||
Send bug reports to Internet address `bug-gnu-libc@prep.ai.mit.edu'
|
||
or UUCP path `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.
|
||
|
||
|
||
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.
|
||
|
||
The process of building the library is driven by the makefiles,
|
||
which make heavy use of GNU `make' features. 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. The `string' subdirectory has all the string-manipulation
|
||
functions, `stdio' has all the standard I/O functions, etc.
|
||
|
||
Each subdirectory contains a simple makefile, called `Makefile',
|
||
which defines a few `make' variables and then includes the global
|
||
makefile `Rules' with a line like:
|
||
|
||
include ../Rules
|
||
|
||
The basic variables that a subdirectory makefile defines are:
|
||
|
||
`subdir'
|
||
The name of the subdirectory, for example `stdio'. This variable
|
||
*must* be defined.
|
||
|
||
`headers'
|
||
The names of the header files in this section of the library,
|
||
such as `stdio.h'.
|
||
|
||
`routines'
|
||
`aux'
|
||
The names of the modules (source files) in this section of the
|
||
library. These should be simple names, such as `strlen' (rather
|
||
than complete file names, such as `strlen.c'). The idea is that
|
||
`routines' is for modules that define functions in the library,
|
||
and `aux' is for auxiliary modules containing things like data
|
||
definitions. But the values of `routines' and `aux' are
|
||
concatenated, so there really is no practical difference.
|
||
|
||
`tests'
|
||
The names of test programs for this section of the library. These
|
||
should be simple names, such as `tester' (rather than complete
|
||
file names, such as `tester.c'). `make tests' will build and run
|
||
all the test programs. If a test program needs input, put the
|
||
test data in a file called `TEST-PROGRAM.input'; it will 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 `TEST-PROGRAM.args'.
|
||
|
||
`others'
|
||
The names of "other" in 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 `make others'.
|
||
|
||
`install-lib'
|
||
`install-data'
|
||
`install'
|
||
Files to be installed by `make install'. Things listed in
|
||
`install-lib' are installed in the directory specified by
|
||
`libdir' in `Makeconfig' (*note Installation::.). Things listed
|
||
in `install-data' are installed in the directory specified by
|
||
`datadir' in `Makeconfig'. Things listed in `install' are
|
||
installed in the directory specified by `bindir' in `Makeconfig'.
|
||
|
||
`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. Only define `distribute' if there are files used in
|
||
an unusual way that should go into the distribution.
|
||
|
||
All the machine-dependent and operating system-dependent files in
|
||
the library are in the subdirectory `sysdeps' under the top-level
|
||
library source directory. This directory contains a hierarchy of
|
||
directories. Each subdirectory of `sysdeps' contains source files for
|
||
a particular machine or operating system, or for a class of machine or
|
||
operating system. A configuration is specified by an ordered list of
|
||
these subdirectories. Each subdirectory implicitly appends its parent
|
||
directory to the list. For example, specifying the list
|
||
`unix/bsd/hp9k3bsd' is equivalent to specifying the list
|
||
`unix/bsd/hp9k3bsd unix/bsd unix'. A subdirectory can also specify
|
||
that it implies other subdirectories which are not directly above it in
|
||
the directory hierarchy. If the file `Implies' exists in a
|
||
subdirectory, it lists other subdirectories of `sysdeps' which are
|
||
appended to the list, appearing after the subdirectory containing the
|
||
`Implies' file. Lines in an `Implies' file that begin with a `#'
|
||
character are ignored as comments. For example,
|
||
`unix/bsd/hp9k3bsd/Implies' contains:
|
||
|
||
# HP 9000 series 300 is 68k.
|
||
m68k
|
||
|
||
Since `m68k/Implies' contains:
|
||
|
||
# 68k uses IEEE 754 floating point.
|
||
ieee754
|
||
|
||
and `unix/bsd/Implies' contains:
|
||
|
||
# BSD has Internet-related things.
|
||
unix/inet
|
||
|
||
and `unix/Implies' contains:
|
||
|
||
posix
|
||
|
||
the final list is ` unix/bsd/hp9k3bsd unix/bsd m68k unix/inet unix
|
||
ieee754 posix '.
|
||
|
||
There are two "special" subdirectories of `sysdeps', `generic' and
|
||
`stub'. These two are always implicitly appended to the list of
|
||
subdirectories (in that order), so you needn't put them in an
|
||
`Implies' file, and you should not create any subdirectories under
|
||
them. `generic' is for things that can be implemented in
|
||
machine-independent C, using only other machine-independent functions
|
||
in the C library. `stub' is for "stub" versions of functions which
|
||
cannot be implemented on a particular machine or operating system.
|
||
These functions always return an error, and set `errno' to `ENOSYS'
|
||
(Function not implemented). A source file is known to be
|
||
system-dependent by its having a version in `generic' or `stub', so
|
||
every system-dependent function should have a generic or stub
|
||
implementation (there is no point in having both). If you come across
|
||
a file that is in one of the main source directories (`string',
|
||
`stdio', etc.), and you want to write a machine- or operating
|
||
system-dependent version of it, move the file into `sysdeps/generic'
|
||
and write your new implementation in the appropriate system-specific
|
||
subdirectory. Note that if a file is to be system-dependent, it *must
|
||
not* appear in one of the main source directories.
|
||
|
||
There are a few special files that may exist in each subdirectory of
|
||
`sysdeps':
|
||
|
||
`Makefile'
|
||
A makefile for this machine or operating system, or class of
|
||
machine or operating system. This file is included by the
|
||
library makefile `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
|
||
`subdir' (see above) to select different sets of variables and
|
||
rules for different sections of the library. It can also set the
|
||
`make' variable `sysdep-routines', to specify extra modules to be
|
||
included in the library. You should use `sysdep-routines' rather
|
||
than adding modules to `routines' because the latter is used in
|
||
determining what to distribute for each subdirectory of the main
|
||
source tree.
|
||
|
||
Each makefile in a subdirectory in the ordered list of
|
||
subdirectories to be searched is included in order. Since
|
||
several system-dependent makefiles may be included, each should
|
||
append to `sysdep-routines' rather than simply setting it:
|
||
|
||
sysdep-routines := $(sysdep-routines) foo bar
|
||
|
||
`Subdirs'
|
||
This file contains the names of new whole subdirectories under the
|
||
top-level library source tree that should be included for this
|
||
system. These subdirectories are treated just like the
|
||
system-independent subdirectories in the library source tree,
|
||
such as `stdio' and `math'. Use this when there are whole new
|
||
sets of routines and header files that should go into the library
|
||
for the system this subdirectory of `sysdeps' implements. For
|
||
example, `sysdeps/unix/inet/Subdirs' contains `inet'; the `inet'
|
||
directory contains various network-oriented operations which only
|
||
make sense to put in the library on systems that support the
|
||
Internet.
|
||
|
||
`Dist'
|
||
This file contains the names of files (relative the the
|
||
subdirectory of `sysdeps' in which it appears) which should be
|
||
included in the distribution. List any new files used by rules
|
||
in the `Makefile' in the same directory, or header files used by
|
||
the source files in that directory. You don't need to list files
|
||
that are implementations (either C or assembly source) of
|
||
routines whose names are given in the machine-independent
|
||
makefiles in the main source tree.
|
||
|
||
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.
|
||
|
||
|
||
|
||
The Layout of the `sysdeps' Directory Hierarchy
|
||
------------------------------------------------
|
||
|
||
Different machine architectures are generally at the top level of
|
||
the `sysdeps' hierarchy. For example, `sysdeps/sparc' and
|
||
`sysdeps/m68k'. These contain things specific to those machine
|
||
architectures (perhaps with subdirectories for specialization of those
|
||
architectures, such as `sysdeps/m68k/68881'), but not specific to any
|
||
particular operating system.
|
||
|
||
Things specific to a particular operating system on a particular
|
||
machine are canonically put in a subdirectory in the section of the
|
||
hierarchy for the operating system, usually with an `Implies' file
|
||
referring to the top-level subdirectory under `sysdeps' for the
|
||
particular machine. For example, `unix/bsd/hp9k3bsd' implies `m68k'.
|
||
|
||
There are a few directories at the top level of the `sysdeps'
|
||
hierarchy that are not for particular machine architectures.
|
||
|
||
`generic'
|
||
`stub'
|
||
As described above (*note Porting::.), these are the two
|
||
subdirectories that every configuration uses, usually last.
|
||
|
||
`ieee754'
|
||
This directory is for code using the IEEE 754 floating-point
|
||
format, where the C type `float' is IEEE 754 single-precision
|
||
format, and `double' is IEEE 754 double-precision format.
|
||
Usually this is directory is referred to in the `Implies' file in
|
||
a machine architecture-specific directory, such as `m68k/Implies'.
|
||
|
||
`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
|
||
`posix' cannot be complete.
|
||
|
||
`unix'
|
||
This is the directory for Unix-like things. See *Note Porting to
|
||
Unix::. `unix' implies `posix'.
|
||
|
||
`mach'
|
||
This is the directory for things based on the Mach microkernel
|
||
from CMU (including the GNU operating system). Other basic
|
||
operating systems (VMS, for example) would have their own
|
||
directories at the top level of the `sysdeps' hierarchy, parallel
|
||
to `unix' and `mach'.
|
||
|
||
|
||
Porting the GNU C Library to Unix Systems
|
||
------------------------------------------
|
||
|
||
Most Unix systems are fundamentally very similar. There are
|
||
variations between different machines, and variations in what
|
||
facilities are provided by the kernel. But the interface to the
|
||
operating system facilities is, for the most part, pretty uniform and
|
||
simple.
|
||
|
||
The code for Unix systems is in the directory `unix', at the top
|
||
level of the `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 `sysdeps/unix'. These files
|
||
are named with a suffix of `.S'; for example, `__open.S'. Files ending
|
||
in `.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 `sysdep.h'. The `sysdep.h' in `sysdeps/unix' does not adequately
|
||
define them. They must be defined for the particular machine and
|
||
operating system variant. See `sysdeps/unix/sysdep.h' and the
|
||
machine-specific `sysdep.h' implementations to see what these macros
|
||
are and what they should do.
|
||
|
||
The system-specific makefile for the `unix' directory,
|
||
`sysdeps/unix/Makefile', gives rules to generate several files from
|
||
the Unix system you are building the library on (which is assumed to be
|
||
the target system you are building the library *for*). All the
|
||
generated files are put in the directory where the object files are
|
||
kept; they should not affect the source tree itself. The files
|
||
generated are: `ioctls.h', `errnos.h', `sys/param.h', and `errlist.c'
|
||
(for the `stdio' section of the library).
|
||
|
||
|
||
Compatibility with Traditional C
|
||
=================================
|
||
|
||
Although the GNU C library implements the ANSI C library facilities,
|
||
you *can* use the GNU C library with traditional, "pre-ANSI" C
|
||
compilers. However, there are a couple things you need to watch out
|
||
for.
|
||
|
||
You must include a different set of header files when compiling your
|
||
program using a traditional C compiler than when compiling with an ANSI
|
||
C compiler. (This is because traditional C compilers do not understand
|
||
the function prototypes used in the ANSI C header files. On the other
|
||
hand, if you are using an ANSI C compiler like GCC, you should use the
|
||
ANSI C header files because the prototypes permit the compiler to do a
|
||
better job of detecting errors in calls to library functions.) You can
|
||
tell the C compiler what directories to search for header files by
|
||
using the `-I' option. Set the `trad-incldir' variable in
|
||
`Makeconfig' to choose where to install this set of header files.
|
||
|
||
You also need to be careful because the content and organization of
|
||
the GNU C library header files differs from that of traditional C
|
||
implementations. This means you may need to make changes to your
|
||
program in order to get it to compile.
|
||
|
||
|
||
Contributors to the GNU C Library
|
||
==================================
|
||
|
||
The GNU C library was written almost entirely by Roland McGrath.
|
||
Some parts of the library were contributed by other people.
|
||
|
||
* The `getopt' and related functions were written by Richard
|
||
Stallman, David J. MacKenzie, and Roland McGrath.
|
||
|
||
* The random number generation functions `random', `srandom',
|
||
`setstate' and `initstate', which are also the basis for the
|
||
`rand' and `srand' functions, were written by Earl T. Cohen for
|
||
the University of California at Berkeley and are copyrighted by
|
||
the Regents of the University of California. They have undergone
|
||
minor changes to fit into the GNU C library and to fit the ANSI C
|
||
standard, but the functional code is Berkeley's.
|
||
|
||
* 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.
|
||
|
||
* The `qsort' function was written by Douglas C. Schmidt.
|
||
|
||
* The memory allocation functions `malloc', `realloc' and `free'
|
||
and related code were written by Michael J. Haertel.
|
||
|
||
* Fast implementations of many of the string functions (`memcpy',
|
||
`strlen', etc.) were written by Torbjorn Granlund.
|
||
|
||
* Some of the support code for Mach is taken from Mach 3.0, from
|
||
CMU, and is under the following copyright terms:
|
||
|
||
Mach Operating System
|
||
Copyright (c) 1991,1990,1989 Carnegie Mellon University
|
||
All Rights Reserved.
|
||
|
||
Permission to use, copy, modify and distribute this software and its
|
||
documentation is hereby granted, provided that both the copyright
|
||
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.
|
||
|
||
Carnegie Mellon requests users of this software to return to
|
||
|
||
Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
|
||
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.
|
||
|
||
* The `tar.h' header file was written by David J. MacKenzie.
|
||
|
||
|
||
|
||
Tag Table:
|
||
Node: Maintenance97
|
||
Node: Installation141
|
||
Node: Reporting Bugs3131
|
||
Node: Porting4714
|
||
Node: Hierarchy Conventions13569
|
||
Node: Porting to Unix15729
|
||
Node: Compatibility with Traditional C17429
|
||
Node: Contributors to the GNU C Library18645
|
||
|
||
End Tag Table
|