about summary refs log tree commit diff
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL')
-rw-r--r--INSTALL218
1 files changed, 146 insertions, 72 deletions
diff --git a/INSTALL b/INSTALL
index cb6cb51080..410c21cb68 100644
--- a/INSTALL
+++ b/INSTALL
@@ -6,19 +6,23 @@ 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 "add-on" bundles
-separate from the main distribution.  Unless you are doing an unusual
-installation, you should get them both.  Support for the `crypt'
-function is distributed separately because of US export restrictions.
-If you are outside the US or Canada, you must get `crypt' support from
-a site outside the US, such as `ftp.ifi.uio.no'.  (Most non-US mirrors
-of `ftp.gnu.org' will have it too.)  The file you need is
-`glibc-crypt-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
-`glibc-linuxthreads-VERSION.tar.gz'.  Both add-on bundles should be
-unpacked into the top level of the libc source tree.
+   Features can be added to GNU Libc via "add-on" bundles.  These are
+separate tarfiles which you unpack into the top level of the source
+tree.  Then you give `configure' the `--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 `glibc-linuxthreads-VERSION.tar.gz'.  Support for
+the `crypt' function is distributed separately because of United States
+export restrictions.  If you are outside the US or Canada, you must get
+`crypt' support from a site outside the US, such as `ftp.ifi.uio.no'.
+(Most non-US mirrors of `ftp.gnu.org' will have it too.)  The file you
+need is `glibc-crypt-VERSION.tar.gz'.
 
    You will need recent versions of several GNU tools: definitely GCC
 and GNU Make, and possibly others.  *Note Tools for Compilation::,
@@ -39,14 +43,12 @@ at the top level of the source tree.  In the scenario above, you'd type
      $ ../glibc-2.1.0/configure ARGS...
 
 `configure' takes many options, but you can get away with knowing only
-two: `--enable-add-ons' and `--prefix'.  The `--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 `--prefix' option tells configure
-where you want glibc installed.  This defaults to `/usr/local'.  If you
-are installing glibc as your primary C library, give the option
-`--prefix=/usr', which will put components in `/usr' or `/' as
-appropriate.
+two: `--prefix' and `--enable-add-ons'.  The `--prefix' option tells
+configure where you want glibc installed.  This defaults to
+`/usr/local'.  The `--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 CC and CFLAGS variables in the
 environment when running `configure'.  CC selects the C compiler that
@@ -137,9 +139,16 @@ will be used, and CFLAGS sets optimization options for the compiler.
      too, and you may have to override CONFIGURE's selection of the
      compiler and/or binutils.
 
-     If you give just one of these, `configure' will get confused.  If
-     `configure' doesn't correctly guess your system type for a native
-     build, report that as a bug.
+     If you give just `--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 `i586-pc-linux-gnu' but you
+     want to compile a library optimized for 386es, give
+     `--host=i386-pc-linux-gnu' or just `--host=i386-linux'.  (A
+     library compiled for a Pentium (`i586') will still work on a 386,
+     but it may be slower.)
+
+     If you give just `--build', configure will get confused.
 
    To build the library and related programs, type `make'.  This will
 produce a lot of output, some of which may look like errors from `make'
@@ -170,15 +179,57 @@ the tests assume they are not being run by `root'.  We recommend you
 compile and test glibc as an unprivileged user.
 
    To format the `GNU C Library Reference Manual' for printing, type
-`make dvi'.  You need a working TeX installation to do this.
+`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 `make info', but
+it shouldn't be necessary.
+
+Installing the C Library
+========================
 
    To install the library and its header files, and the Info files of
 the manual, type `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 `install_root' on the command line.
-This is useful to create chroot'ed environment or to prepare binary
-releases.
+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, `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
+`/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
+(`-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
+(`/usr/lib/gcc-lib/TARGET/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 `install_root' variable on the command line for
+`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, `nscd' and `utmpd', which you may or
+may not want to run.  `nscd' caches name service lookups; it can
+dramatically improve performance with NIS+, and may help with DNS as
+well.  `utmpd' allows programs that use the old format for the `utmp'
+file to coexist with new programs.  For more information see the files
+`nscd/README' and `login/README.utmpd'.
+
+   One auxiliary program, `/usr/libexec/pt_chown', is installed setuid
+`root'.  This program is invoked by the `grantpt' function; it sets the
+permissions on a pseudoterminal so it can be used by the calling
+process.  This means programs like `xterm' and `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 `devptsfs'
+or `devfs' filesystems providing pty slaves, you don't need this
+program; otherwise you do.  The source for `pt_chown' is in
+`login/programs/pt_chown.c'.
 
 Recommended Tools for Compilation
 =================================
@@ -202,7 +253,9 @@ build the GNU C library:
      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.
+     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.)
 
    * GNU `binutils' 2.8.1.0.23, 2.9.1, or 2.9.0.15
 
@@ -220,19 +273,13 @@ build the GNU C library:
      To correctly translate and install the Texinfo documentation you
      need this version of the `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
+     installation mechanism for the info files is not present or works
      differently.
 
-     On some Debian Linux based systems the `install-info' program
-     supplied with the system works differently from the one we expect.
-     You must therefore run `make install' like this:
-
-          make INSTALL_INFO=/path/to/GNU/install-info install
-
    * GNU `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
+     should work with any POSIX-compliant awk implementation; `gawk'
      3.0 and `mawk' 1.3 are known to work.
 
    * Perl 5
@@ -302,23 +349,51 @@ maintainers by sending electronic mail to <bug-glibc@gnu.org>.
    Each case of `iX86' can be `i386', `i486', `i586', or `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.)
-
-     decstation
-     hp320-bsd4.3 hp300bsd
-     i486-gnu
-     i586-linux
-     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
+but will not use instructions not available on all of them.  If you
+want the library to use instructions only available on newer
+processors, give GCC the appropriate `-m' switches via CFLAGS.
+
+Specific advice for Linux systems
+=================================
+
+   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 `/usr/src/linux-dev'.  In that
+directory, run `make config' and accept all the defaults.  Then
+configure glibc with the option
+`--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
+`make config' as above.  Then rename or delete `/usr/include', create a
+new `/usr/include', and make the usual symbolic links of
+`/usr/include/linux' and `/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 `/usr/include/net' and `/usr/include/scsi' should *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
+`/lib' and some in `/usr/lib'.  This is handled automatically if you
+configure glibc with `--prefix=/usr'.  If you set some other prefix or
+allow it to default to `/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
+`http://www.imaxx.net/~thrytis/glibc' for details.
+
+   You cannot use `nscd' with 2.0 kernels, due to bugs in the
+kernel-side thread support.  `nscd' happens to hit these bugs
+particularly hard, but you might have problems with any threaded
+program.
 
 Reporting Bugs
 ==============
@@ -333,7 +408,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 (*note 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
@@ -341,21 +422,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 `config.status'
-and `config.make' which are created by running `configure'; they will
-be in whatever directory was current when you ran `configure'.
-
-   If you think you have found some way in which the GNU C library does
-not conform to the ISO and POSIX standards (*note Standards and
-Portability::.), that is definitely a bug.  Report it!
-
-   Send bug reports to the Internet address <bug-glibc@gnu.org> using
-the `glibcbug' script which is installed by the GNU C library.  If you
-have other problems with installation or use, please report those as
-well.
+Do this using the `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).  `glibcbug'
+will insert the configuration information we need to see, and ship the
+report off to <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