<!doctype linuxdoc system>

<article>

<title>Glibc 2 HOWTO
<author>Eric Green, <tt/ejg3@cornell.edu/
<date>v1.6, 22 June 1998
<abstract>
<nidx>GNU C libary (see glibc)</nidx>
<nidx>glibc</nidx>
The glibc 2 HOWTO covers installing and using the GNU C Library version 2
(libc 6) on Linux systems.
</abstract>

<toc>


<sect>Introduction.
<p>

<sect1>About glibc 2.
<p>
<nidx>glibc!overview</nidx>

Glibc 2 is the latest version of the GNU C Library. It currently runs
unmodified on GNU Hurd systems and Linux i386, m68k, and alpha systems.
Support for Linux PowerPC, MIPS, Sparc, Sparc 64, and Arm will be in version
2.1.  In the future support for other architectures and operating systems
will be added.

On Linux, glibc 2 is used as the libc with major version 6, the successor
of the Linux libc 5.  It is intended by the Linux libc developers to
eventually replace libc 5.  As of 2.0.6, glibc is considered production
quality.  Version 2.1 (due out in the near future) will be ready for main
stream use along with adding more ports and features.

There are three optional add-ons available for glibc 2:
<descrip>
<tag/Crypt/The UFC-crypt package.  It is seperate  because of export restrictions.
<tag/LinuxThreads/An implementation of the Posix 1003.1c &dquot;pthread&dquot; interface.
<tag/Locale data/Contains the data needed to build the locale data files to
     use the internationalization features of the glibc.
</descrip>

The crypt and LinuxThreads add-ons are strongly recommended... not using
them risks to be incompatible with the libraries of other systems.
(If you do not wish to use them, you must add the option
--disable-sanity-checks when you run configure.)

<sect1>About this document.
<p>

This HOWTO covers installing the glibc 2 library on an existing Linux
system.  It is tailored for users of Intel based systems currently using
libc 5, but users of other systems and alternate libraries (such as glibc 1)
should be able to use this information by substituting the proper filenames
and architecture names in the appropriate places.

The latest copy of this HOWTO can be found as part of the
<url url="http://sunsite.unc.edu/LDP" name="Linux Documentation Project">
or from <url url="http://www.imaxx.net/~thrytis/glibc/Glibc2-HOWTO.html">.

<sect1>Recent changes in this document.
<p>

Differences between version 1.6 and 1.5:
<itemize>
<item>Fixed the install instructions of the binary glibc package.
</itemize>

Differences between version 1.5 and 1.4:
<itemize>
<item>Indexing added Ed Bailey.
<item>Changed my email address.
</itemize>


<sect>Choosing your installation method.
<p>
<nidx>glibc!installing</nidx>

There are a few ways to install glibc.  You can install the libraries
as a test, using the existing libraries as the default but letting you try
the new libraries by using different options when compiling your program.
Installing in this way also makes it easy to remove glibc in the future
(though any program linked with glibc will no longer work after the
libraries are removed). Using glibc as a test library requires you to
compile the libraries from source.  There is no binary distribution for
installing libraries this way.  This installation is described in
<ref id="test-install" name="Installing as a test library">.

The other way described in this document to install is using glibc as
your primary library.  All new programs that you compile on your system
will use glibc, though you can link programs with your old libraries using
different options while compiling.  You can either install the libraries
from binaries, or compile the library yourself.  If you want to change
optimization or configuration options, or use an add-on which is not
distributed as a binary package, you must get the source distribution
and compile.  This installation procedure is described in
<ref id="primary-install" name="Installing as the primary C library">.

Frodo Looijaard describes yet another way of installing glibc.  His
method involves installing glibc as a secondary library and setting up a
cross compiler to compile using glibc.  The installation procedure for
this method is more complicated then the test library install described
in this document, but allows for easier compiling when linking to glibc.
This method is described in his <url url="http://huizen.dds.nl/~frodol/glibc/"
name="Installing glibc-2 on Linux"> document.

If you are currently running Debian 1.3 but do not want to upgrade to the
unstable version of Debian to use glibc, the
<url url="http://www.gate.net/~storm/FAQ/libc5-libc6-Mini-HOWTO.html"
name="Debian libc5 to libc6 Mini-HOWTO"> describes how to use Debian
packages to upgrade your system.

If you are installing glibc 2 on an important system, you might want
to use the test install.  Even if there are no bugs, some programs
will need to be modified before they will compile due to changes in
function prototypes and types.


<sect>Getting the library.<label id="getting">
<p>
<nidx>glibc!obtaining</nidx>

The glibc 2 consists of the glibc package and three optional add-on
packages, LinuxThreads, Locale, and Crypt.  The source can be found
at
<itemize>
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-2.0.6.tar.gz">
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-linuxthreads-2.0.6.tar.gz">
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-localedata-2.0.6.tar.gz">
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-crypt-2.0.6.tar.gz">
</itemize>

It will take about 150 MB of disk space for the full compile and install.
The basic binary install of just the core library package is about 50 MB.

