diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/Makefile | 2 | ||||
| -rw-r--r-- | manual/install.texi | 227 | ||||
| -rw-r--r-- | manual/libc.texinfo | 2 |
3 files changed, 153 insertions, 78 deletions
diff --git a/manual/Makefile b/manual/Makefile index 5db6a31f23..0652d4dea0 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -82,7 +82,7 @@ stamp-summary: summary.awk $(filter-out summary.texi, $(texis)) # access to the documentation of the function, variables, and other # definitions. dir-add.info: xtract-typefun.awk $(texis) - (echo "INFO-DIR-SECTION GNU C library functions:"; \ + (echo "INFO-DIR-SECTION GNU C library functions"; \ echo "START-INFO-DIR-ENTRY"; \ $(AWK) -f $^ | sort; \ echo "END-INFO-DIR-ENTRY") > $@.new diff --git a/manual/install.texi b/manual/install.texi index 3712643989..a68151852e 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 diff --git a/manual/libc.texinfo b/manual/libc.texinfo index b9d3d7a6d9..0beec66fd6 100644 --- a/manual/libc.texinfo +++ b/manual/libc.texinfo @@ -5,7 +5,7 @@ @setchapternewpage odd @comment Tell install-info what to do. -@dircategory GNU libraries: +@dircategory GNU libraries @direntry * Libc: (libc). C library. @end direntry |