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