Binary packages for 2.0.6 are not available.  Version 2.0.4 binary packages
are available for i386 and m68k, and version 2.0.1 for the alpha can be
found at
<itemize>
<item>Intel x86:
<itemize>
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-2.0.4.bin.i386.tar.gz">
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-crypt-2.0.4.bin.i386.tar.gz">
</itemize>
<item>Alpha:
<itemize>
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-2.0.1.bin.alpha-linux.tar.gz">
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-crypt-2.0.1.bin.alpha-linux.tar.gz">
</itemize>
<item>m68k:
<itemize>
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-2.0.4-m68k-linux.bin.tar.gz">
<item><url url="ftp://prep.ai.mit.edu/pub/gnu/glibc-crypt-2.0.4-m68k-linux.bin.tar.gz">
</itemize>
</itemize>
There are export restrictions on the crypt add-on.  Non-US users should
get it from <url url="ftp://ftp.ifi.uio.no/pub/gnu">.

If you are running a Red Hat distribution, you can get rpms for glibc 2 from
<url url="ftp://ftp.redhat.com/pub/redhat/">.  Glibc 2 is the primary C
library for the new Red Hat distribution 5.0.

If you are running a Debian distribution, you can get the packages for glibc 2
from <url url="ftp://ftp.debian.org/debian/dists/unstable/main/">.  The
files are named libc6.  Glibc 2 is now part of the base package of the
hamm version of Debian, and will be the primary libc when Debian 2.0 is
released.


<sect>Installing as a test library.<label id="test-install">
<p>
<nidx>glibc!testing</nidx>

This section covers installing glibc 2 as a test library.  Anything you
compile will be linked to your existing libraries unless you give some
extra parameters to link to the new libraries.  It appears that the
paths are compiled into quite a few files, so you probably have to
install the library from source.

<sect1>Compiling and installing.
<p>

<sect2>Prerequisites.
<p>
<nidx>glibc!testing!prerequisites</nidx>

<itemize>
<item>About 150 MB free disk space
<item>GNU make 3.75
<item>gcc &gt;= 2.7.2 (better 2.7.2.1)
<item>binutils 2.8.1 (for alpha you need a snapshot)
<item>bash 2.0
<item>autoconf 2.12 (if you change configure.in)
<item>texinfo 3.11
</itemize>

On an i586@133 with 64 MB of RAM, it takes about 3 hours to compile with full
libraries with add-ons.  On a loaded i686@200, it takes about half
an hour.

<sect2>Extracting the source.
<p>
<nidx>glibc!testing!sources, extracting</nidx>

You need to extract the source from the archives so you can compile it.
The best way to do this is:
 <tscreen><verb>
 tar xzf glibc-2.0.6.tar.gz
 cd glibc-2.0.6
 tar xzf ../glibc-linuxthreads-2.0.6.tar.gz
 tar xzf ../glibc-crypt-2.0.6.tar.gz
 tar xzf ../glibc-localedata-2.0.6.tar.gz
 </verb></tscreen>
This will put linuxthreads, crypt, and localedata directories in the
glibc-2.0.6 directory where configure can find these add-ons.

<sect2>Configuring.
<p>
<nidx>glibc!testing!configuring</nidx>

In the glibc-2.0.6 directory, create a directory named compile, and
cd into it.  All work will be done in this directory, which will simplify
cleaning up.  (The developers have not been very concerned with getting 'make clean' perfect yet.)
 <tscreen><verb>
 mkdir compile
 cd compile
 </verb></tscreen>
Run <tt>../configure</tt>.  To use the add-on packages, you need to specify
them with --enable-add-ons, such as --enable-add-ons=linuxthreads,crypt,localedata.
You also need to choose a destination directory to install to.
/usr/i486-linuxglibc2 is a good choice.  The configure line for this would be:
 <tscreen><verb>
 ../configure --enable-add-ons=linuxthreads,crypt,localedata --prefix=/usr/i486-linuxglibc2
 </verb></tscreen>

<sect2>Compiling and installing.
<p>
<nidx>glibc!testing!compiling</nidx>
<nidx>glibc!testing!installing</nidx>

To compile and verify, run:
 <tscreen><verb>
 make
 make check
 </verb></tscreen>
If the 'make check' succeeds, install the library as root (while still in the
<tt>compile/</tt> directory):
 <tscreen><verb>
 make install
 </verb></tscreen>

<sect1>Updating the dynamic loader.
<p>
<nidx>glibc!testing!dynamic loader, updating</nidx>
<nidx>glibc!testing!ld.so.conf, updating</nidx>

<enum>
<item>Create a link from the new <tt>ld.so</tt> to <tt>/lib/ld-linux.so.2</tt>:
 <tscreen><verb>
 ln -s /usr/i486-linuxglibc2/lib/ld-linux.so.2 /lib/ld-linux.so.2
 </verb></tscreen>
This is the only library where the location is fixed once a program
is linked, and using a link in <tt>/lib</tt> will ease upgrading to glibc as
your primary C library when the stable version is released.
<item>Edit <tt>/etc/ld.so.conf</tt>.  You need to add path to the lib
directory the new libraries reside in at the end of the file, which will
be <tt>&lt;prefix&gt;/lib</tt>, such as <tt>/usr/i486-linuxglibc2/lib</tt>
for the choice above.  After you have modified <tt>/etc/ld.so.conf</tt>, run
 <tscreen><verb>
 ldconfig -v
 </verb></tscreen>
</enum>

<sect1>Configuring for gcc.
<p>
<nidx>glibc!testing!gcc configuration</nidx>
The last step of installation is updating <tt>/usr/lib/gcc-lib</tt> so gcc
knows how to use the new libraries.  First you need to duplicate the existing
configuration.  To find out which configuration is current, use the -v
option of gcc:
 <tscreen><verb>
 &percnt; gcc -v
 Reading specs from /usr/lib/gcc-lib/i486-unknown-linux/2.7.2.2/specs
 gcc version 2.7.2.2
 </verb></tscreen>
In this case, i486-unknown-linux is the system, and 2.7.2.2 is the
version.  You need to copy the <tt>/usr/lib/gcc-lib/&lt;system&gt;</tt> to
the new test system directory:
 <tscreen><verb>
 cd /usr/lib/gcc-lib/
 cp -r i486-unknown-linux i486-linuxglibc2
 </verb></tscreen>
Change into your new test system directory and version directory
 <tscreen><verb>
 cd /usr/lib/gcc-lib/i486-linuxglibc2/2.7.2.2
 </verb></tscreen>
and edit the file <tt>specs</tt> found in this directory.  In this file,
change <tt>/lib/ld-linux.so.1</tt> to <tt>/lib/ld-linux.so.2</tt>.  You also
need to remove all expressions <tt/&percnt;{...:-lgmon}/ in the file, since
glibc does not use the gmon library for profiling.  A sample specs file can
be found in the <ref id="specs" name="Sample specs file"> section.

<sect1>Updating header file links.
<p>
<nidx>glibc!testing!header files, updating</nidx>

You need create links in your new include directory to other include
directories:
 <tscreen><verb>
 cd /usr/i486-linuxglibc2/include
 ln -s /usr/src/linux/include/linux
 ln -s /usr/src/linux/include/asm
 ln -s /usr/X11R6/include/X11
 </verb></tscreen>
You might also have other libraries such as ncurses which need their
header files put in this directory.  You should copy or link the files
from <tt>/usr/include</tt>.  (Some libraries may need to be recompiled
with glibc2 in order to work with it.  In these cases, just compile and
install the package to <tt>/usr/i486-linuxglibc2</tt>.)

<sect1>Testing your installation.
<p>
<nidx>glibc!testing</nidx>

To test the installation, create the following program in a file glibc.c:
 <tscreen><verb>
 &num;include &lt;stdio.h&gt;

 main()
 {
     printf("hello world!\n");
 }
 </verb></tscreen>
and compile with the options of &dquot;-b &lt;base install directory&gt; -nostdinc -I&lt;install directory&gt;/include -I/usr/lib/gcc-lib/&lt;new system dir&gt/&lt;gcc version&gt;/include&dquot;:
 <tscreen><verb>
 &percnt; gcc -b i486-linuxglibc2 -nostdinc -I/usr/i486-linuxglibc2/include -I/usr/lib/gcc-lib/i486-linuxglibc2/2.7.2.2/include glibc.c -o glibc
 </verb></tscreen>
Use ldd to verify the program was linked with glibc2, and not your old libc:
 <tscreen><verb>
 &percnt; ldd glibc
 libc.so.6 => /usr/i486-linuxglibc2/lib/libc-2.0.6.so (0x4000d000)
 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
 </verb></tscreen>
If it compiles, the links check out, and it generates
&dquot;hello world!&dquot; when run, the installation succeeded.



<sect>Installing as the primary C library.<label id="primary-install">
<p>
<nidx>glibc!installation</nidx>

This section covers installing glibc 2 as your primary C library.  Any
new programs you compile will be linked with this library, unless you
use special compile options to link with another version.

If you are are using Redhat or Debian and have downloaded the appropriate
rpm or deb files, see the Redhat or Debian installion instructions.  You
can then skip this section.


<sect1>Building the library from source.<label id="compiling">
<p>
<nidx>glibc!installation!compilation</nidx>

This section explains how to compile glibc 2 and add-ons from the sources.
You must compile the library if you want to change optimization or
configuration options or use a package you do not have the binaries for.

<sect2>Prerequisites.
<p>
<nidx>glibc!installation!prerequisites</nidx>

<itemize>
<item>About 150 MB free disk space
<item>GNU make 3.75
<item>gcc &gt;= 2.7.2 (better 2.7.2.1)
<item>binutils 2.8.1 (for alpha you need a snapshot)
<item>bash 2.0
<item>autoconf 2.12 (if you change configure.in)
<item>texinfo 3.11
</itemize>

On an i586@133 with 64 MB of RAM, it takes about 3 hours to compile with full
libraries with add-ons.  On a loaded i686@200, it takes about half
an hour.

<sect2>Extracting the source.
<p>
<nidx>glibc!installation!sources, extracting</nidx>

You need to extract the source from the archives so you can compile it.
The best way to do this is:
 <tscreen><verb>
 tar xzf glibc-2.0.6.tar.gz
 cd glibc-2.0.6
 tar xzf ../glibc-linuxthreads-2.0.6.tar.gz
 tar xzf ../glibc-crypt-2.0.6.tar.gz
 tar xzf ../glibc-localedata-2.0.6.tar.gz
 </verb></tscreen>
This will put linuxthreads, crypt, and localedata directories in the
glibc-2.0.6 directory where configure can find these add-ons.

<sect2>Configuring.
<p>
<nidx>glibc!installation!configuration</nidx>

