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