1: Installing the GNU C Library
    2: ****************************
    3: 
    4: Before you do anything else, you should read the file `FAQ' located at
    5: the top level of the source tree.  This file answers common questions
    6: and describes problems you may experience with compilation and
    7: installation.  It is updated more frequently than this manual.
    8: 
    9:    Features can be added to GNU Libc via "add-on" bundles.  These are
   10: separate tar files, which you unpack into the top level of the source
   11: tree.  Then you give `configure' the `--enable-add-ons' option to
   12: activate them, and they will be compiled into the library.
   13: 
   14:    You will need recent versions of several GNU tools: definitely GCC
   15: and GNU Make, and possibly others.  *Note Tools for Compilation::,
   16: below.
   17: 
   18: Configuring and compiling GNU Libc
   19: ==================================
   20: 
   21: GNU libc cannot be compiled in the source directory.  You must build it
   22: in a separate build directory.  For example, if you have unpacked the
   23: glibc sources in `/src/gnu/glibc-2.4', create a directory
   24: `/src/gnu/glibc-build' to put the object files in.  This allows
   25: removing the whole build directory in case an error occurs, which is
   26: the safest way to get a fresh start and should always be done.
   27: 
   28:    From your object directory, run the shell script `configure' located
   29: at the top level of the source tree.  In the scenario above, you'd type
   30: 
   31:      $ ../glibc-2.4/configure ARGS...
   32: 
   33:    Please note that even though you're building in a separate build
   34: directory, the compilation needs to modify a few files in the source
   35: directory, especially some files in the manual subdirectory.
   36: 
   37: `configure' takes many options, but the only one that is usually
   38: mandatory is `--prefix'.  This option tells `configure' where you want
   39: glibc installed.  This defaults to `/usr/local', but the normal setting
   40: to install as the standard system library is `--prefix=/usr' for
   41: GNU/Linux systems and `--prefix=' (an empty prefix) for GNU/Hurd
   42: systems.
   43: 
   44:    It may also be useful to set the CC and CFLAGS variables in the
   45: environment when running `configure'.  CC selects the C compiler that
   46: will be used, and CFLAGS sets optimization options for the compiler.
   47: 
   48:    The following list describes all of the available options for
   49: `configure':
   50: 
   51: `--prefix=DIRECTORY'
   52:      Install machine-independent data files in subdirectories of
   53:      `DIRECTORY'.  The default is to install in `/usr/local'.
   54: 
   55: `--exec-prefix=DIRECTORY'
   56:      Install the library and other machine-dependent files in
   57:      subdirectories of `DIRECTORY'.  The default is to the `--prefix'
   58:      directory if that option is specified, or `/usr/local' otherwise.
   59: 
   60: `--with-headers=DIRECTORY'
   61:      Look for kernel header files in DIRECTORY, not `/usr/include'.
   62:      Glibc needs information from the kernel's private header files.
   63:      Glibc will normally look in `/usr/include' for them, but if you
   64:      specify this option, it will look in DIRECTORY instead.
   65: 
   66:      This option is primarily of use on a system where the headers in
   67:      `/usr/include' come from an older version of glibc.  Conflicts can
   68:      occasionally happen in this case.  Note that Linux libc5 qualifies
   69:      as an older version of glibc.  You can also use this option if you
   70:      want to compile glibc with a newer set of kernel headers than the
   71:      ones found in `/usr/include'.
   72: 
   73: `--enable-add-ons[=LIST]'
   74:      Specify add-on packages to include in the build.  If this option is
   75:      specified with no list, it enables all the add-on packages it
   76:      finds in the main source directory; this is the default behavior.
   77:      You may specify an explicit list of add-ons to use in LIST,
   78:      separated by spaces or commas (if you use spaces, remember to
   79:      quote them from the shell).  Each add-on in LIST can be an
   80:      absolute directory name or can be a directory name relative to the
   81:      main source directory, or relative to the build directory (that
   82:      is, the current working directory).  For example,
   83:      `--enable-add-ons=nptl,../glibc-libidn-2.4'.
   84: 
   85: `--enable-kernel=VERSION'
   86:      This option is currently only useful on GNU/Linux systems.  The
   87:      VERSION parameter should have the form X.Y.Z and describes the
   88:      smallest version of the Linux kernel the generated library is
   89:      expected to support.  The higher the VERSION number is, the less
   90:      compatibility code is added, and the faster the code gets.
   91: 
   92: `--with-binutils=DIRECTORY'
   93:      Use the binutils (assembler and linker) in `DIRECTORY', not the
   94:      ones the C compiler would default to.  You can use this option if
   95:      the default binutils on your system cannot deal with all the
   96:      constructs in the GNU C library.  In that case, `configure' will
   97:      detect the problem and suppress these constructs, so that the
   98:      library will still be usable, but functionality may be lost--for
   99:      example, you can't build a shared libc with old binutils.
  100: 
  101: `--without-fp'
  102:      Use this option if your computer lacks hardware floating-point
  103:      support and your operating system does not emulate an FPU.
  104: 
  105:      these
  106: 
  107: `--disable-shared'
  108:      Don't build shared libraries even if it is possible.  Not all
  109:      systems support shared libraries; you need ELF support and
  110:      (currently) the GNU linker.
  111: 
  112: `--disable-profile'
  113:      Don't build libraries with profiling information.  You may want to
  114:      use this option if you don't plan to do profiling.
  115: 
  116: `--enable-omitfp'
  117:      Use maximum optimization for the normal (static and shared)
  118:      libraries, and compile separate static libraries with debugging
  119:      information and no optimization.  We recommend not doing this.
  120:      The extra optimization doesn't gain you much, it may provoke
  121:      compiler bugs, and you won't be able to trace bugs through the C
  122:      library.
  123: 
  124: `--disable-versioning'
  125:      Don't compile the shared libraries with symbol version information.
  126:      Doing this will make the resulting library incompatible with old
  127:      binaries, so it's not recommended.
  128: 
  129: `--enable-static-nss'
  130:      Compile static versions of the NSS (Name Service Switch) libraries.
  131:      This is not recommended because it defeats the purpose of NSS; a
  132:      program linked statically with the NSS libraries cannot be
  133:      dynamically reconfigured to use a different name database.
  134: 
  135: `--without-tls'
  136:      By default the C library is built with support for thread-local
  137:      storage if the used tools support it.  By using `--without-tls'
  138:      this can be prevented though there generally is no reason since it
  139:      creates compatibility problems.
  140: 
  141: `--build=BUILD-SYSTEM'
  142: `--host=HOST-SYSTEM'
  143:      These options are for cross-compiling.  If you specify both
  144:      options and BUILD-SYSTEM is different from HOST-SYSTEM, `configure'
  145:      will prepare to cross-compile glibc from BUILD-SYSTEM to be used
  146:      on HOST-SYSTEM.  You'll probably need the `--with-headers' option
  147:      too, and you may have to override CONFIGURE's selection of the
  148:      compiler and/or binutils.
  149: 
  150:      If you only specify `--host', `configure' will prepare for a
  151:      native compile but use what you specify instead of guessing what
  152:      your system is. This is most useful to change the CPU submodel.
  153:      For example, if `configure' guesses your machine as
  154:      `i586-pc-linux-gnu' but you want to compile a library for 386es,
  155:      give `--host=i386-pc-linux-gnu' or just `--host=i386-linux' and add
  156:      the appropriate compiler flags (`-mcpu=i386' will do the trick) to
  157:      CFLAGS.
  158: 
  159:      If you specify just `--build', `configure' will get confused.
  160: 
  161:    To build the library and related programs, type `make'.  This will
  162: produce a lot of output, some of which may look like errors from `make'
  163: but isn't.  Look for error messages from `make' containing `***'.
  164: Those indicate that something is seriously wrong.
  165: 
  166:    The compilation process can take a long time, depending on the
  167: configuration and the speed of your machine.  Some complex modules may
  168: take a very long time to compile, as much as several minutes on slower
  169: machines.  Do not panic if the compiler appears to hang.
  170: 
  171:    If you want to run a parallel make, simply pass the `-j' option with
  172: an appropriate numeric parameter to `make'.  You need a recent GNU
  173: `make' version, though.
  174: 
  175:    To build and run test programs which exercise some of the library
  176: facilities, type `make check'.  If it does not complete successfully,
  177: do not use the built library, and report a bug after verifying that the
  178: problem is not already known.  *Note Reporting Bugs::, for instructions
  179: on reporting bugs.  Note that some of the tests assume they are not
  180: being run by `root'.  We recommend you compile and test glibc as an
  181: unprivileged user.
  182: 
  183:    Before reporting bugs make sure there is no problem with your system.
  184: The tests (and later installation) use some pre-existing files of the
  185: system such as `/etc/passwd', `/etc/nsswitch.conf' and others.  These
  186: files must all contain correct and sensible content.
  187: 
  188:    To format the `GNU C Library Reference Manual' for printing, type
  189: `make dvi'.  You need a working TeX installation to do this.  The
  190: distribution already includes the on-line formatted version of the
  191: manual, as Info files.  You can regenerate those with `make info', but
  192: it shouldn't be necessary.
  193: 
  194:    The library has a number of special-purpose configuration parameters
  195: which you can find in `Makeconfig'.  These can be overwritten with the
  196: file `configparms'.  To change them, create a `configparms' in your
  197: build directory and add values as appropriate for your system.  The
  198: file is included and parsed by `make' and has to follow the conventions
  199: for makefiles.
  200: 
  201:    It is easy to configure the GNU C library for cross-compilation by
  202: setting a few variables in `configparms'.  Set `CC' to the
  203: cross-compiler for the target you configured the library for; it is
  204: important to use this same `CC' value when running `configure', like
  205: this: `CC=TARGET-gcc configure TARGET'.  Set `BUILD_CC' to the compiler
  206: to use for programs run on the build system as part of compiling the
  207: library.  You may need to set `AR' and `RANLIB' to cross-compiling
  208: versions of `ar' and `ranlib' if the native tools are not configured to
  209: work with object files for the target you configured for.
  210: 
  211: Installing the C Library
  212: ========================
  213: 
  214: To install the library and its header files, and the Info files of the
  215: manual, type `env LANGUAGE=C LC_ALL=C make install'.  This will build
  216: things, if necessary, before installing them; however, you should still
  217: compile everything first.  If you are installing glibc as your primary
  218: C library, we recommend that you shut the system down to single-user
  219: mode first, and reboot afterward.  This minimizes the risk of breaking
  220: things when the library changes out from underneath.
  221: 
  222:    If you're upgrading from Linux libc5 or some other C library, you
  223: need to replace the `/usr/include' with a fresh directory before
  224: installing it.  The new `/usr/include' should contain the Linux
  225: headers, but nothing else.
  226: 
  227:    You must first build the library (`make'), optionally check it
  228: (`make check'), switch the include directories and then install (`make
  229: install').  The steps must be done in this order.  Not moving the
  230: directory before install will result in an unusable mixture of header
  231: files from both libraries, but configuring, building, and checking the
  232: library requires the ability to compile and run programs against the old
  233: library.
  234: 
  235:    If you are upgrading from a previous installation of glibc 2.0 or
  236: 2.1, `make install' will do the entire job.  You do not need to remove
  237: the old includes - if you want to do so anyway you must then follow the
  238: order given above.
  239: 
  240:    You may also need to reconfigure GCC to work with the new library.
  241: The easiest way to do that is to figure out the compiler switches to
  242: make it work again (`-Wl,--dynamic-linker=/lib/ld-linux.so.2' should
  243: work on GNU/Linux systems) and use them to recompile gcc.  You can also
  244: edit the specs file (`/usr/lib/gcc-lib/TARGET/VERSION/specs'), but that
  245: is a bit of a black art.
  246: 
  247:    You can install glibc somewhere other than where you configured it
  248: to go by setting the `install_root' variable on the command line for
  249: `make install'.  The value of this variable is prepended to all the
  250: paths for installation.  This is useful when setting up a chroot
  251: environment or preparing a binary distribution.  The directory should be
  252: specified with an absolute file name.
  253: 
  254:    Glibc 2.2 includes a daemon called `nscd', which you may or may not
  255: want to run.  `nscd' caches name service lookups; it can dramatically
  256: improve performance with NIS+, and may help with DNS as well.
  257: 
  258:    One auxiliary program, `/usr/libexec/pt_chown', is installed setuid
  259: `root'.  This program is invoked by the `grantpt' function; it sets the
  260: permissions on a pseudoterminal so it can be used by the calling
  261: process.  This means programs like `xterm' and `screen' do not have to
  262: be setuid to get a pty.  (There may be other reasons why they need
  263: privileges.)  If you are using a 2.1 or newer Linux kernel with the
  264: `devptsfs' or `devfs' filesystems providing pty slaves, you don't need
  265: this program; otherwise you do.  The source for `pt_chown' is in
  266: `login/programs/pt_chown.c'.
  267: 
  268:    After installation you might want to configure the timezone and
  269: locale installation of your system.  The GNU C library comes with a
  270: locale database which gets configured with `localedef'.  For example, to
  271: set up a German locale with name `de_DE', simply issue the command
  272: `localedef -i de_DE -f ISO-8859-1 de_DE'.  To configure all locales
  273: that are supported by glibc, you can issue from your build directory the
  274: command `make localedata/install-locales'.
  275: 
  276:    To configure the locally used timezone, set the `TZ' environment
  277: variable.  The script `tzselect' helps you to select the right value.
  278: As an example, for Germany, `tzselect' would tell you to use
  279: `TZ='Europe/Berlin''.  For a system wide installation (the given paths
  280: are for an installation with `--prefix=/usr'), link the timezone file
  281: which is in `/usr/share/zoneinfo' to the file `/etc/localtime'.  For
  282: Germany, you might execute `ln -s /usr/share/zoneinfo/Europe/Berlin
  283: /etc/localtime'.
  284: 
  285: Recommended Tools for Compilation
  286: =================================
  287: 
  288: We recommend installing the following GNU tools before attempting to
  289: build the GNU C library:
  290: 
  291:    * GNU `make' 3.79 or newer
  292: 
  293:      You need the latest version of GNU `make'.  Modifying the GNU C
  294:      Library to work with other `make' programs would be so difficult
  295:      that we recommend you port GNU `make' instead.  *Really.*  We
  296:      recommend GNU `make' version 3.79.  All earlier versions have
  297:      severe bugs or lack features.
  298: 
  299:    * GCC 3.4 or newer, GCC 4.1 recommended
  300: 
  301:      The GNU C library can only be compiled with the GNU C compiler
  302:      family.  For the 2.3 releases, GCC 3.2 or higher is required; GCC
  303:      3.4 is the compiler we advise to use for 2.3 versions.  For the
  304:      2.4 release, GCC 3.4 or higher is required; as of this writing,
  305:      GCC 4.1 is the compiler we advise to use for current versions.  On
  306:      certain machines including `powerpc64', compilers prior to GCC 4.0
  307:      have bugs that prevent them compiling the C library code in the
  308:      2.4 release.  On other machines, GCC 4.1 is required to build the C
  309:      library with support for the correct `long double' type format;
  310:      these include `powerpc' (32 bit), `s390' and `s390x'.
  311: 
  312:      You can use whatever compiler you like to compile programs that
  313:      use GNU libc, but be aware that both GCC 2.7 and 2.8 have bugs in
  314:      their floating-point support that may be triggered by the math
  315:      library.
  316: 
  317:      Check the FAQ for any special compiler issues on particular
  318:      platforms.
  319: 
  320:    * GNU `binutils' 2.15 or later
  321: 
  322:      You must use GNU `binutils' (as and ld) to build the GNU C library.
  323:      No other assembler or linker has the necessary functionality at the
  324:      moment.
  325: 
  326:    * GNU `texinfo' 3.12f
  327: 
  328:      To correctly translate and install the Texinfo documentation you
  329:      need this version of the `texinfo' package.  Earlier versions do
  330:      not understand all the tags used in the document, and the
  331:      installation mechanism for the info files is not present or works
  332:      differently.
  333: 
  334:    * GNU `awk' 3.0, or higher
  335: 
  336:      `Awk' is used in several places to generate files.  `gawk' 3.0 is
  337:      known to work.
  338: 
  339:    * Perl 5
  340: 
  341:      Perl is not required, but it is used if present to test the
  342:      installation.  We may decide to use it elsewhere in the future.
  343: 
  344:    * GNU `sed' 3.02 or newer
  345: 
  346:      `Sed' is used in several places to generate files.  Most scripts
  347:      work with any version of `sed'.  The known exception is the script
  348:      `po2test.sed' in the `intl' subdirectory which is used to generate
  349:      `msgs.h' for the test suite.  This script works correctly only
  350:      with GNU `sed' 3.02.  If you like to run the test suite, you
  351:      should definitely upgrade `sed'.
  352: 
  353: 
  354: If you change any of the `configure.in' files you will also need
  355: 
  356:    * GNU `autoconf' 2.53 or higher
  357: 
  358: and if you change any of the message translation files you will need
  359: 
  360:    * GNU `gettext' 0.10.36 or later
  361: 
  362: You may also need these packages if you upgrade your source tree using
  363: patches, although we try to avoid this.
  364: 
  365: Specific advice for GNU/Linux systems
  366: =====================================
  367: 
  368: If you are installing GNU libc on a GNU/Linux system, you need to have
  369: the header files from a 2.2 or newer kernel around for reference.  For
  370: some architectures, like ia64, sh and hppa, you need at least headers
  371: from kernel 2.3.99 (sh and hppa) or 2.4.0 (ia64).  You do not need to
  372: use that kernel, just have its headers where glibc can access at them.
  373: The easiest way to do this is to unpack it in a directory such as
  374: `/usr/src/linux-2.2.1'.  In that directory, run `make config' and
  375: accept all the defaults.  Then run `make include/linux/version.h'.
  376: Finally, configure glibc with the option
  377: `--with-headers=/usr/src/linux-2.2.1/include'.  Use the most recent
  378: kernel you can get your hands on.
  379: 
  380:    An alternate tactic is to unpack the 2.2 kernel and run `make
  381: config' as above; then, rename or delete `/usr/include', create a new
  382: `/usr/include', and make symbolic links of `/usr/include/linux' and
  383: `/usr/include/asm' into the kernel sources.  You can then configure
  384: glibc with no special options.  This tactic is recommended if you are
  385: upgrading from libc5, since you need to get rid of the old header files
  386: anyway.
  387: 
  388:    After installing GNU libc, you may need to remove or rename
  389: `/usr/include/linux' and `/usr/include/asm', and replace them with
  390: copies of `include/linux' and `include/asm-$ARCHITECTURE' taken from
  391: the Linux source package which supplied kernel headers for building the
  392: library.  ARCHITECTURE will be the machine architecture for which the
  393: library was built, such as `i386' or `alpha'.  You do not need to do
  394: this if you did not specify an alternate kernel header source using
  395: `--with-headers'.  The intent here is that these directories should be
  396: copies of, *not* symlinks to, the kernel headers used to build the
  397: library.
  398: 
  399:    Note that `/usr/include/net' and `/usr/include/scsi' should *not* be
  400: symlinks into the kernel sources.  GNU libc provides its own versions
  401: of these files.
  402: 
  403:    GNU/Linux expects some components of the libc installation to be in
  404: `/lib' and some in `/usr/lib'.  This is handled automatically if you
  405: configure glibc with `--prefix=/usr'.  If you set some other prefix or
  406: allow it to default to `/usr/local', then all the components are
  407: installed there.
  408: 
  409:    If you are upgrading from libc5, you need to recompile every shared
  410: library on your system against the new library for the sake of new code,
  411: but keep the old libraries around for old binaries to use.  This is
  412: complicated and difficult.  Consult the Glibc2 HOWTO at
  413: `http://www.imaxx.net/~thrytis/glibc' for details.
  414: 
  415:    You cannot use `nscd' with 2.0 kernels, due to bugs in the
  416: kernel-side thread support.  `nscd' happens to hit these bugs
  417: particularly hard, but you might have problems with any threaded
  418: program.
  419: 
  420: Reporting Bugs
  421: ==============
  422: 
  423: There are probably bugs in the GNU C library.  There are certainly
  424: errors and omissions in this manual.  If you report them, they will get
  425: fixed.  If you don't, no one will ever know about them and they will
  426: remain unfixed for all eternity, if not longer.
  427: 
  428:    It is a good idea to verify that the problem has not already been
  429: reported.  Bugs are documented in two places: The file `BUGS' describes
  430: a number of well known bugs and the bug tracking system has a WWW
  431: interface at `http://sources.redhat.com/bugzilla/'.  The WWW interface
  432: gives you access to open and closed reports.  A closed report normally
  433: includes a patch or a hint on solving the problem.
  434: 
  435:    To report a bug, first you must find it.  With any luck, this will
  436: be the hard part.  Once you've found a bug, make sure it's really a
  437: bug.  A good way to do this is to see if the GNU C library behaves the
  438: same way some other C library does.  If so, probably you are wrong and
  439: the libraries are right (but not necessarily).  If not, one of the
  440: libraries is probably wrong.  It might not be the GNU library.  Many
  441: historical Unix C libraries permit things that we don't, such as
  442: closing a file twice.
  443: 
  444:    If you think you have found some way in which the GNU C library does
  445: not conform to the ISO and POSIX standards (*note Standards and
  446: Portability::), that is definitely a bug.  Report it!
  447: 
  448:    Once you're sure you've found a bug, try to narrow it down to the
  449: smallest test case that reproduces the problem.  In the case of a C
  450: library, you really only need to narrow it down to one library function
  451: call, if possible.  This should not be too difficult.
  452: 
  453:    The final step when you have a simple test case is to report the bug.
  454: Do this using the WWW interface to the bug database.
  455: 
  456:    If you are not sure how a function should behave, and this manual
  457: doesn't tell you, that's a bug in the manual.  Report that too!  If the
  458: function's behavior disagrees with the manual, then either the library
  459: or the manual has a bug, so report the disagreement.  If you find any
  460: errors or omissions in this manual, please report them to the bug
  461: database.  If you refer to specific sections of the manual, please
  462: include the section names for easier identification.
  463: