440 lines
21 KiB
Plaintext
440 lines
21 KiB
Plaintext
Installing the GNU C Library
|
|
****************************
|
|
|
|
Before you do anything else, you should read the FAQ at
|
|
`http://sourceware.org/glibc/wiki/FAQ'. It answers common questions
|
|
and describes problems you may experience with compilation and
|
|
installation.
|
|
|
|
Features can be added to the GNU C Library via "add-on" bundles.
|
|
These are separate tar files, which you unpack into the top level of
|
|
the source tree. Then you give `configure' the `--enable-add-ons'
|
|
option to activate them, and they will be compiled into the library.
|
|
|
|
You will need recent versions of several GNU tools: definitely GCC
|
|
and GNU Make, and possibly others. *Note Tools for Compilation::,
|
|
below.
|
|
|
|
Configuring and compiling the GNU C Library
|
|
===========================================
|
|
|
|
The GNU C Library cannot be compiled in the source directory. You must
|
|
build it in a separate build directory. For example, if you have
|
|
unpacked the GNU C Library sources in `/src/gnu/glibc-VERSION', create
|
|
a directory `/src/gnu/glibc-build' to put the object files in. This
|
|
allows removing the whole build directory in case an error occurs,
|
|
which is the safest way to get a fresh start and should always be done.
|
|
|
|
From your object directory, run the shell script `configure' located
|
|
at the top level of the source tree. In the scenario above, you'd type
|
|
|
|
$ ../glibc-VERSION/configure ARGS...
|
|
|
|
Please note that even though you're building in a separate build
|
|
directory, the compilation may need to create or modify files and
|
|
directories in the source directory.
|
|
|
|
`configure' takes many options, but the only one that is usually
|
|
mandatory is `--prefix'. This option tells `configure' where you want
|
|
the GNU C Library installed. This defaults to `/usr/local', but the
|
|
normal setting to install as the standard system library is
|
|
`--prefix=/usr' for GNU/Linux systems and `--prefix=' (an empty prefix)
|
|
for GNU/Hurd systems.
|
|
|
|
It may also be useful to set the CC and CFLAGS variables in the
|
|
environment when running `configure'. CC selects the C compiler that
|
|
will be used, and CFLAGS sets optimization options for the compiler.
|
|
|
|
The following list describes all of the available options for
|
|
`configure':
|
|
|
|
`--prefix=DIRECTORY'
|
|
Install machine-independent data files in subdirectories of
|
|
`DIRECTORY'. The default is to install in `/usr/local'.
|
|
|
|
`--exec-prefix=DIRECTORY'
|
|
Install the library and other machine-dependent files in
|
|
subdirectories of `DIRECTORY'. The default is to the `--prefix'
|
|
directory if that option is specified, or `/usr/local' otherwise.
|
|
|
|
`--with-headers=DIRECTORY'
|
|
Look for kernel header files in DIRECTORY, not `/usr/include'.
|
|
The GNU C Library needs information from the kernel's header files
|
|
describing the interface to the kernel. The GNU C Library will
|
|
normally look in `/usr/include' for them, but if you specify this
|
|
option, it will look in DIRECTORY instead.
|
|
|
|
This option is primarily of use on a system where the headers in
|
|
`/usr/include' come from an older version of the GNU C Library.
|
|
Conflicts can occasionally happen in this case. You can also use
|
|
this option if you want to compile the GNU C Library with a newer
|
|
set of kernel headers than the ones found in `/usr/include'.
|
|
|
|
`--enable-add-ons[=LIST]'
|
|
Specify add-on packages to include in the build. If this option is
|
|
specified with no list, it enables all the add-on packages it
|
|
finds in the main source directory; this is the default behavior.
|
|
You may specify an explicit list of add-ons to use in LIST,
|
|
separated by spaces or commas (if you use spaces, remember to
|
|
quote them from the shell). Each add-on in LIST can be an
|
|
absolute directory name or can be a directory name relative to the
|
|
main source directory, or relative to the build directory (that
|
|
is, the current working directory). For example,
|
|
`--enable-add-ons=nptl,../glibc-libidn-VERSION'.
|
|
|
|
`--enable-kernel=VERSION'
|
|
This option is currently only useful on GNU/Linux systems. The
|
|
VERSION parameter should have the form X.Y.Z and describes the
|
|
smallest version of the Linux kernel the generated library is
|
|
expected to support. The higher the VERSION number is, the less
|
|
compatibility code is added, and the faster the code gets.
|
|
|
|
`--with-binutils=DIRECTORY'
|
|
Use the binutils (assembler and linker) in `DIRECTORY', not the
|
|
ones the C compiler would default to. You can use this option if
|
|
the default binutils on your system cannot deal with all the
|
|
constructs in the GNU C Library. In that case, `configure' will
|
|
detect the problem and suppress these constructs, so that the
|
|
library will still be usable, but functionality may be lost--for
|
|
example, you can't build a shared libc with old binutils.
|
|
|
|
`--without-fp'
|
|
Use this option if your computer lacks hardware floating-point
|
|
support and your operating system does not emulate an FPU.
|
|
|
|
`--disable-shared'
|
|
Don't build shared libraries even if it is possible. Not all
|
|
systems support shared libraries; you need ELF support and
|
|
(currently) the GNU linker.
|
|
|
|
`--disable-profile'
|
|
Don't build libraries with profiling information. You may want to
|
|
use this option if you don't plan to do profiling.
|
|
|
|
`--disable-versioning'
|
|
Don't compile the shared libraries with symbol version information.
|
|
Doing this will make the resulting library incompatible with old
|
|
binaries, so it's not recommended.
|
|
|
|
`--enable-static-nss'
|
|
Compile static versions of the NSS (Name Service Switch) libraries.
|
|
This is not recommended because it defeats the purpose of NSS; a
|
|
program linked statically with the NSS libraries cannot be
|
|
dynamically reconfigured to use a different name database.
|
|
|
|
`--without-tls'
|
|
By default the C library is built with support for thread-local
|
|
storage if the used tools support it. By using `--without-tls'
|
|
this can be prevented though there generally is no reason since it
|
|
creates compatibility problems.
|
|
|
|
`--build=BUILD-SYSTEM'
|
|
`--host=HOST-SYSTEM'
|
|
These options are for cross-compiling. If you specify both
|
|
options and BUILD-SYSTEM is different from HOST-SYSTEM, `configure'
|
|
will prepare to cross-compile the GNU C Library from BUILD-SYSTEM
|
|
to be used on HOST-SYSTEM. You'll probably need the
|
|
`--with-headers' option too, and you may have to override
|
|
CONFIGURE's selection of the compiler and/or binutils.
|
|
|
|
If you only specify `--host', `configure' will prepare for a
|
|
native compile but use what you specify instead of guessing what
|
|
your system is. This is most useful to change the CPU submodel.
|
|
For example, if `configure' guesses your machine as
|
|
`i586-pc-linux-gnu' but you want to compile a library for 386es,
|
|
give `--host=i386-pc-linux-gnu' or just `--host=i386-linux' and add
|
|
the appropriate compiler flags (`-mcpu=i386' will do the trick) to
|
|
CFLAGS.
|
|
|
|
If you specify just `--build', `configure' will get confused.
|
|
|
|
To build the library and related programs, type `make'. This will
|
|
produce a lot of output, some of which may look like errors from `make'
|
|
but isn't. Look for error messages from `make' containing `***'.
|
|
Those indicate that something is seriously wrong.
|
|
|
|
The compilation process can take a long time, depending on the
|
|
configuration and the speed of your machine. Some complex modules may
|
|
take a very long time to compile, as much as several minutes on slower
|
|
machines. Do not panic if the compiler appears to hang.
|
|
|
|
If you want to run a parallel make, simply pass the `-j' option with
|
|
an appropriate numeric parameter to `make'. You need a recent GNU
|
|
`make' version, though.
|
|
|
|
To build and run test programs which exercise some of the library
|
|
facilities, type `make check'. If it does not complete successfully,
|
|
do not use the built library, and report a bug after verifying that the
|
|
problem is not already known. *Note Reporting Bugs::, for instructions
|
|
on reporting bugs. Note that some of the tests assume they are not
|
|
being run by `root'. We recommend you compile and test the GNU C
|
|
Library as an unprivileged user.
|
|
|
|
Before reporting bugs make sure there is no problem with your system.
|
|
The tests (and later installation) use some pre-existing files of the
|
|
system such as `/etc/passwd', `/etc/nsswitch.conf' and others. These
|
|
files must all contain correct and sensible content.
|
|
|
|
To format the `GNU C Library Reference Manual' for printing, type
|
|
`make dvi'. You need a working TeX installation to do this. The
|
|
distribution builds the on-line formatted version of the manual, as
|
|
Info files, as part of the build process. You can build them manually
|
|
with `make info'.
|
|
|
|
The library has a number of special-purpose configuration parameters
|
|
which you can find in `Makeconfig'. These can be overwritten with the
|
|
file `configparms'. To change them, create a `configparms' in your
|
|
build directory and add values as appropriate for your system. The
|
|
file is included and parsed by `make' and has to follow the conventions
|
|
for makefiles.
|
|
|
|
It is easy to configure the GNU C Library for cross-compilation by
|
|
setting a few variables in `configparms'. Set `CC' to the
|
|
cross-compiler for the target you configured the library for; it is
|
|
important to use this same `CC' value when running `configure', like
|
|
this: `CC=TARGET-gcc configure TARGET'. Set `BUILD_CC' to the compiler
|
|
to use for programs run on the build system as part of compiling the
|
|
library. You may need to set `AR' to cross-compiling versions of `ar'
|
|
if the native tools are not configured to work with object files for
|
|
the target you configured for. When cross-compiling the GNU C Library,
|
|
it may be tested using `make check
|
|
test-wrapper="SRCDIR/scripts/cross-test-ssh.sh HOSTNAME"', where SRCDIR
|
|
is the absolute directory name for the main source directory and
|
|
HOSTNAME is the host name of a system that can run the newly built
|
|
binaries of the GNU C Library. The source and build directories must
|
|
be visible at the same locations on both the build system and HOSTNAME.
|
|
|
|
In general, when testing the GNU C Library, `test-wrapper' may be set
|
|
to the name and arguments of any program to run newly built binaries.
|
|
This program must preserve the arguments to the binary being run, its
|
|
working directory, all environment variables set as part of testing and
|
|
the standard input, output and error file descriptors. If
|
|
`TEST-WRAPPER env' will not work to run a program with environment
|
|
variables set, then `test-wrapper-env' must be set to a program that
|
|
runs a newly built program with environment variable assignments in
|
|
effect, those assignments being specified as `VAR=VALUE' before the
|
|
name of the program to be run.
|
|
|
|
Installing the C Library
|
|
========================
|
|
|
|
To install the library and its header files, and the Info files of the
|
|
manual, type `env LANGUAGE=C LC_ALL=C make install'. This will build
|
|
things, if necessary, before installing them; however, you should still
|
|
compile everything first. If you are installing the GNU C Library as
|
|
your primary C library, we recommend that you shut the system down to
|
|
single-user mode first, and reboot afterward. This minimizes the risk
|
|
of breaking things when the library changes out from underneath.
|
|
|
|
`make install' will do the entire job of upgrading from a previous
|
|
installation of the GNU C Library version 2.x. There may sometimes be
|
|
headers left behind from the previous installation, but those are
|
|
generally harmless. If you want to avoid leaving headers behind you
|
|
can do things in the following order.
|
|
|
|
You must first build the library (`make'), optionally check it
|
|
(`make check'), switch the include directories and then install (`make
|
|
install'). The steps must be done in this order. Not moving the
|
|
directory before install will result in an unusable mixture of header
|
|
files from both libraries, but configuring, building, and checking the
|
|
library requires the ability to compile and run programs against the old
|
|
library. The new `/usr/include', after switching the include
|
|
directories and before installing the library should contain the Linux
|
|
headers, but nothing else. If you do this, you will need to restore
|
|
any headers from libraries other than the GNU C Library yourself after
|
|
installing the library.
|
|
|
|
You can install the GNU C Library somewhere other than where you
|
|
configured it to go by setting the `install_root' variable on the
|
|
command line for `make install'. The value of this variable is
|
|
prepended to all the paths for installation. This is useful when
|
|
setting up a chroot environment or preparing a binary distribution.
|
|
The directory should be specified with an absolute file name.
|
|
|
|
The GNU C Library includes a daemon called `nscd', which you may or
|
|
may not want to run. `nscd' caches name service lookups; it can
|
|
dramatically improve performance with NIS+, and may help with DNS as
|
|
well.
|
|
|
|
One auxiliary program, `/usr/libexec/pt_chown', is installed setuid
|
|
`root'. This program is invoked by the `grantpt' function; it sets the
|
|
permissions on a pseudoterminal so it can be used by the calling
|
|
process. This means programs like `xterm' and `screen' do not have to
|
|
be setuid to get a pty. (There may be other reasons why they need
|
|
privileges.) If you are using a Linux kernel with the `devptsfs' or
|
|
`devfs' filesystems providing pty slaves, you don't need this program;
|
|
otherwise you do. The source for `pt_chown' is in
|
|
`login/programs/pt_chown.c'.
|
|
|
|
After installation you might want to configure the timezone and
|
|
locale installation of your system. The GNU C Library comes with a
|
|
locale database which gets configured with `localedef'. For example, to
|
|
set up a German locale with name `de_DE', simply issue the command
|
|
`localedef -i de_DE -f ISO-8859-1 de_DE'. To configure all locales
|
|
that are supported by the GNU C Library, you can issue from your build
|
|
directory the command `make localedata/install-locales'.
|
|
|
|
To configure the locally used timezone, set the `TZ' environment
|
|
variable. The script `tzselect' helps you to select the right value.
|
|
As an example, for Germany, `tzselect' would tell you to use
|
|
`TZ='Europe/Berlin''. For a system wide installation (the given paths
|
|
are for an installation with `--prefix=/usr'), link the timezone file
|
|
which is in `/usr/share/zoneinfo' to the file `/etc/localtime'. For
|
|
Germany, you might execute `ln -s /usr/share/zoneinfo/Europe/Berlin
|
|
/etc/localtime'.
|
|
|
|
Recommended Tools for Compilation
|
|
=================================
|
|
|
|
We recommend installing the following GNU tools before attempting to
|
|
build the GNU C Library:
|
|
|
|
* GNU `make' 3.79 or newer
|
|
|
|
You need the latest version of GNU `make'. Modifying the GNU C
|
|
Library to work with other `make' programs would be so difficult
|
|
that we recommend you port GNU `make' instead. *Really.* We
|
|
recommend GNU `make' version 3.79. All earlier versions have
|
|
severe bugs or lack features.
|
|
|
|
* GCC 4.3 or newer, GCC 4.6 recommended
|
|
|
|
GCC 4.3 or higher is required; as of this writing, GCC 4.6 is the
|
|
compiler we advise to use to build the GNU C Library.
|
|
|
|
You can use whatever compiler you like to compile programs that use
|
|
the GNU C Library.
|
|
|
|
Check the FAQ for any special compiler issues on particular
|
|
platforms.
|
|
|
|
* GNU `binutils' 2.20 or later
|
|
|
|
You must use GNU `binutils' (as and ld) to build the GNU C Library.
|
|
No other assembler or linker has the necessary functionality at the
|
|
moment.
|
|
|
|
* GNU `texinfo' 4.5 or later
|
|
|
|
To correctly translate and install the Texinfo documentation you
|
|
need this version of the `texinfo' package. Earlier versions do
|
|
not understand all the tags used in the document, and the
|
|
installation mechanism for the info files is not present or works
|
|
differently.
|
|
|
|
* GNU `awk' 3.0, or higher
|
|
|
|
`Awk' is used in several places to generate files. `gawk' 3.0 is
|
|
known to work.
|
|
|
|
* Perl 5
|
|
|
|
Perl is not required, but it is used if present to test the
|
|
installation. We may decide to use it elsewhere in the future.
|
|
|
|
* GNU `sed' 3.02 or newer
|
|
|
|
`Sed' is used in several places to generate files. Most scripts
|
|
work with any version of `sed'. The known exception is the script
|
|
`po2test.sed' in the `intl' subdirectory which is used to generate
|
|
`msgs.h' for the test suite. This script works correctly only
|
|
with GNU `sed' 3.02. If you like to run the test suite, you
|
|
should definitely upgrade `sed'.
|
|
|
|
|
|
If you change any of the `configure.in' files you will also need
|
|
|
|
* GNU `autoconf' 2.53 or higher
|
|
|
|
and if you change any of the message translation files you will need
|
|
|
|
* GNU `gettext' 0.10.36 or later
|
|
|
|
You may also need these packages if you upgrade your source tree using
|
|
patches, although we try to avoid this.
|
|
|
|
Specific advice for GNU/Linux systems
|
|
=====================================
|
|
|
|
If you are installing the GNU C Library on GNU/Linux systems, you need
|
|
to have the header files from a 2.6.19.1 or newer kernel around for
|
|
reference. These headers must be installed using `make
|
|
headers_install'; the headers present in the kernel source directory
|
|
are not suitable for direct use by the GNU C Library. You do not need
|
|
to use that kernel, just have its headers installed where the GNU C
|
|
Library can access them, referred to here as INSTALL-DIRECTORY. The
|
|
easiest way to do this is to unpack it in a directory such as
|
|
`/usr/src/linux-VERSION'. In that directory, run `make headers_install
|
|
INSTALL_HDR_PATH=INSTALL-DIRECTORY'. Finally, configure the GNU C
|
|
Library with the option `--with-headers=INSTALL-DIRECTORY/include'.
|
|
Use the most recent kernel you can get your hands on. (If you are
|
|
cross-compiling the GNU C Library, you need to specify
|
|
`ARCH=ARCHITECTURE' in the `make headers_install' command, where
|
|
ARCHITECTURE is the architecture name used by the Linux kernel, such as
|
|
`x86' or `powerpc'.)
|
|
|
|
After installing the GNU C Library, you may need to remove or rename
|
|
directories such as `/usr/include/linux' and `/usr/include/asm', and
|
|
replace them with copies of directories such as `linux' and `asm' from
|
|
`INSTALL-DIRECTORY/include'. All directories present in
|
|
`INSTALL-DIRECTORY/include' should be copied, except that the GNU C
|
|
Library provides its own version of `/usr/include/scsi'; the files
|
|
provided by the kernel should be copied without replacing those
|
|
provided by the GNU C Library. The `linux', `asm' and `asm-generic'
|
|
directories are required to compile programs using the GNU C Library;
|
|
the other directories describe interfaces to the kernel but are not
|
|
required if not compiling programs using those interfaces. You do not
|
|
need to copy kernel headers if you did not specify an alternate kernel
|
|
header source using `--with-headers'.
|
|
|
|
The Filesystem Hierarchy Standard for GNU/Linux systems expects some
|
|
components of the GNU C Library installation to be in `/lib' and some
|
|
in `/usr/lib'. This is handled automatically if you configure the GNU
|
|
C Library with `--prefix=/usr'. If you set some other prefix or allow
|
|
it to default to `/usr/local', then all the components are installed
|
|
there.
|
|
|
|
Reporting Bugs
|
|
==============
|
|
|
|
There are probably bugs in the GNU C Library. There are certainly
|
|
errors and omissions in this manual. If you report them, they will get
|
|
fixed. If you don't, no one will ever know about them and they will
|
|
remain unfixed for all eternity, if not longer.
|
|
|
|
It is a good idea to verify that the problem has not already been
|
|
reported. Bugs are documented in two places: The file `BUGS' describes
|
|
a number of well known bugs and the bug tracking system has a WWW
|
|
interface at `http://sourceware.org/bugzilla/'. The WWW interface
|
|
gives you access to open and closed reports. A closed report normally
|
|
includes a patch or a hint on solving the problem.
|
|
|
|
To report a bug, first you must find it. With any luck, this will
|
|
be the hard part. Once you've found a bug, make sure it's really a
|
|
bug. A good way to do this is to see if the GNU C Library behaves the
|
|
same way some other C library does. If so, probably you are wrong and
|
|
the libraries are right (but not necessarily). If not, one of the
|
|
libraries is probably wrong. It might not be the GNU C Library. Many
|
|
historical Unix C libraries permit things that we don't, such as
|
|
closing a file twice.
|
|
|
|
If you think you have found some way in which the GNU C Library does
|
|
not conform to the ISO and POSIX standards (*note Standards and
|
|
Portability::), that is definitely a bug. Report it!
|
|
|
|
Once you're sure you've found a bug, try to narrow it down to the
|
|
smallest test case that reproduces the problem. In the case of a C
|
|
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.
|
|
Do this using the WWW interface to the bug database.
|
|
|
|
If you are not sure how a function should behave, and this manual
|
|
doesn't tell you, that's a bug in the manual. Report that too! If the
|
|
function's behavior disagrees with the manual, then either the library
|
|
or the manual has a bug, so report the disagreement. If you find any
|
|
errors or omissions in this manual, please report them to the bug
|
|
database. If you refer to specific sections of the manual, please
|
|
include the section names for easier identification.
|