In the <tt>glibc-2.0.6</tt> directory, create a directory named compile, and
cd into it.  All work will be done in this directory, which will simplify
cleaning up.  (The developers have not been very concerned with getting 'make
clean' perfect yet.)
<tscreen><verb>
mkdir compile
cd compile
</verb></tscreen>
Run <tt>../configure</tt>.  To use the add-on packages, you need to specify
them with --enable-add-ons, such as --enable-add-ons=linuxthreads,crypt,localedata.
You probably will also want to specify paths where it will be installed.
To match the standard linux distributions, specify --prefix=/usr.  (When
a prefix of <tt>/usr</tt> is specified on a linux system, configure knows to
adjust other paths to place libc.so and other important libraries in
<tt>/lib</tt>.)  The whole configure line would be:
<tscreen><verb>
 ../configure --enable-add-ons=linuxthreads,crypt,localedata --prefix=/usr
</verb></tscreen>

<sect2>Compiling.
<p>
<nidx>glibc!installation!compilation</nidx>

To compile and verify, run:
 <tscreen><verb>
 make
 make check
 </verb></tscreen>


<sect1>Preparing for installation.
<p>
<nidx>glibc!installation!preparation for</nidx>

Now you need to move some files around to prepare for the new library,
whether you are installing from source or binaries.  Any new program compiled
will be linked to glibc, but old programs which are not statically linked
will still depend on libc 5, so you can not just overwrite the old version.

<enum>
<item>Create a new directory to hold the old files to:
 <tscreen><verb>
 mkdir -p /usr/i486-linuxlibc5/lib
 </verb></tscreen>

<item>The old header files must be evacuated from <tt>/usr/include</tt>:
 <tscreen><verb>
 mv /usr/include /usr/i486-linuxlibc5/include
 </verb></tscreen>

<item>Create a new include directory and set up the links to other include
directories:
 <tscreen><verb>
 mkdir /usr/include

 ln -s /usr/src/linux/include/linux /usr/include/linux
 ln -s /usr/src/linux/include/asm /usr/include/asm
 ln -s /usr/X11R6/include/X11 /usr/include/X11
 ln -s /usr/lib/g++-include /usr/include/g++
 </verb></tscreen>
The links may need adjusting according to your distribution.  At least
Slackware puts g++ headers in <tt>/usr/local/g++-include</tt>, while Debian
puts the headers in <tt>/usr/include/g++</tt>, and links
<tt>/usr/lib/g++-include</tt> to <tt>/usr/include/g++</tt>.  In the later
case, you probably will want to move the original g++ include directory back
to <tt>/usr/include</tt>.

<item>Restore any extra header files and links.  Some non-standard libraries
such as ncurses put files in <tt>/usr/include</tt> or put a link to their
include directories in the <tt>/usr/include</tt>.  These files and links need
to be restored in order to use the extra libraries properly.

<item>Add your new library directory (such as
<tt>/usr/i486-linuxlibc5/lib</tt>) <em>at the top</em> of your
<tt>/etc/ld.so.conf</tt> file.  You should have ld.so 1.8.8 or
better installed to avoid getting strange messages once glibc is installed.

<item>Move/copy all the old C libraries into the new directory.
 <tscreen><verb>
 mv /usr/lib/libbsd.a /usr/i486-linuxlibc5/lib
 mv /usr/lib/libc.a /usr/i486-linuxlibc5/lib
 mv /usr/lib/libgmon.a /usr/i486-linuxlibc5/lib
 mv /usr/lib/libm.a /usr/i486-linuxlibc5/lib
 mv /usr/lib/libmcheck.a /usr/i486-linuxlibc5/lib
 mv /usr/lib/libc.so /usr/i486-linuxlibc5/lib
 mv /usr/lib/libm.so /usr/i486-linuxlibc5/lib
 cp /lib/libm.so.5.* /usr/i486-linuxlibc5/lib
 cp /lib/libc.so.5.* /usr/i486-linuxlibc5/lib
 </verb></tscreen>
<tt>libm.so.5</tt> and <tt>libc.so.5</tt> should be copied and not moved if
<tt>/usr</tt> is a seperate partition from <tt>/</tt>, because they are
required by programs used to start linux and must be located on the root
drive partition.

<item>Move the <tt>/usr/lib/*.o</tt> files into the new directory.
 <tscreen><verb>
 mv /usr/lib/crt1.o /usr/i486-linuxlibc5/lib
 mv /usr/lib/crti.o /usr/i486-linuxlibc5/lib
 mv /usr/lib/crtn.o /usr/i486-linuxlibc5/lib
 mv /usr/lib/gcrt1.o /usr/i486-linuxlibc5/lib
 </verb></tscreen>

<item>Update your library cache after your libraries are moved.
 <tscreen><verb>
 ldconfig -v
 </verb></tscreen>
</enum>


<sect1>Installing from the binary package.
<p>
<nidx>glibc!installation!precompiled binaries</nidx>

If you are installing glibc from precompiled binaries, you first want
to check what is in the package before you install the binaries:
 <tscreen><verb>
 tar -tzvvf glibc-2.0.bin.i386.tar.gz
 tar -tzvvf glibc-crypt-2.0.bin.i386.tar.gz
 </verb></tscreen>
If you are happy with that, you can install glibc with:
 <tscreen><verb>
 cd /
 tar -xzf glibc-2.0.bin.i386.tar.gz
 tar -xzf glibc-crypt-2.0.bin.i386.tar.gz
 ldconfig -v
 </verb></tscreen>
If you have a different architecture or version, substitute the proper
file names.

The most recent glibc version is generally not available as a binary
package, and it is strongly recommended that you run the most recent
version to avoid bugs.  If you can not build the library yourself, grab
a binary package of glibc from one of the distributions that is based
on glibc (e.g. RedHat) and install this.

<sect1>Installing from the source.
<p>
<nidx>glibc!installation!from source</nidx>

To install the library from source, run as root from the <tt>compile/</tt>
directory:
 <tscreen><verb>
 make install
 ldconfig -v
 </verb></tscreen>


<sect1>Updating the gcc specs.
<p>
<nidx>glibc!installation!gcc specs file, updating</nidx>

The final step of the installation (for both binary and source installs)
is to update the gcc <tt>specs</tt> file so you can link your programs
properly. To determine which specs file is the one used by gcc, use:
 <tscreen><verb>
 &percnt; gcc -v
 reading specs from /usr/lib/gcc-lib/i486-unknown-linux/2.7.2.2/specs
 gcc version 2.7.2.2
 </verb></tscreen>

In this case, i486-unknown-linux is the system, and 2.7.2.2 is the version.
You need to copy the <tt>/usr/lib/gcc-lib/&lt;system&gt;</tt> to the old
system directory:
 <tscreen><verb>
 cd /usr/lib/gcc-lib/
 cp -r i486-unknown-linux i486-linuxlibc5
 </verb></tscreen>

Change into the original directory and version directory
 <tscreen><verb>
 cd /usr/lib/gcc-lib/i486-unknown-linux/2.7.2.2
 </verb></tscreen>

and edit the file <tt>specs</tt> found in this directory.  In this file,
change <tt>/lib/ld-linux.so.1</tt> to <tt>/lib/ld-linux.so.2</tt>.  You
also need to remove all expressions <tt/&percnt;{...:-lgmon}/ in the file,
since glibc does not use the gmon library for profiling.  A sample specs
file can be found in the <ref id="specs" name="Sample specs file"> section.


<sect1>Testing your installation.
<p>
<nidx>glibc!installation!testing</nidx>

To test the installation, create the following program in a file glibc.c:
 <tscreen><verb>
 &num;include &lt;stdio.h&gt;

 main()
 {
     printf("hello world!\n");
 }
 </verb></tscreen>
and compile the program.
 <tscreen><verb>
 &percnt; gcc glibc.c -o glibc
 </verb></tscreen>
Use ldd to verify the program was linked with glibc2, and not your old libc:
 <tscreen><verb>
 &percnt; ldd glibc
 libc.so.6 => /lib/libc.so.6 (0x4000e000)
 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
 </verb></tscreen>
If this compiles and generates &dquot;hello world!&dquot; when run, the
installation was successful.



<sect>Compiling with the non-primary libc.
<p>
<nidx>glibc!compiling with alternate library</nidx>

There are times you will want to use an alternate library to compile
your programs with.  This section explains how to accomplish this, using
the directories and installation names used in the examples in the
previous two sections.  Remember to change the names to fit your setup.

<sect1>A warning when using non-primary libcs.
<p>
<nidx>glibc!compiling with alternate library!warning</nidx>
Before compiling any programs which is used in the system boot process,
remember that if the program is dynamically linked and is used before the
non-root partitions are mounted, all linked libraries must be on the root
partition.  Following the installation process in the previous section
for installing glibc as your primary C library, the old libc is left in
<tt>/lib</tt>, which will be on your root partition.  This means all of your
programs will still work during booting.  However, if <tt>/usr</tt> is on a
different partition and you install glibc as a test library in
<tt>/usr/i486-linuxglibc2</tt>, any new programs you compile with glibc
will not work until your <tt>/usr</tt> partition is mounted.

<sect1>Compiling programs with a test glibc.
<p>
<nidx>glibc!compiling with alternate library!glibc</nidx>
To compile a program with a test-install glibc, you need to reset the
include paths to point to the glibc includes.  Specifying
&dquot;-nostdinc&dquot; will negate the normal paths, and
&dquot;-I/usr/i486-linuxglibc2/include&dquot; will point
to the glibc includes.  You will also need to specify the gcc includes,
which are found in <tt>/usr/lib/gcc-lib/i486-linuxglibc2/2.7.2.2/include</tt>
(assuming you installed the test lib in i486-linuxglibc2 with gcc version
2.7.2.2).

To link a program with a test-install glibc, you need to specify the
gcc setup.  This is done by using the option &dquot;-b i486-linuxglibc2&dquot;.

For most programs, you can specify these new options by adding them to the
<tt>&dollar;CFLAGS</tt> and <tt>&dollar;LDFLAGS</tt> makefile options:
 <tscreen><verb>
 CFLAGS = -nostdinc -I/usr/i486-linuxglibc2/include -I/usr/lib/gcc-lib/i486-linuxglibc2/2.7.2.2/include -b i486-linuxglibc2
 LDFLAGS = -b i486-linuxglibc2
 </verb></tscreen>
If you are using a configure script, define the <tt>&dollar;CFLAGS</tt>
and <tt>&dollar;LDFLAGS</tt> shell variables (by using env/setenv for
csh/tcsh, or set/export for sh/bash/etc) before running configure.  The
makefiles generated by this should contain the proper <tt>&dollar;CFLAGS</tt>
and <tt>&dollar;LDFLAGS</tt>.  Not all configure scripts
will pick up the variables, so you should check after running configure
and edit the makefiles by hand if necessary.

If the programs you are compiling only call gcc (and not cpp or binutils
directly), you can use the following script to save having to specify
all of the options each time:
 <tscreen><verb>
 &num;!/bin/bash
 /usr/bin/gcc -b i486-linuxglibc2 -nostdinc \
              -I/usr/i486-linuxglibc2/include \
              -I/usr/lib/gcc-lib/i486-linuxglibc2/2.7.2.2/include "&dollar;@"
 </verb></tscreen>
You can then use this script instead of &dquot;gcc&dquot; when compiling.

<sect1>Compiling programs with libc 5 when glibc is primary library.
<p>
<nidx>glibc!compiling with alternate library!libc 5</nidx>
To compile a program with your old libraries when you have installed
glibc as your main library, you need to reset the include paths to
the old includes.  Specifying &dquot;-nostdinc&dquot; will negate the
normal paths, and &dquot;-I/usr/i486-linuxlibc5/include&dquot; will point
to the glibc includes.  You must also specify
&dquot;-I/usr/lib/gcc-lib/i486-linuxlibc5/2.7.2.2/include&dquot;
to include the gcc specific includes.  Remember to adjust these paths
based on the what you named the new directories and your gcc version.

To link a program with your old libc, you need to specify the gcc
setup.  This is done by using the option
&dquot;-b i486-linuxlibc5&dquot;.

For most programs, you can specify these new options by appending them
to the <tt>&dollar;CFLAGS</tt> and <tt>&dollar;LDFLAGS</tt> makefile options:
 <tscreen><verb>
 CFLAGS = -nostdinc -I/usr/i486-linuxlibc5/include -I/usr/lib/gcc-lib/i486-linuxlibc5/2.7.2.2/include -b i486-linuxlibc5
 LDFLAGS = -b i486-linuxlibc5
 </verb></tscreen>
If you are using a configure script, define the <tt>&dollar;CFLAGS</tt>
and <tt>&dollar;LDFLAGS</tt> shell variables (by using env/setenv for
csh/tcsh, or set/export for sh/bash/etc) before running configure.  The
makefiles generated by this should contain the proper
<tt>&dollar;CFLAGS</tt> and <tt>&dollar;LDFLAGS</tt>.  Not all configure
scripts will pick up the variables, so you should check after running
configure and edit the makefiles by hand if necessary.

If the programs you are compiling only call gcc (and not cpp or binutils
directly), you can use the following script to save having to specify
all of the options each time:
 <tscreen><verb>
 &num;!/bin/bash
 /usr/bin/gcc -b i486-linuxlibc5 -nostdinc \
              -I/usr/i486-linuxlibc5/include \
              -I/usr/lib/gcc-lib/i486-linuxlibc5/2.7.2.2/include "&dollar;@"
 </verb></tscreen>
You can then use this script instead of &dquot;gcc&dquot; when compiling.


<sect>Compiling C++ programs.
<p>
<nidx>glibc!C++ programs, compiling</nidx>

Libg++ uses parts of the math library, so is link to libm.  Since your
existing libg++ will be compiled with your old library, you will have
to recompile libg++ with glibc or get a binary copy.  The latest source for
libg++ along with a binary linked with glibc (for x86) can be found at
<url url="ftp://ftp.yggdrasil.com/private/hjl/">.

<sect1>Installing libg++ for a test glibc install.
<p>
<nidx>glibc!libg++, installing!as test library</nidx>
If you have installed glibc as a test library, you need to install
the files into the directory you installed glibc into (such as
<tt>/usr/i486-linuxglibc2</tt> for the example in the previous sections).
If you are installing from the binary package (which i would recommend,
since i never had any luck compiling libg++ this way), you need to
extract the files into a temporary directory and move all the
<tt>usr/lib/</tt> files into the <tt>&lt;install directory&gt;/lib/</tt>
directory, the <tt>usr/include/</tt> files into the
<tt>&lt;install directory&gt;/include/</tt> directory (remember to
delete your <tt>include/g++</tt> link first!), and the <tt>usr/bin/</tt>
files into the <tt>&lt;install directory&gt;/bin/</tt> directory.

<sect1>Installing libg++ for a primary glibc install.
<p>
<nidx>glibc!libg++, installing!as primary library</nidx>
If you have installed glibc as the primary library, you first need to move
your old libg++ files into your old libc directory if you still want to be able
to compile g++ programs with your old libc.  Probably the easiest way to
do this is by installing a new copy of the libg++ compiled with libc 5
as in the previous section, and then installing the glibc version normally.

<sect1>Compiling C++ programs with the non-primary libc.
<p>
<nidx>glibc!C++ programs, compiling!with non-primary libc</nidx>
If you are trying to compile a C++ program with a non-primary libc, you
will need to include the g++ include dir, which in the examples above would
be <tt>/usr/i486-linuxglibc2/include/g++</tt> for a test glibc install or
<tt>/usr/i486-linuxlibc5/include/g++</tt> for a primary glibc install.
This can usually be done by appending the <tt>&dollar;CXXFLAGS</tt> variable:
 <tscreen><verb>
 CXXFLAGS = -nostdinc -I/usr/i486-linuxglibc2/include -I/usr/lib/gcc-lib/i486-linuxglibc2/2.7.2.2/include -I/usr/i486-linuxlibc5/include/g++ -b i486-linuxglibc2
 </verb></tscreen>


<sect>Problems.
<p>
<nidx>glibc!problems</nidx>

The glibc package contains a FAQ with additional information that you should
check if you are having problems.  An online version is also available
at <url url="http://www.imaxx.net/~thrytis/glibc/glibc-FAQ.html">.  Below
are some tips for solving problems which are not covered in the FAQ or are
covered here in more detail.

<sect1>Host names do not resolve.
<p>
<nidx>glibc!problems!names not resolving</nidx>

Glibc 2 uses a different method than libc 5 in looking up host names.
The glibc name server switch (NSS) code looks for a file
<tt>/etc/nsswitch.conf</tt>.  If host names are not resolving for you
when using a glibc 2 application and your <tt>/etc/resolv.conf</tt> is
configured correctly, check if you have the <tt>/etc/nsswitch.conf</tt>
file.  If you do not have this file, you can create one containing the
line:
 <tscreen><verb>
 hosts:        files dns
 </verb></tscreen>
It will now look for <tt>/etc/resolv.conf</tt> to find the nameservers.

You should look at the section of the libc info pages describing the
nsswitch.conf file for more details.


<sect>Reporting bugs.
<p>
<nidx>glibc!bugs, reporting</nidx>

If you think the lib is buggy, please read first the FAQ. It might be that
others had the same problem and there's an easy solution. You should also
check the section "Recommended Tools to Install the GNU C Library" in the
<tt>INSTALL</tt> file since some bugs are bugs of the tools and not of glibc.

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.

Next, go to <url url="http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl">,
and look through the bug database.  Check here to verify the problem has not
already be reported. You should also look at the file <tt>BUGS</tt>
(distributed with libc) to check for known bugs.

Once you're sure you've found a new 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, the versions of the GNU C library, the GNU CC compiler, and
the GNU Binutils which you are using.  Also include the files
<tt>config.status</tt> and <tt>config.make</tt> which are created by running
<tt>configure</tt>; they will be in whatever directory was current when you
ran <tt>configure</tt>.

All bug reports for the GNU C library should be sent using the
<tt/glibcbug/ shell script which comes with the GNU libc to
<url url="bugs@gnu.org"> (the older address <url url="bugs@gnu.ai.mit.edu">
is still working), or submitted through the GNATS web interface at
<url url="http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl">.

Suggestions and questions should be sent to the mailing list at
<url url="bugs-glibc@prep.ai.mit.edu">.
If you don't read the gnewsgroup gnu.bug.glibc, you can subscribe to
the list by asking <url url="bug-glibc-request@prep.ai.mit.edu">.

Please DO NOT send bug report for the GNU C library to
&lt;bug-gcc@prep.ai.mit.edu&gt;.  That list is for bug reports for GNU CC.
GNU CC and the GNU C library are separate entities maintained by
separate people.


<sect>Sample specs file.<label id="specs">
<p>
<nidx>glibc!GCC specs file, sample</nidx>

Included here is a sample <tt>specs</tt> file for glibc 2 which is used by
gcc for compiling and linking.  It should be found in the directory
<tt>/usr/lib/gcc-lib/&lt;new system dir&gt;/&lt;gcc version&gt;</tt>.  If you
are running an x86 system, you probably can copy this section to the file
exactly.
 <tscreen><verb>
 *asm:
 &percnt;{V} &percnt;{v:&percnt;{!V:-V}} &percnt;{Qy:} &percnt;{!Qn:-Qy} &percnt;{n} &percnt;{T} &percnt;{Ym,*} &percnt;{Yd,*} &percnt;{Wa,*:&percnt;*}

 *asm_final:
 &percnt;{pipe:-}

 *cpp:
 &percnt;{fPIC:-D__PIC__ -D__pic__} &percnt;{fpic:-D__PIC__ -D__pic__} &percnt;{!m386:-D__i486__} &percnt;{posix:-D_POSIX_SOURCE} &percnt;{pthread:-D_REENTRANT}

 *cc1:
 &percnt;{profile:-p}

 *cc1plus:


 *endfile:
 &percnt;{!shared:crtend.o&percnt;s} &percnt;{shared:crtendS.o&percnt;s} crtn.o&percnt;s

 *link:
 -m elf_i386 &percnt;{shared:-shared}   &percnt;{!shared:     &percnt;{!ibcs:       &percnt;{!static:   &percnt;{rdynamic:-export-dynamic}      &percnt;{!dynamic-linker:-dynamic-linker /lib/ld-linux.so.2}}
&percnt;{static:-static}}}

 *lib:
 &percnt;{!shared: &percnt;{pthread:-lpthread}  &percnt;{profile:-lc_p} &percnt;{!profile: -lc}}

 *libgcc:
 -lgcc

 *startfile:
 &percnt;{!shared:      &percnt;{pg:gcrt1.o&percnt;s} &percnt;{!pg:&percnt;{p:gcrt1.o&percnt;s}                        &percnt;{!p:&percnt;{profile:gcrt1.o&percnt;s}
 &percnt;{!profile:crt1.o&percnt;s}}}}    crti.o&percnt;s &percnt;{!shared:crtbegin.o&percnt;s} &percnt;{shared:crtbeginS.o&percnt;s}

 *switches_need_spaces:


 *signed_char:
 &percnt;{funsigned-char:-D__CHAR_UNSIGNED__}

 *predefines:
 -D__ELF__ -Dunix -Di386 -Dlinux -Asystem(unix) -Asystem(posix) -Acpu(i386) -Amachine(i386)

 *cross_compile:
 0

 *multilib:
 . ;
 </verb></tscreen>

<sect>Miscellanea.
<p>
<nidx>glibc!miscellanea</nidx>

<sect1>Further information.
<nidx>glibc!information resources</nidx>

<p>

<sect2>Web pages.
<p>
<nidx>glibc!information resources!WWW</nidx>

<itemize>
<item><url url="http://www.gnu.org/software/libc/libc.html" name="FSF's GNU C Library Home Page">
<item><url url="http://www.imaxx.net/~thrytis/glibc/" name="Using GNU Libc 2 with Linux">
<item><url url="http://huizen.dds.nl/~frodol/glibc/"name="Installing glibc-2 on Linux">.
<item><url url="http://www.gate.net/~storm/FAQ/libc5-libc6-Mini-HOWTO.html" name="Debian libc5 to libc6 Mini-HOWTO">.
</itemize>

<sect2>Newgroups.
<p>
<nidx>glibc!information resources!newsgroups</nidx>

<itemize>
<item><htmlurl url="news:comp.os.linux.development.system" name="comp.os.linux.development.system">
<item><htmlurl url="news:comp.os.linux.development.apps" name="comp.os.linux.development.apps">
<item><htmlurl url="news:linux.dev.kernel" name="linux.dev.kernel">
<item><htmlurl url="news:gnu.bug.glibc" name="gnu.bugs.glibc">
</itemize>

<sect2>Mailing lists.
<p>
<nidx>glibc!information resources!mailing lists</nidx>

<descrip>
<tag/Glibc 2 Linux discussion list./
This list is intended for discussion among Linux users who
have installed glibc2, the new GNU C libraries.  Topics
might include compatibility issues and questions about the
compilation of code in a Linux/glibc setting.
To subscribe, send mail to <url url="mailto:Majordomo@ricardo.ecn.wfu.edu"
name="Majordomo@ricardo.ecn.wfu.edu"> with a body of "subscribe glibc-linux
&lt;your email address&gt;.

Archives for this mailing list can be found at <url
url="http://www.progressive-comp.com/Lists/?l=linux-glibc&amp;r=1&amp;w=2&num;linux-glibc">
</descrip>

<sect1>Credits.
<p>

Most of this information was stolen from the
<url url="http://www.gnu.org/software/libc/libc.html" name="GNU Libc web page">
and from Ulrich Drepper's &lt;drepper@gnu.ai.mit.edu&gt; glibc 2 announcement
and his comments.   Andreas Jaeger &lt;aj@arthur.rhein-neckar.de&gt;
provided some of the Reporting bugs section.

The following people have provided information and feedback for this document:
<itemize>
<item>Allex &lt;allex@ms2.accmail.com.tw&gt;
<item>Mark Brown &lt;M.A.Brown-4@sms.ed.ac.uk&gt;
<item>Ulrich Drepper &lt;drepper@gnu.ai.mit.edu&gt;
<item>Scott K. Ellis &lt;ellis@valueweb.net&gt;
<item>Aron Griffis &lt;agriffis@coat.com&gt;
<item>Andreas Jaeger &lt;aj@arthur.rhein-neckar.de&gt;
<item>Hank Leininger &lt;hlein@progressive-comp.com&gt;
<item>Frodo Looijaard &lt;frodol@dds.nl&gt;
<item>Ryan McGuire &lt;rmcguire@freenet.columbus.oh.us&gt;
<item>Shaya Potter &lt;spotter@capaccess.org&gt;
<item>Les Schaffer &lt;godzilla@futuris.net&gt;
<item>Andy Sewell &lt;puck@pookhill.demon.co.uk&gt;
<item>Gary Shea &lt;shea@gtsdesign.com&gt;
<item>Stephane &lt;sr@adb.fr&gt;
<item>Jan Vandenbos &lt;jan@imaxx.net&gt;
<item>Michael Wolf &lt;wolfm@rpi.edu&gt;
</itemize>

Translations of this document are being done by:
<itemize>
<item>Chinese: Allex &lt;allex@ms2.accmail.com.tw&gt;
<item>French:  Olivier Tharan &lt;tharan@int-evry.fr&gt;
<item>Japanese:  Kazuyuki Okamoto &lt;ikko-@pacific.rim.or.jp&gt;
</itemize>


<sect1>Feedback.
<p>

Besides writing this HOWTO, maintaining the
<url url="http://www.imaxx.net/~thrytis/glibc" name="glibc 2 for Linux">
page, and using it on my machine, I have nothing to do with the glibc
project.  I am far from knowledgeable on this topic, though I try to help
with problems mailed to me.  I welcome any feedback, corrections, or
suggestions you have to offer.  Please send them to
<url url="mailto:ejg3@cornell.edu" name="ejg3@cornell.edu">.

<sect1>Copyright.
<P>
Copyright (c) 1997 by Eric Green.  This document may be distributed under
the terms set forth in the LDP license.

</article>
