aboutsummaryrefslogtreecommitdiff
path: root/manual/install.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/install.texi')
-rw-r--r--manual/install.texi227
1 files changed, 151 insertions, 76 deletions
diff --git a/manual/install.texi b/manual/install.texi
index 3712643..a681518 100644
--- a/manual/install.texi
+++ b/manual/install.texi
@@ -11,33 +11,42 @@ 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}.
+Features can be added to GNU Libc via @dfn{add-on} bundles. These are
+separate tarfiles which you unpack into the top level of the source
+tree. Then you give @code{configure} the @samp{--enable-add-ons} option
+to activate them, and they will be compiled into the library. As of the
+2.1 release, two important components of glibc are distributed as
+``official'' add-ons. Unless you are doing an unusual installation, you
+should get them both.
+
+Support for POSIX threads is maintained by someone else, so it's in a
+separate package. It is only available for Linux systems, but 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}.
+Support for the @code{crypt} function is distributed separately because
+of United States 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 need is @file{glibc-crypt-@var{VERSION}.tar.gz}.
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.
+* Installation:: How to install it once you've got it compiled.
* Tools for Compilation:: You'll need these first.
* Supported Configurations:: What it runs on, what it doesn't.
+* Linux:: Specific advice for Linux systems.
* Reporting Bugs:: So they'll get fixed.
@end menu
@node Configuring and compiling
@appendixsec Configuring and compiling GNU Libc
+@cindex configuring
+@cindex compiling
GNU Libc cannot be compiled in the source directory. You must create a
separate directory for the object files. This directory should be
@@ -54,14 +63,12 @@ $ ../glibc-2.1.0/configure @var{args...}
@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
+only two: @samp{--prefix} and @samp{--enable-add-ons}. 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.
+This defaults to @file{/usr/local}. 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.
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
@@ -109,7 +116,6 @@ 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.
@@ -144,7 +150,6 @@ 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
@@ -154,9 +159,16 @@ 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.
+If you give just @samp{--host}, configure will prepare for a native
+compile but use what you say instead of guessing what your system is.
+This is most useful to change the CPU submodel. For example, if
+configure guesses your machine as @code{i586-pc-linux-gnu} but you want
+to compile a library optimized for 386es, give
+@samp{--host=i386-pc-linux-gnu} or just @samp{--host=i386-linux}. (A
+library compiled for a Pentium (@code{i586}) will still work on a 386,
+but it may be slower.)
+
+If you give just @samp{--build}, configure will get confused.
@end table
To build the library and related programs, type @code{make}. This will
@@ -192,14 +204,57 @@ 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.
+The distribution already includes the on-line formatted version of the
+manual, as Info files. You can regenerate those with @w{@code{make
+info}}, but it shouldn't be necessary.
+
+@node Installation
+@appendixsec Installing the C Library
+@cindex installing
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
+before installing them. Don't rely on that; compile everything first.
+If you are installing glibc as your primary C library, we recommend you
+shut the system down to single-user mode first, and reboot afterward.
+This minimizes the risk of breaking things when the library changes out
+from underneath.
+
+If you are upgrading from a previous installation of glibc 2.0 or 2.1,
+@samp{make install} will do the entire job. If you're upgrading from
+Linux libc5 or some other C library, you need to rename the old
+@file{/usr/include} directory out of the way first, or you will end up
+with a mixture of header files from both libraries, and you won't be
+able to compile anything. You may also need to reconfigure GCC to work
+with the new library. The easiest way to do that is to figure out the
+compiler switches to make it work again
+(@samp{-Wl,-dynamic-linker=/lib/ld-linux.so.2} should work on Linux
+systems) and use them to recompile gcc. You can also edit the specs
+file (@file{/usr/lib/gcc-lib/@var{TARGET}/@var{VERSION}/specs}), but
+that is a bit of a black art.
+
+You can install glibc somewhere other than where you configured it to go
+by setting the @code{install_root} variable on the command line for
+@samp{make install}. The value of this variable is prepended to all the
+paths for installation. This is useful when setting up a chroot
+environment or preparing a binary distribution.
+
+Glibc 2.1 includes two daemons, @code{nscd} and @code{utmpd}, which you
+may or may not want to run. @code{nscd} caches name service lookups; it
+can dramatically improve performance with NIS+, and may help with DNS as
+well. @code{utmpd} allows programs that use the old format for the
+@file{utmp} file to coexist with new programs. For more information see
+the files @file{nscd/README} and @file{login/README.utmpd}.
+
+One auxiliary program, @file{/usr/libexec/pt_chown}, is installed setuid
+@code{root}. This program is invoked by the @code{grantpt} function; it
+sets the permissions on a pseudoterminal so it can be used by the
+calling process. This means programs like @code{xterm} and
+@code{screen} do not have to be setuid to get a pty. (There may be
+other reasons why they need privileges.) If you are using a 2.1 Linux
+kernel with the @code{devptsfs} or @code{devfs} filesystems providing
+pty slaves, you don't need this program; otherwise you do. The source
+for @file{pt_chown} is in @file{login/programs/pt_chown.c}.
@node Tools for Compilation
@appendixsec Recommended Tools for Compilation
@@ -227,7 +282,9 @@ 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.
+has catastrophic bugs and cannot be used at all. (You can use GCC 2.7.x
+to compile programs that use GNU libc, but you may have problems,
+particularly with the math functions.)
@item
GNU @code{binutils} 2.8.1.0.23, 2.9.1, or 2.9.0.15
@@ -247,21 +304,13 @@ 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
+mechanism for the info files is not present or works differently.
@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
+work with any POSIX-compliant awk implementation; @code{gawk} 3.0 and
@code{mawk} 1.3 are known to work.
@item
@@ -350,25 +399,53 @@ 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
+available on all of them. If you want the library to use instructions
+only available on newer processors, give GCC the appropriate @samp{-m}
+switches via @var{CFLAGS}.
+
+@node Linux
+@appendixsec Specific advice for Linux systems
+@cindex upgrading from libc5
+@cindex kernel header files
+
+If you are installing GNU libc on a Linux system, you need to have the
+header files from a development kernel around for reference. You do not
+need to use the development kernel, just have its headers where glibc
+can get at them. The easiest way to do this is to unpack a development
+kernel in a directory such as @file{/usr/src/linux-dev}. In that
+directory, run @samp{make config} and accept all the defaults. Then
+configure glibc with the option
+@samp{--with-headers=/usr/src/linux-dev/include}. Use the latest
+development kernel you can get your hands on.
+
+An alternate tactic is to unpack the development kernel and run
+@samp{make config} as above. Then rename or delete @file{/usr/include},
+create a new @file{/usr/include}, and make the usual symbolic links of
+@file{/usr/include/linux} and @file{/usr/include/asm} into the
+development kernel sources. You can then configure glibc with no
+special options. This tactic is recommended if you are upgrading from
+libc5, since you need to get rid of the old header files anyway.
+
+Note that @file{/usr/include/net} and @file{/usr/include/scsi} should
+@strong{not} be symlinks into the kernel sources. GNU libc provides its
+own versions of these files.
+
+Linux expects some components of the libc installation to be in
+@file{/lib} and some in @file{/usr/lib}. This is handled automatically
+if you configure glibc with @samp{--prefix=/usr}. If you set some other
+prefix or allow it to default to @file{/usr/local}, then all the
+components are installed there.
+
+If you are upgrading from libc5, you need to recompile every shared
+library on your system against the new library for the sake of new code,
+but keep the old libraries around for old binaries to use. This is
+complicated and difficult. Consult the Glibc2 HOWTO at
+@url{http://www.imaxx.net/~thrytis/glibc} for details.
+
+You cannot use @code{nscd} with 2.0 kernels, due to bugs in the
+kernel-side thread support. @code{nscd} happens to hit these bugs
+particularly hard, but you might have problems with any threaded
+program.
@node Reporting Bugs
@appendixsec Reporting Bugs
@@ -385,7 +462,13 @@ 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.
+is probably wrong. It might not be the GNU library. Many historical
+Unix C libraries permit things that we don't, such as closing a file
+twice.
+
+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!
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
@@ -393,22 +476,14 @@ 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
+Do this using the @code{glibcbug} script. It is installed with libc, or
+if you haven't installed it, will be in your build directory. Send your
+test case, the results you got, the results you expected, and what you
+think the problem might be (if you've thought of anything).
+@code{glibcbug} will insert the configuration information we need to
+see, and ship the report off to @email{bug-glibc@@gnu.org}. Don't send
+a message there directly; it is fed to a program that expects mail to be
+formatted in a particular way. Use the script.
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