Installing the GNU C Library
****************************
-Before you do anything else, you should read the file `FAQ' located at
-the top level of the source tree. This file answers common questions
+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. It is updated more frequently than this manual.
+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.
+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::,
$ ../glibc-VERSION/configure ARGS...
Please note that even though you're building in a separate build
-directory, the compilation needs to modify a few files in the source
-directory, especially some files in the manual subdirectory.
+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
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
this can be prevented though there generally is no reason since it
creates compatibility problems.
+`--enable-hardcoded-path-in-tests'
+ By default, dynamic tests are linked to run with the installed C
+ library. This option hardcodes the newly built C library path in
+ dynamic tests so that they can be invoked directly.
+
+`--enable-lock-elision=yes'
+ Enable lock elision for pthread mutexes by default.
+
+`--enable-pt_chown'
+ The file `pt_chown' is a helper binary for `grantpt' (*note
+ Pseudo-Terminals: Allocation.) that is installed setuid root to
+ fix up pseudo-terminal ownership. It is not built by default
+ because systems using the Linux kernel are commonly built with the
+ `devpts' filesystem enabled and mounted at `/dev/pts', which
+ manages pseudo-terminal ownership automatically. By using
+ `--enable-pt_chown', you may build `pt_chown' and install it
+ setuid and owned by `root'. The use of `pt_chown' introduces
+ additional security risks to the system and you should enable it
+ only if you understand and accept those risks.
+
`--build=BUILD-SYSTEM'
`--host=HOST-SYSTEM'
These options are for cross-compiling. If you specify both
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.
+ 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
+ `i686-pc-linux-gnu' but you want to compile a library for 586es,
+ give `--host=i586-pc-linux-gnu' or just `--host=i586-linux' and add
+ the appropriate compiler flags (`-mcpu=i586' will do the trick) to
CFLAGS.
If you specify just `--build', `configure' will get confused.
+`--with-pkgversion=VERSION'
+ Specify a description, possibly including a build number or build
+ date, of the binaries being built, to be included in `--version'
+ output from programs installed with the GNU C Library. For
+ example, `--with-pkgversion='FooBar GNU/Linux glibc build 123''.
+ The default value is `GNU libc'.
+
+`--with-bugurl=URL'
+ Specify the URL that users should visit if they wish to report a
+ bug, to be included in `--help' output from programs installed with
+ the GNU C Library. The default value refers to the main
+ bug-reporting information for the GNU C Library.
+
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 `***'.
system such as `/etc/passwd', `/etc/nsswitch.conf' and others. These
files must all contain correct and sensible content.
+ Normally, `make check' will run all the tests before reporting all
+problems found and exiting with error status if any problems occurred.
+You can specify `stop-on-test-failure=y' when running `make check' to
+make the test run stop and exit with an error status immediately when a
+failure occurs.
+
To format the `GNU C Library Reference Manual' for printing, type
`make dvi'. You need a working TeX installation to do this. The
-distribution already includes the on-line formatted version of the
-manual, as Info files. You can regenerate those with `make info', but
-it shouldn't be necessary.
+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
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.
+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 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. If multiple assignments to
+the same variable are specified, the last assignment specified must
+take precedence.
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.
+manual, type `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
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 2.1 or newer 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'.
+`root' if the `--enable-pt_chown' configuration option is used. This
+program is invoked by the `grantpt' function; it sets the permissions
+on a pseudoterminal so it can be used by the calling process. If you
+are using a Linux kernel with the `devpts' filesystem enabled and
+mounted at `/dev/pts', you don't need this program.
After installation you might want to configure the timezone and
locale installation of your system. The GNU C Library comes with a
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.4 or newer, GCC 4.6 recommended
- GCC 4.3 or higher is required; as of this writing, GCC 4.6 is the
+ GCC 4.4 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
No other assembler or linker has the necessary functionality at the
moment.
- * GNU `texinfo' 3.12f
+ * 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
installation mechanism for the info files is not present or works
differently.
- * GNU `awk' 3.0, or higher
+ * GNU `awk' 3.1.2, or higher
- `Awk' is used in several places to generate files. `gawk' 3.0 is
- known to work.
+ `awk' is used in several places to generate files. Some `gawk'
+ extensions are used, including the `asorti' function, which was
+ introduced in version 3.1.2 of `gawk'.
* Perl 5
should definitely upgrade `sed'.
-If you change any of the `configure.in' files you will also need
+If you change any of the `configure.ac' files you will also need
* GNU `autoconf' 2.53 or higher
Specific advice for GNU/Linux systems
=====================================
-If you are installing the GNU C Library on a GNU/Linux system, you need
-to have the header files from a 2.6.19.1 or newer kernel around for
+If you are installing the GNU C Library on GNU/Linux systems, you need
+to have the header files from a 2.6.32 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
need to copy kernel headers if you did not specify an alternate kernel
header source using `--with-headers'.
- GNU/Linux 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.
-
- You cannot use `nscd' with 2.0 kernels, due to bugs in the
-kernel-side thread support. `nscd' happens to hit these bugs
-particularly hard, but you might have problems with any threaded
-program.
+ 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
==============
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://sources.redhat.com/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.
+a number of well known bugs and the central GNU C Library 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
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.
+Do this at `http://www.gnu.org/software/libc/bugs.html'.
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
projects / platform / upstream / glibc.git / blobdiff