9a821cf90b
* elf/rtld.c: Add a few __builtin_expects where they will improve a lot. 1998-11-05 Ulrich Drepper <drepper@cygnus.com> 1998-11-04 Andreas Schwab <schwab@issan.cs.uni-dortmund.de> * libio/genops.c (_IO_least_marker): Add additional parameter end_p replacing fp->_IO_read_end. (save_for_backup): Likewise. All callers changed. Use _IO_size_t and _IO_ssize_t instead of int. (_IO_switch_to_main_get_area): Remove use of _IO_save_ptr. (_IO_switch_to_backup_area): Likewise. Fix comments. (_IO_seekmark): Undo last change. (_IO_default_pbackfail): Correct use of backup area. * libio/libio.h (_IO_FILE_complete): Remove _IO_save_ptr.
421 lines
17 KiB
Plaintext
421 lines
17 KiB
Plaintext
@c This is for making the `INSTALL' file for the distribution.
|
|
@c Makeinfo ignores it when processing the file from the include.
|
|
@setfilename INSTALL
|
|
|
|
@node Installation, Maintenance, Library Summary, Top
|
|
@c %MENU% How to install the GNU C library
|
|
@appendix Installing the GNU C Library
|
|
|
|
Before you do anything else, you should read the file @file{FAQ} found
|
|
at the top level of the source tree. This file answers common questions
|
|
and describes problems you may experience with compilation and
|
|
installation. It is updated more frequently than this manual.
|
|
|
|
Two components of GNU Libc are distributed as @dfn{add-on} bundles
|
|
separate from the main distribution. Unless you are doing an unusual
|
|
installation, you should get them both. Support for the @code{crypt}
|
|
function is distributed separately because of US export restrictions.
|
|
If you are outside the US or Canada, you must get @code{crypt} support
|
|
from a site outside the US, such as @samp{ftp.ifi.uio.no}.
|
|
@c Check this please someone:
|
|
(Most non-US mirrors of @samp{ftp.gnu.org} will have it too.) The file
|
|
you need is @file{glibc-crypt-@var{VERSION}.tar.gz}. Support for POSIX
|
|
threads is maintained by someone else, so it's in a separate package.
|
|
At the moment it is only available for Linux systems; this will change
|
|
in the future. Get it from the same place you got the main bundle; the
|
|
file is @file{glibc-linuxthreads-@var{VERSION}.tar.gz}. Both add-on
|
|
bundles should be unpacked into the top level of the libc source tree.
|
|
|
|
You will need recent versions of several GNU tools: definitely GCC and
|
|
GNU Make, and possibly others. @xref{Tools for Compilation}, below.
|
|
|
|
@menu
|
|
* Configuring and compiling:: How to compile and test GNU libc.
|
|
* Tools for Compilation:: You'll need these first.
|
|
* Supported Configurations:: What it runs on, what it doesn't.
|
|
* Reporting Bugs:: So they'll get fixed.
|
|
@end menu
|
|
|
|
@node Configuring and compiling
|
|
@appendixsec Configuring and compiling GNU Libc
|
|
|
|
GNU Libc cannot be compiled in the source directory. You must create a
|
|
separate directory for the object files. This directory should be
|
|
outside the source tree. For example, if you have unpacked the glibc
|
|
sources in @file{/src/gnu/glibc-2.1.0}, create a directory
|
|
@file{/src/gnu/glibc-build} to put the object files in.
|
|
|
|
From your object directory, run the shell script @file{configure} found
|
|
at the top level of the source tree. In the scenario above, you'd type
|
|
|
|
@smallexample
|
|
$ ../glibc-2.1.0/configure @var{args...}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@code{configure} takes many options, but you can get away with knowing
|
|
only two: @samp{--enable-add-ons} and @samp{--prefix}. The
|
|
@samp{--enable-add-ons} option tells configure to use all the add-on
|
|
bundles it finds in the source directory. Since important functionality
|
|
is provided in add-ons, you should always give this option. The
|
|
@code{--prefix} option tells configure where you want glibc installed.
|
|
This defaults to @file{/usr/local}. If you are installing glibc as your
|
|
primary C library, give the option @samp{--prefix=/usr}, which will put
|
|
components in @file{/usr} or @file{/} as appropriate.
|
|
|
|
It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
|
|
the environment when running @code{configure}. @var{CC} selects the C
|
|
compiler that will be used, and @var{CFLAGS} sets optimization options
|
|
for the compiler.
|
|
|
|
Here are all the useful options known by @code{configure}:
|
|
|
|
@table @samp
|
|
@item --prefix=@var{directory}
|
|
Install machine-independent data files in subdirectories of
|
|
@file{@var{directory}}. The default is to install in @file{/usr/local}.
|
|
|
|
@item --exec-prefix=@var{directory}
|
|
Install the library and other machine-dependent files in subdirectories
|
|
of @file{@var{directory}}. The default is to the @samp{--prefix}
|
|
directory if that option is given, or @file{/usr/local} otherwise.
|
|
|
|
@item --with-headers=@var{directory}
|
|
Look for kernel header files in @var{directory}, not
|
|
@file{/usr/include}. Glibc needs information from the kernel's private
|
|
header files. It will normally look in @file{/usr/include} for them,
|
|
but if you give this option, it will look in @var{DIRECTORY} instead.
|
|
|
|
This option is primarily of use on a system where the headers in
|
|
@file{/usr/include} come from an older version of glibc. Conflicts can
|
|
occasionally happen in this case. Note that Linux libc5 qualifies as an
|
|
older version of glibc. You can also use this option if you want to
|
|
compile glibc with a newer set of kernel headers than the ones found in
|
|
@file{/usr/include}.
|
|
|
|
@item --enable-add-ons[=@var{list}]
|
|
Enable add-on packages in your source tree. If this option is given
|
|
with no list, it enables all the add-on packages it finds. If you do
|
|
not wish to use some add-on package that you have present in your source
|
|
tree, give this option a list of the add-ons that you @emph{do} want
|
|
used, like this: @samp{--enable-add-ons=crypt,linuxthreads}
|
|
|
|
@item --with-binutils=@var{directory}
|
|
Use the binutils (assembler and linker) in @file{@var{directory}}, not
|
|
the ones the C compiler would default to. You could use this option if
|
|
the default binutils on your system cannot deal with all the constructs
|
|
in the GNU C library. (@code{configure} will detect the problem and
|
|
suppress these constructs, so the library will still be usable, but
|
|
functionality may be lost---for example, you can not build a shared libc
|
|
with old binutils.)
|
|
|
|
@c extra blank line makes it look better
|
|
@item --without-fp
|
|
Use this option if your computer lacks hardware floating-point support
|
|
and your operating system does not emulate an FPU.
|
|
|
|
@item --disable-static
|
|
Don't build static libraries. Static libraries aren't that useful these
|
|
days, but we recommend you build them in case you need them.
|
|
|
|
@item --disable-shared
|
|
Don't build shared libraries even if we could. Not all systems support
|
|
shared libraries; you need ELF support and (currently) the GNU linker.
|
|
|
|
@item --disable-profile
|
|
Don't build libraries with profiling information. You may want to use
|
|
this option if you don't plan to do profiling.
|
|
|
|
@item --enable-omitfp
|
|
Use maximum optimization for the normal (static and shared)
|
|
libraries, and compile separate static libraries with debugging
|
|
information and no optimisation. We recommend against this. The extra
|
|
optimization doesn't gain you much, it may provoke compiler bugs, and
|
|
you won't be able to trace bugs through the C library.
|
|
|
|
@item --disable-versioning
|
|
Don't compile the shared libraries with symbol version information.
|
|
Doing this will make the library that's built incompatible with old
|
|
binaries, so it's not recommended.
|
|
|
|
@item --enable-static-nss
|
|
Compile static versions of the NSS (Name Service Switch) libraries.
|
|
This is not recommended because it defeats the purpose of NSS; a program
|
|
linked statically with the NSS libraries cannot be dynamically
|
|
reconfigured to use a different name database.
|
|
|
|
@c another extra blank line
|
|
@item --build=@var{build-system}
|
|
@itemx --host=@var{host-system}
|
|
These options are for cross-compiling. If you give them both and
|
|
@var{build-system} is different from @var{host-system}, @code{configure}
|
|
will prepare to cross-compile glibc from @var{build-system} to be used
|
|
on @var{host-system}. You'll probably need the @samp{--with-headers}
|
|
option too, and you may have to override @var{configure}'s selection of
|
|
the compiler and/or binutils.
|
|
|
|
If you give just one of these, @code{configure} will get confused. If
|
|
@code{configure} doesn't correctly guess your system type for a native
|
|
build, report that as a bug.
|
|
@end table
|
|
|
|
To build the library and related programs, type @code{make}. This will
|
|
produce a lot of output, some of which may look like errors from
|
|
@code{make} but isn't. Look for error messages from @code{make}
|
|
containing @samp{***}. Those indicate that something is really wrong.
|
|
|
|
The compilation process takes several hours even on fast hardware.
|
|
Expect at least two hours for the default configuration on i586 for
|
|
Linux. For Hurd times are much longer. Except for EGCS 1.1 (and later
|
|
versions of EGCS), all supported versions of GCC have a problem which
|
|
causes them to take several minutes to compile certain files in the
|
|
iconvdata directory. Do not panic if the compiler appears to hang.
|
|
|
|
If you want to run a parallel make, you can't just give @code{make} the
|
|
@samp{-j} option, because it won't be passed down to the sub-makes.
|
|
Instead, edit the generated @file{Makefile} and uncomment the line
|
|
|
|
@smallexample
|
|
# PARALLELMFLAGS = -j 4
|
|
@end smallexample
|
|
|
|
@noindent
|
|
You can change the @samp{4} to some other number as appropriate for
|
|
your system.
|
|
|
|
To build and run some test programs which exercise some of the library
|
|
facilities, type @code{make check}. This should complete successfully;
|
|
if it doesn't, do not use the built library, and report a bug.
|
|
@xref{Reporting Bugs}, for how to do that. Note that some of the tests
|
|
assume they are not being run by @code{root}. We recommend you compile
|
|
and test glibc as an unprivileged user.
|
|
|
|
To format the @cite{GNU C Library Reference Manual} for printing, type
|
|
@w{@code{make dvi}}. You need a working @TeX{} installation to do this.
|
|
|
|
To install the library and its header files, and the Info files of the
|
|
manual, type @code{make install}. This will build things if necessary,
|
|
before installing them. If you want to install the files in a different
|
|
place than the one specified at configuration time you can specify a
|
|
value for the Makefile variable @code{install_root} on the command line.
|
|
This is useful to create chroot'ed environment or to prepare binary
|
|
releases.@refill
|
|
|
|
@node Tools for Compilation
|
|
@appendixsec Recommended Tools for Compilation
|
|
@cindex installation tools
|
|
@cindex tools, for installing library
|
|
|
|
We recommend installing the following GNU tools before attempting to
|
|
build the GNU C library:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
GNU @code{make} 3.75
|
|
|
|
You need the latest version of GNU @code{make}. Modifying the GNU C
|
|
Library to work with other @code{make} programs would be so hard that we
|
|
recommend you port GNU @code{make} instead. @strong{Really.} We
|
|
recommend version GNU @code{make} version 3.75 or 3.77. All earlier
|
|
versions have severe bugs or lack features. Version 3.76 is known to
|
|
have bugs which only show up in big projects like GNU @code{libc}.
|
|
Version 3.76.1 seems OK but some people have reported problems.
|
|
|
|
@item
|
|
EGCS 1.1 or 1.0.3
|
|
|
|
The GNU C library can only be compiled with the GNU C compiler family.
|
|
We recommend EGCS 1.0.3 or higher. GCC 2.8.1 and older versions of EGCS
|
|
may have problems, particularly on non-Intel architectures. GCC 2.7.x
|
|
has catastrophic bugs and cannot be used at all.
|
|
|
|
@item
|
|
GNU @code{binutils} 2.8.1.0.23, 2.9.1, or 2.9.0.15
|
|
|
|
You must use GNU binutils (as and ld) if you want to build a shared
|
|
library. Even if you don't, we recommend you use them anyway. No one
|
|
has tested compilation with non-GNU binutils in a long time.
|
|
|
|
The quality of binutils releases has varied a bit recently. The bugs
|
|
are in obscure features, but glibc uses quite a few of those.
|
|
2.8.1.0.23, 2.9.1, and 2.9.0.15 are known to work. Versions after
|
|
2.8.1.0.23 may or may not work. Older versions definitely don't.
|
|
|
|
@item
|
|
GNU @code{texinfo} 3.11
|
|
|
|
To correctly translate and install the Texinfo documentation you need
|
|
this version of the @code{texinfo} package. Earlier versions do not
|
|
understand all the tags used in the document, and the installation
|
|
mechanisms for the info files is not present or works differently.
|
|
|
|
On some Debian Linux based systems the @code{install-info} program
|
|
supplied with the system works differently from the one we expect. You
|
|
must therefore run @code{make install} like this:
|
|
|
|
@smallexample
|
|
make INSTALL_INFO=/path/to/GNU/install-info install
|
|
@end smallexample
|
|
|
|
@item
|
|
GNU @code{awk} 3.0, or some other POSIX awk
|
|
|
|
Awk is used in several places to generate files. The scripts should
|
|
work with any POSIX-compliant awk implementation; GNU awk 3.0 and
|
|
@code{mawk} 1.3 are known to work.
|
|
|
|
@item
|
|
Perl 5
|
|
|
|
Perl is not required, but it is used if present to test the
|
|
installation. We may decide to use it elsewhere in the future.
|
|
|
|
@end itemize
|
|
|
|
@noindent
|
|
If you change any of the @file{configure.in} files you will also need
|
|
|
|
@itemize @bullet
|
|
@item
|
|
GNU @code{autoconf} 2.12
|
|
@end itemize
|
|
|
|
@noindent
|
|
and if you change any of the message translation files you will need
|
|
|
|
@itemize @bullet
|
|
@item
|
|
GNU @code{gettext} 0.10.35 or later
|
|
@end itemize
|
|
|
|
@noindent
|
|
You may also need these packages if you upgrade your source tree using
|
|
patches, although we try to avoid this.
|
|
|
|
@node Supported Configurations
|
|
@appendixsec Supported Configurations
|
|
@cindex configurations, all supported
|
|
|
|
The GNU C Library currently supports configurations that match the
|
|
following patterns:
|
|
|
|
@smallexample
|
|
alpha-@var{*}-linux
|
|
arm-@var{*}-linux
|
|
arm-@var{*}-linuxaout
|
|
arm-@var{*}-none
|
|
i@var{x}86-@var{*}-gnu
|
|
i@var{x}86-@var{*}-linux
|
|
m68k-@var{*}-linux
|
|
powerpc-@var{*}-linux
|
|
sparc-@var{*}-linux
|
|
sparc64-@var{*}-linux
|
|
@end smallexample
|
|
|
|
Former releases of this library (version 1.09.1 and perhaps earlier
|
|
versions) used to run on the following configurations:
|
|
|
|
@smallexample
|
|
alpha-dec-osf1
|
|
alpha-@var{*}-linuxecoff
|
|
i@var{x}86-@var{*}-bsd4.3
|
|
i@var{x}86-@var{*}-isc2.2
|
|
i@var{x}86-@var{*}-isc3.@var{n}
|
|
i@var{x}86-@var{*}-sco3.2
|
|
i@var{x}86-@var{*}-sco3.2v4
|
|
i@var{x}86-@var{*}-sysv
|
|
i@var{x}86-@var{*}-sysv4
|
|
i@var{x}86-force_cpu386-none
|
|
i@var{x}86-sequent-bsd
|
|
i960-nindy960-none
|
|
m68k-hp-bsd4.3
|
|
m68k-mvme135-none
|
|
m68k-mvme136-none
|
|
m68k-sony-newsos3
|
|
m68k-sony-newsos4
|
|
m68k-sun-sunos4.@var{n}
|
|
mips-dec-ultrix4.@var{n}
|
|
mips-sgi-irix4.@var{n}
|
|
sparc-sun-solaris2.@var{n}
|
|
sparc-sun-sunos4.@var{n}
|
|
@end smallexample
|
|
|
|
Since no one has volunteered to test and fix these configurations,
|
|
they are not supported at the moment. They probably don't compile;
|
|
they definitely don't work anymore. Porting the library is not hard.
|
|
If you are interested in doing a port, please contact the glibc
|
|
maintainers by sending electronic mail to @email{bug-glibc@@gnu.org}.
|
|
|
|
Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486},
|
|
@samp{i586}, or @samp{i686}. All of those configurations produce a
|
|
library that can run on any of these processors. The library will be
|
|
optimized for the specified processor, but will not use instructions not
|
|
available on all of them.
|
|
|
|
While no other configurations are supported, there are handy aliases for
|
|
these few. (These aliases work in other GNU software as well.)
|
|
|
|
@smallexample
|
|
decstation
|
|
hp320-bsd4.3 hp300bsd
|
|
i486-gnu
|
|
i586-linux
|
|
i386-sco
|
|
i386-sco3.2v4
|
|
i386-sequent-dynix
|
|
i386-svr4
|
|
news
|
|
sun3-sunos4.@var{n} sun3
|
|
sun4-solaris2.@var{n} sun4-sunos5.@var{n}
|
|
sun4-sunos4.@var{n} sun4
|
|
@end smallexample
|
|
|
|
@node Reporting Bugs
|
|
@appendixsec Reporting Bugs
|
|
@cindex reporting bugs
|
|
@cindex bugs, reporting
|
|
|
|
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 library does. If so, probably you are wrong and the
|
|
libraries are right (but not necessarily). 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. Also include the files
|
|
@file{config.status} and @file{config.make} which are created by running
|
|
@file{configure}; they will be in whatever directory was current when
|
|
you ran @file{configure}.
|
|
|
|
If you think you have found some way in which the GNU C library does not
|
|
conform to the ISO and POSIX standards (@pxref{Standards and
|
|
Portability}), that is definitely a bug. Report it!@refill
|
|
|
|
Send bug reports to the Internet address @email{bug-glibc@@gnu.org}
|
|
using the @code{glibcbug} script which is installed by the GNU C
|
|
library. If you have other problems with installation or use, please
|
|
report those as well.@refill
|
|
|
|
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. If you find any
|
|
errors or omissions in this manual, please report them to the Internet
|
|
address @email{bug-glibc-manual@@gnu.org}. If you refer to specific
|
|
sections when reporting on the manual, please include the section names
|
|
for easier identification.
|