summaryrefslogtreecommitdiff
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