diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 218 |
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 |