| Installing the GNU C Library |
| **************************** |
| |
| Installation of the GNU C library is relatively simple, but usually |
| requires several GNU tools to be installed already. |
| |
| Before you do anything else, you should read the file `FAQ' found 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. |
| |
| To configure the GNU C library for your system, run the shell script |
| `configure' with `sh'. You might use an argument which is the |
| conventional GNU name for your system configuration--for example, |
| `i486-pc-linux-gnu', for Linux running on i486. *Note Installation: |
| (gcc.info)Installation, for a full description of standard GNU |
| configuration names. If you omit the configuration name, `configure' |
| will try to guess one for you by inspecting the system it is running |
| on. It may or may not be able to come up with a guess, and the guess |
| might be wrong. `configure' will tell you the canonical name of the |
| chosen configuration before proceeding. |
| |
| Here are some options that you should specify (if appropriate) when |
| you run `configure': |
| |
| `--with-binutils=DIRECTORY' |
| Use the binutils (assembler and linker) in `DIRECTORY', not the |
| ones the C compiler would default to. You could use this option if |
| the default binutils on your system cannot deal with all the |
| constructs in the GNU C library. (`configure' will detect the |
| problem and 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.) |
| |
| `--without-fp' |
| `--nfp' |
| Use this option if your computer lacks hardware floating-point |
| support and your operating system does not emulate an FPU. |
| |
| `--prefix=DIRECTORY' |
| Install machine-independent data files in subdirectories of |
| `DIRECTORY'. (You can also set this in `configparms'; see below.) |
| The default is to install in `/usr/local'. |
| |
| `--exec-prefix=DIRECTORY' |
| Install the library and other machine-dependent files in |
| subdirectories of `DIRECTORY'. (You can also set this in |
| `configparms'; see below.) The default is to use <prefix>/bin and |
| <prefix>/sbin. |
| |
| `--enable-shared' |
| `--disable-shared' |
| Enable or disable building of an ELF shared library on systems that |
| support it. The default is to build the shared library on systems |
| using ELF when the GNU `binutils' are available. |
| |
| `--enable-profile' |
| `--disable-profile' |
| Enable or disable building of the profiled C library, `-lc_p'. The |
| default is to build the profiled library. You may wish to disable |
| it if you don't plan to do profiling, because it doubles the build |
| time of compiling just the unprofiled static library. |
| |
| `--enable-omitfp' |
| Enable building a highly-optimized but possibly undebuggable C |
| library. This causes the normal static and shared (if enabled) C |
| libraries to be compiled with maximal optimization, including the |
| `-fomit-frame-pointer' switch that makes debugging impossible on |
| many machines, and without debugging information (which makes the |
| binaries substantially smaller). An additional static library is |
| compiled with no optimization and full debugging information, and |
| installed as `-lc_g'. |
| |
| `--enable-add-ons[=LIST]' |
| Certain components of the C library are distributed separately |
| from the rest of the sources. In particular, the `crypt' function |
| and its friends are separated due to US export control |
| regulations, and the threading support code for Linux is |
| maintained separately. You can get these "add-on" packages from |
| the same place you got the libc sources. To use them, unpack them |
| into your source tree, and give `configure' the `--enable-add-ons' |
| option. |
| |
| If you do not wish to use some add-on package that you have |
| present in your source tree, give this option a list of the |
| add-ons that you *do* want used, like this: |
| `--enable-add-ons=crypt,linuxthreads' |
| |
| `--with-headers=DIRECTORY' |
| Search only DIRECTORY and the C compiler's private directory for |
| header files not found in the libc sources. `/usr/include' will |
| not be searched if this option is given. On Linux, DIRECTORY |
| should be the kernel's private include directory (usually |
| `/usr/src/linux/include'). |
| |
| This option is primarily of use on a system where the headers in |
| `/usr/include' come from an older version of glibc. Conflicts can |
| occasionally happen in this case. Note that Linux libc5 qualifies |
| as an older version of glibc. You can also use this option if you |
| want to compile glibc with a newer set of kernel headers than the |
| ones found in `/usr/include'. |
| |
| You should not build the library in the same directory as the |
| sources, because there are bugs in `make clean'. Make a directory for |
| the build, and run `configure' from that directory, like this: |
| |
| mkdir linux |
| cd linux |
| ../configure |
| |
| `configure' looks for the sources in whatever directory you specified |
| for finding `configure' itself. It does not matter where in the file |
| system the source and build directories are--as long as you specify the |
| source directory when you run `configure', you will get the proper |
| results. |
| |
| This feature lets you keep sources and binaries in different |
| directories, and that makes it easy to build the library for several |
| different machines from the same set of sources. Simply create a build |
| directory for each target machine, and run `configure' in that |
| directory specifying the target machine's configuration name. |
| |
| The library has a number of special-purpose configuration parameters. |
| These are defined in the file `configparms'; see the comments in that |
| file for the details. To change them, copy `configparms' into your |
| build directory and modify it as appropriate for your system. |
| `configure' will not notice your modifications if you change the file |
| in the source directory. |
| |
| It is easy to configure the GNU C library for cross-compilation by |
| setting a few variables in `configparms'. Set `CC' to the |
| cross-compiler for the target you configured the library for; it is |
| important to use this same `CC' value when running `configure', like |
| this: `CC=TARGET-gcc configure TARGET'. Set `BUILD_CC' to the compiler |
| to use for for programs run on the build system as part of compiling |
| the library. You may need to set `AR' and `RANLIB' to cross-compiling |
| versions of `ar' and `ranlib' if the native tools are not configured to |
| work with object files for the target you configured for. |
| |
| Some of the machine-dependent code for some machines uses extensions |
| in the GNU C compiler, so you may need to compile the library with GCC. |
| (In fact, all of the existing complete ports require GCC.) |
| |
| 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' |
| (but isn't). Look for error messages from `make' containing `***'. |
| Those indicate that something is really wrong. |
| |
| The compilation process takes several hours even on fast hardware; |
| expect at least two hours for the default configuration on i586 for |
| Linux. For Hurd times are much longer. All current releases of GCC |
| have a problem which causes them to take several minutes to compile |
| certain files in the iconvdata directory. Do not panic if the compiler |
| appears to hang. |
| |
| To build and run some test programs which exercise some of the |
| library facilities, type `make check'. This will produce several files |
| with names like `PROGRAM.out'. |
| |
| To format the `GNU C Library Reference Manual' for printing, type |
| `make dvi'. You need a working TeX installation to do this. |
| |
| 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. |
| |
| For now (in this alpha version, and at least on RedHat Linux), if you |
| are trying to install this as your default libraries, a different |
| installation method is recommended. Move `/usr/include' out of the |
| way, create a new `/usr/include' directory (don't forget the symlinks |
| `/usr/include/asm' and `/usr/include/linux', that should point to |
| `/usr/src/linux/include/asm' and `/usr/src/linux/include/linux' -or |
| wherever you keep your kernel sources-respectively), build normally and |
| install into somewhere else via `install_root'. Then move your |
| `/usr/include' back, and copy the newly created stuff by hand over the |
| old. Remember to copy programs and shared libraries into `FILENAME.new' |
| and then move `FILENAME.new' to `FILENAME', as the files might be in |
| use. You will have to `ranlib' your copies of the static libraries |
| `/usr/lib/libNAME.a'. You will see that `libbsd-compat.a', `libieee.a', |
| and `libmcheck.a' are just object files, not archives. This is normal. |
| Copy the new header files over the old ones by something like |
| `cd /usr; (cd INSTALL_ROOT; tar cf - include) | tar xf -'. |
| |
| Recommended Tools to Install the GNU C Library |
| ============================================== |
| |
| We recommend installing the following GNU tools before attempting to |
| build the GNU C library: |
| |
| * GNU `make' 3.75 |
| |
| You need the latest version of GNU `make'. Modifying the GNU C |
| Library to work with other `make' programs would be so hard that we |
| recommend you port GNU `make' instead. *Really.* We recommend |
| version GNU `make' version 3.75. Versions 3.76 and 3.76.1 are |
| known to have bugs which only show up in big projects like GNU |
| `libc'. |
| |
| * GCC 2.8.1/EGCS 1.0.2 |
| |
| On most platforms, the GNU C library can only be compiled with the |
| GNU C compiler family. We recommend GCC version 2.8.1 and EGCS |
| version 1.0.2 or later versions of these two; earlier versions may |
| have problems. |
| |
| * GNU `binutils' 2.8.1.0.23 |
| |
| Using the GNU `binutils' (assembler, linker, and related tools) is |
| preferable when possible, and they are required to build an ELF |
| shared C library. Version 2.1 of the library uses ELF symbol |
| versioning extensively. Support for this feature is incomplete or |
| buggy before binutils 2.8.1.0.23, so you must use at least this |
| version. |
| |
| * GNU `texinfo' 3.11 |
| |
| 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 |
| 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 |
| |
| Several files used during the build are generated using features |
| of GNU `awk' that are not found in other implementations. |
| |
| If you change any of the `configure.in' files you will also need |
| |
| * GNU `autoconf' 2.12 |
| |
| and if you change any of the message translation files you will need |
| |
| * GNU `gettext' 0.10 or later |
| |
| You may also need these packages if you upgrade your source tree using |
| patches, although we try to avoid this. |
| |
| Supported Configurations |
| ======================== |
| |
| The GNU C Library currently supports configurations that match the |
| following patterns: |
| |
| alpha-ANYTHING-linux |
| arm-ANYTHING-linuxaout |
| arm-ANYTHING-none |
| iX86-ANYTHING-gnu |
| iX86-ANYTHING-linux |
| m68k-ANYTHING-linux |
| powerpc-ANYTHING-linux |
| sparc-ANYTHING-linux |
| sparc64-ANYTHING-linux |
| |
| Former releases of this library (version 1.09.1 and perhaps earlier |
| versions) used to run on the following configurations: |
| |
| alpha-dec-osf1 |
| alpha-ANYTHING-linuxecoff |
| iX86-ANYTHING-bsd4.3 |
| iX86-ANYTHING-isc2.2 |
| iX86-ANYTHING-isc3.N |
| iX86-ANYTHING-sco3.2 |
| iX86-ANYTHING-sco3.2v4 |
| iX86-ANYTHING-sysv |
| iX86-ANYTHING-sysv4 |
| iX86-force_cpu386-none |
| iX86-sequent-bsd |
| i960-nindy960-none |
| m68k-hp-bsd4.3 |
| m68k-mvme135-none |
| m68k-mvme136-none |
| m68k-sony-newsos3 |
| m68k-sony-newsos4 |
| m68k-sun-sunos4.N |
| mips-dec-ultrix4.N |
| mips-sgi-irix4.N |
| sparc-sun-solaris2.N |
| sparc-sun-sunos4.N |
| |
| Since no one has volunteered to test and fix these configurations, |
| they are not supported at the moment. They probably don't compile; |
| they definitely don't work anymore. Porting the library is not hard. |
| If you are interested in doing a port, please contact the glibc |
| 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 |
| |
| Useful hints for the installation |
| ================================= |
| |
| There are a some more or less obvious methods one should know when |
| compiling GNU libc: |
| |
| * Better never compile in the source directory. Create a new |
| directory and run the `configure' from there. Everything should |
| happen automagically. |
| |
| * You can use the `-j' option of GNU make by changing the line |
| specifying `PARALLELMAKE' in the Makefile generated during the |
| configuration. |
| |
| It is not useful to start the `make' process using the `-j' option |
| since this option is not propagated down to the sub-`make's. |
| |
| * If you made some changes after a complete build and only want to |
| check these changes run `make' while specifying the list of |
| subdirs it has to visit. |
| |
| make subdirs="nss elf" |
| |
| The above build run will only visit the subdirectories `nss' and |
| `elf'. Beside this it updates the `libc' files itself. |
| |
| Reporting Bugs |
| ============== |
| |
| There are probably bugs in the GNU C library. There are certainly |
| errors and omissions in this manual. If you report them, they will get |
| fixed. If you don't, no one will ever know about them and they will |
| remain unfixed for all eternity, if not longer. |
| |
| To report a bug, first you must find it. Hopefully, this will be the |
| 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. |
| |
| 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 |
| 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. |
| |
| 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 |
| function's behavior disagrees with the manual, then either the library |
| or the manual has a bug, so report the disagreement. If you find any |
| errors or omissions in this manual, please report them to the Internet |
| address <bug-glibc-manual@gnu.org>. If you refer to specific sections |
| when reporting on the manual, please include the section names for |
| easier identification. |
| |