path: root/INSTALL

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'.  Modifying the GNU C
Library to work with other `make' programs would be so hard that we
recommend you port GNU `make' instead.  *Really.*

   To configure the GNU C library for your system, run the shell script
`configure' with `sh'.  Use an argument which is the conventional GNU
name for your system configuration--for example, `sparc-sun-sunos4.1',
for a Sun 4 running Sunos 4.1.  *Note Installation:
(gcc.info)Installation, for a full description of standard GNU
configuration names.  If you omit the configuration name, `configure'
will try to guess one for you by inspecting the system it is running
on.  It may or may not be able to come up with a guess, and the its
guess might be wrong.  `configure' will tell you the canonical name of
the chosen configuration before proceeding.

   The GNU C Library currently supports configurations that match the
following patterns:

     alpha-dec-osf1
     i386-ANYTHING-bsd4.3
     i386-ANYTHING-gnu
     i386-ANYTHING-isc2.2
     i386-ANYTHING-isc3.N
     i386-ANYTHING-sco3.2
     i386-ANYTHING-sco3.2v4
     i386-ANYTHING-sysv
     i386-ANYTHING-sysv4
     i386-force_cpu386-none
     i386-sequent-bsd
     i960-nindy960-none
     m68k-hp-bsd4.3
     m68k-mvme135-none
     m68k-mvme136-none
     m68k-sony-newsos3
     m68k-sony-newsos4
     m68k-sun-sunos4.N
     mips-dec-ultrix4.N
     mips-sgi-irix4.N
     sparc-sun-solaris2.N
     sparc-sun-sunos4.N

   While no other configurations are supported, there are handy aliases
for these few.  (These aliases work in other GNU software as well.)

     decstation
     hp320-bsd4.3 hp300bsd
     i386-sco
     i386-sco3.2v4
     i386-sequent-dynix
     i386-svr4
     news
     sun3-sunos4.N sun3
     sun4-solaris2.N sun4-sunos5.N
     sun4-sunos4.N sun4

   Here are some options that you should specify (if appropriate) when
you run `configure':

`--with-gnu-ld'
     Use this option if you plan to use GNU `ld' to link programs with
     the GNU C Library.  (We strongly recommend that you do.)  This
     option enables use of features that exist only in GNU `ld'; so if
     you configure for GNU `ld' you must use GNU `ld' *every time* you
     link with the GNU C Library, and when building it.

`--with-gnu-as'
     Use this option if you plan to use the GNU assembler, `gas', when
     building the GNU C Library.  On some systems, the library may not
     build properly if you do *not* use `gas'.

`--nfp'
     Use this option if your computer lacks hardware floating point
     support.

`--prefix=DIRECTORY'
     Install machine-independent data files in subdirectories of
     `DIRECTORY'.  (You can also set this in `configparms'; see below.)

`--exec-prefix=DIRECTORY'
     Install the library and other machine-dependent files in
     subdirectories of `DIRECTORY'.  (You can also set this in
     `configparms'; see below.)

   The simplest way to run `configure' is to do it in the directory
that contains the library sources.  This prepares to build the library
in that very directory.

   You can prepare to build the library in some other directory by going
to that other directory to run `configure'.  In order to run configure,
you will have to specify a directory for it, like this:

     mkdir sun4
     cd sun4
     ../configure sparc-sun-sunos4.1

`configure' looks for the sources in whatever directory you specified
for finding `configure' itself.  It does not matter where in the file
system the source and build directories are--as long as you specify the
source directory when you run `configure', you will get the proper
results.

   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 `configure' in that
directory specifying the target machine's configuration name.

   The library has a number of special-purpose configuration parameters.
These are defined in the file `Makeconfig'; see the comments in that
file for the details.

   But don't edit the file `Makeconfig' yourself--instead, create a
file `configparms' in the directory where you are building the library,
and define in that file the parameters you want to specify.
`configparms' should *not* be an edited copy of `Makeconfig'; specify
only the parameters that you want to override.  To see how to set these
parameters, find the section of `Makeconfig' that says "These are the
configuration variables." Then for each parameter that you want to
change, copy the definition from `Makeconfig' to your new `configparms'
file, and change the value as appropriate for your system.

   It is easy to configure the GNU C library for cross-compilation by
setting a few variables in `configparms'.  Set `CC' to the
cross-compiler for the target you configured the library for; it is
important to use this same `CC' value when running `configure', like
this: `CC=TARGET-gcc configure TARGET'.  Set `BUILD_CC' to the compiler
to use for for programs run on the build system as part of compiling
the library.  You may need to set `AR' and `RANLIB' to cross-compiling
versions of `ar' and `ranlib' if the native tools are not configured to
work with object files for the target you configured for.

   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.)

   The current release of the C library contains some header files that
the compiler normally provides: `stddef.h', `stdarg.h', and several
files with names of the form `va-MACHINE.h'.  The versions of these
files that came with older releases of GCC do not work properly with
the GNU C library.  The `stddef.h' file in release 2.2 and later of GCC
is correct.  If you have release 2.2 or later of GCC, use its version
of `stddef.h' instead of the C library's.  To do this, put the line
`override stddef.h =' in `configparms'.  The other files are corrected
in release 2.3 and later of GCC.  `configure' will automatically detect
whether the installed `stdarg.h' and `va-MACHINE.h' files are
compatible with the C library, and use its own if not.

   There is a potential problem with the `size_t' type and versions of
GCC prior to release 2.4.  ANSI C requires that `size_t' always be an
unsigned type.  For compatibility with existing systems' header files,
GCC defines `size_t' in `stddef.h' to be whatever type the system's
`sys/types.h' defines it to be.  Most Unix systems that define `size_t'
in `sys/types.h', define it to be a signed type.  Some code in the
library depends on `size_t' being an unsigned type, and will not work
correctly if it is signed.

   The GNU C library code which expects `size_t' to be unsigned is
correct.  The definition of `size_t' as a signed type is incorrect.
Versions 2.4 and later of GCC always define `size_t' as an unsigned
type, and GCC's `fixincludes' script massages the system's
`sys/types.h' so as not to conflict with this.

   In the meantime, we work around this problem by telling GCC
explicitly to use an unsigned type for `size_t' when compiling the GNU C
library.  `configure' will automatically detect what type GCC uses for
`size_t' arrange to override it if necessary.

   To build the library, type `make lib'.  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.

   To build and run some test programs which exercise some of the
library facilities, type `make tests'.  This will produce several files
with names like `PROGRAM.out'.

   To format the `GNU C Library Reference Manual' for printing, type
`make dvi'.  To format the Info version of the manual for on line
reading with `C-h i' in Emacs or with the `info' program, type
`make info'.

   To install the library and its header files, and the Info files of
the manual, type `make install', after setting the installation
directories in `configparms'.  This will build things if necessary,
before installing them.

Reporting Bugs
==============

   There are probably bugs in the GNU C library.  There are certainly
errors and omissions in this manual.  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 li