blob: 63c41b0b8daac1612659ef9bf7604560d7ef0259 [file] [log] [blame]
lh9ed821d2023-04-07 01:36:19 -07001@include macros.texi
2@include pkgvers.texi
3
4@ifclear plain
5@node Installation, Maintenance, Library Summary, Top
6@end ifclear
7
8@c %MENU% How to install the GNU C Library
9@appendix Installing @theglibc{}
10
11Before you do anything else, you should read the FAQ at
12@url{http://sourceware.org/glibc/wiki/FAQ}. It answers common
13questions and describes problems you may experience with compilation
14and installation.
15
16Features can be added to @theglibc{} via @dfn{add-on} bundles. These are
17separate tar files, which you unpack into the top level of the source
18tree. Then you give @code{configure} the @samp{--enable-add-ons} option
19to activate them, and they will be compiled into the library.
20
21You will need recent versions of several GNU tools: definitely GCC and
22GNU Make, and possibly others. @xref{Tools for Compilation}, below.
23
24@ifclear plain
25@menu
26* Configuring and compiling:: How to compile and test GNU libc.
27* Running make install:: How to install it once you've got it
28 compiled.
29* Tools for Compilation:: You'll need these first.
30* Linux:: Specific advice for GNU/Linux systems.
31* Reporting Bugs:: So they'll get fixed.
32@end menu
33@end ifclear
34
35@node Configuring and compiling
36@appendixsec Configuring and compiling @theglibc{}
37@cindex configuring
38@cindex compiling
39
40@Theglibc{} cannot be compiled in the source directory. You must build
41it in a separate build directory. For example, if you have unpacked
42the @glibcadj{} sources in @file{/src/gnu/glibc-@var{version}},
43create a directory
44@file{/src/gnu/glibc-build} to put the object files in. This allows
45removing the whole build directory in case an error occurs, which is
46the safest way to get a fresh start and should always be done.
47
48From your object directory, run the shell script @file{configure} located
49at the top level of the source tree. In the scenario above, you'd type
50
51@smallexample
52$ ../glibc-@var{version}/configure @var{args@dots{}}
53@end smallexample
54
55Please note that even though you're building in a separate build
56directory, the compilation may need to create or modify files and
57directories in the source directory.
58
59@noindent
60@code{configure} takes many options, but the only one that is usually
61mandatory is @samp{--prefix}. This option tells @code{configure}
62where you want @theglibc{} installed. This defaults to @file{/usr/local},
63but the normal setting to install as the standard system library is
64@samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an
65empty prefix) for @gnuhurdsystems{}.
66
67It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
68the environment when running @code{configure}. @var{CC} selects the C
69compiler that will be used, and @var{CFLAGS} sets optimization options
70for the compiler.
71
72The following list describes all of the available options for
73 @code{configure}:
74
75@table @samp
76@item --prefix=@var{directory}
77Install machine-independent data files in subdirectories of
78@file{@var{directory}}. The default is to install in @file{/usr/local}.
79
80@item --exec-prefix=@var{directory}
81Install the library and other machine-dependent files in subdirectories
82of @file{@var{directory}}. The default is to the @samp{--prefix}
83directory if that option is specified, or @file{/usr/local} otherwise.
84
85@item --with-headers=@var{directory}
86Look for kernel header files in @var{directory}, not
87@file{/usr/include}. @Theglibc{} needs information from the kernel's header
88files describing the interface to the kernel. @Theglibc{} will normally
89look in @file{/usr/include} for them,
90but if you specify this option, it will look in @var{DIRECTORY} instead.
91
92This option is primarily of use on a system where the headers in
93@file{/usr/include} come from an older version of @theglibc{}. Conflicts can
94occasionally happen in this case. You can also use this option if you want to
95compile @theglibc{} with a newer set of kernel headers than the ones found in
96@file{/usr/include}.
97
98@item --enable-add-ons[=@var{list}]
99Specify add-on packages to include in the build. If this option is
100specified with no list, it enables all the add-on packages it finds in
101the main source directory; this is the default behavior. You may
102specify an explicit list of add-ons to use in @var{list}, separated by
103spaces or commas (if you use spaces, remember to quote them from the
104shell). Each add-on in @var{list} can be an absolute directory name
105or can be a directory name relative to the main source directory, or
106relative to the build directory (that is, the current working directory).
107For example, @samp{--enable-add-ons=nptl,../glibc-libidn-@var{version}}.
108
109@item --enable-kernel=@var{version}
110This option is currently only useful on @gnulinuxsystems{}. The
111@var{version} parameter should have the form X.Y.Z and describes the
112smallest version of the Linux kernel the generated library is expected
113to support. The higher the @var{version} number is, the less
114compatibility code is added, and the faster the code gets.
115
116@item --with-binutils=@var{directory}
117Use the binutils (assembler and linker) in @file{@var{directory}}, not
118the ones the C compiler would default to. You can use this option if
119the default binutils on your system cannot deal with all the constructs
120in @theglibc{}. In that case, @code{configure} will detect the
121problem and suppress these constructs, so that the library will still be
122usable, but functionality may be lost---for example, you can't build a
123shared libc with old binutils.
124
125@item --without-fp
126Use this option if your computer lacks hardware floating-point support
127and your operating system does not emulate an FPU.
128
129@c disable static doesn't work currently
130@c @item --disable-static
131@c Don't build static libraries. Static libraries aren't that useful these
132@c days, but we recommend you build them in case you need them.
133
134@item --disable-shared
135Don't build shared libraries even if it is possible. Not all systems
136support shared libraries; you need ELF support and (currently) the GNU
137linker.
138
139@item --disable-profile
140Don't build libraries with profiling information. You may want to use
141this option if you don't plan to do profiling.
142
143@item --enable-static-nss
144Compile static versions of the NSS (Name Service Switch) libraries.
145This is not recommended because it defeats the purpose of NSS; a program
146linked statically with the NSS libraries cannot be dynamically
147reconfigured to use a different name database.
148
149@item --without-tls
150By default the C library is built with support for thread-local storage
151if the used tools support it. By using @samp{--without-tls} this can be
152prevented though there generally is no reason since it creates
153compatibility problems.
154
155@item --enable-hardcoded-path-in-tests
156By default, dynamic tests are linked to run with the installed C library.
157This option hardcodes the newly built C library path in dynamic tests
158so that they can be invoked directly.
159
160@item --enable-lock-elision=yes
161Enable lock elision for pthread mutexes by default.
162
163@pindex pt_chown
164@findex grantpt
165@item --enable-pt_chown
166The file @file{pt_chown} is a helper binary for @code{grantpt}
167(@pxref{Allocation, Pseudo-Terminals}) that is installed setuid root to
168fix up pseudo-terminal ownership. It is not built by default because
169systems using the Linux kernel are commonly built with the @code{devpts}
170filesystem enabled and mounted at @file{/dev/pts}, which manages
171pseudo-terminal ownership automatically. By using
172@samp{--enable-pt_chown}, you may build @file{pt_chown} and install it
173setuid and owned by @code{root}. The use of @file{pt_chown} introduces
174additional security risks to the system and you should enable it only if
175you understand and accept those risks.
176
177@item --disable-werror
178By default, @theglibc{} is built with @option{-Werror}. If you wish
179to build without this option (for example, if building with a newer
180version of GCC than this version of @theglibc{} was tested with, so
181new warnings cause the build with @option{-Werror} to fail), you can
182configure with @option{--disable-werror}.
183
184@item --disable-mathvec
185By default for x86_64, @theglibc{} is built with vector math library.
186Use this option to disable vector math library.
187
188@item --build=@var{build-system}
189@itemx --host=@var{host-system}
190These options are for cross-compiling. If you specify both options and
191@var{build-system} is different from @var{host-system}, @code{configure}
192will prepare to cross-compile @theglibc{} from @var{build-system} to be used
193on @var{host-system}. You'll probably need the @samp{--with-headers}
194option too, and you may have to override @var{configure}'s selection of
195the compiler and/or binutils.
196
197If you only specify @samp{--host}, @code{configure} will prepare for a
198native compile but use what you specify instead of guessing what your
199system is. This is most useful to change the CPU submodel. For example,
200if @code{configure} guesses your machine as @code{i686-pc-linux-gnu} but
201you want to compile a library for 586es, give
202@samp{--host=i586-pc-linux-gnu} or just @samp{--host=i586-linux} and add
203the appropriate compiler flags (@samp{-mcpu=i586} will do the trick) to
204@var{CFLAGS}.
205
206If you specify just @samp{--build}, @code{configure} will get confused.
207
208@item --with-pkgversion=@var{version}
209Specify a description, possibly including a build number or build
210date, of the binaries being built, to be included in
211@option{--version} output from programs installed with @theglibc{}.
212For example, @option{--with-pkgversion='FooBar GNU/Linux glibc build
213123'}. The default value is @samp{GNU libc}.
214
215@item --with-bugurl=@var{url}
216Specify the URL that users should visit if they wish to report a bug,
217to be included in @option{--help} output from programs installed with
218@theglibc{}. The default value refers to the main bug-reporting
219information for @theglibc{}.
220@end table
221
222To build the library and related programs, type @code{make}. This will
223produce a lot of output, some of which may look like errors from
224@code{make} but isn't. Look for error messages from @code{make}
225containing @samp{***}. Those indicate that something is seriously wrong.
226
227The compilation process can take a long time, depending on the
228configuration and the speed of your machine. Some complex modules may
229take a very long time to compile, as much as several minutes on slower
230machines. Do not panic if the compiler appears to hang.
231
232If you want to run a parallel make, simply pass the @samp{-j} option
233with an appropriate numeric parameter to @code{make}. You need a recent
234GNU @code{make} version, though.
235
236To build and run test programs which exercise some of the library
237facilities, type @code{make check}. If it does not complete
238successfully, do not use the built library, and report a bug after
239verifying that the problem is not already known. @xref{Reporting Bugs},
240for instructions on reporting bugs. Note that some of the tests assume
241they are not being run by @code{root}. We recommend you compile and
242test @theglibc{} as an unprivileged user.
243
244Before reporting bugs make sure there is no problem with your system.
245The tests (and later installation) use some pre-existing files of the
246system such as @file{/etc/passwd}, @file{/etc/nsswitch.conf} and others.
247These files must all contain correct and sensible content.
248
249Normally, @code{make check} will run all the tests before reporting
250all problems found and exiting with error status if any problems
251occurred. You can specify @samp{stop-on-test-failure=y} when running
252@code{make check} to make the test run stop and exit with an error
253status immediately when a failure occurs.
254
255To format the @cite{GNU C Library Reference Manual} for printing, type
256@w{@code{make dvi}}. You need a working @TeX{} installation to do
257this. The distribution builds the on-line formatted version of the
258manual, as Info files, as part of the build process. You can build
259them manually with @w{@code{make info}}.
260
261The library has a number of special-purpose configuration parameters
262which you can find in @file{Makeconfig}. These can be overwritten with
263the file @file{configparms}. To change them, create a
264@file{configparms} in your build directory and add values as appropriate
265for your system. The file is included and parsed by @code{make} and has
266to follow the conventions for makefiles.
267
268It is easy to configure @theglibc{} for cross-compilation by
269setting a few variables in @file{configparms}. Set @code{CC} to the
270cross-compiler for the target you configured the library for; it is
271important to use this same @code{CC} value when running
272@code{configure}, like this: @samp{CC=@var{target}-gcc configure
273@var{target}}. Set @code{BUILD_CC} to the compiler to use for programs
274run on the build system as part of compiling the library. You may need to
275set @code{AR} to cross-compiling versions of @code{ar}
276if the native tools are not configured to work with
277object files for the target you configured for. When cross-compiling
278@theglibc{}, it may be tested using @samp{make check
279test-wrapper="@var{srcdir}/scripts/cross-test-ssh.sh @var{hostname}"},
280where @var{srcdir} is the absolute directory name for the main source
281directory and @var{hostname} is the host name of a system that can run
282the newly built binaries of @theglibc{}. The source and build
283directories must be visible at the same locations on both the build
284system and @var{hostname}.
285
286In general, when testing @theglibc{}, @samp{test-wrapper} may be set
287to the name and arguments of any program to run newly built binaries.
288This program must preserve the arguments to the binary being run, its
289working directory and the standard input, output and error file
290descriptors. If @samp{@var{test-wrapper} env} will not work to run a
291program with environment variables set, then @samp{test-wrapper-env}
292must be set to a program that runs a newly built program with
293environment variable assignments in effect, those assignments being
294specified as @samp{@var{var}=@var{value}} before the name of the
295program to be run. If multiple assignments to the same variable are
296specified, the last assignment specified must take precedence.
297Similarly, if @samp{@var{test-wrapper} env -i} will not work to run a
298program with an environment completely empty of variables except those
299directly assigned, then @samp{test-wrapper-env-only} must be set; its
300use has the same syntax as @samp{test-wrapper-env}, the only
301difference in its semantics being starting with an empty set of
302environment variables rather than the ambient set.
303
304
305@node Running make install
306@appendixsec Installing the C Library
307@cindex installing
308
309To install the library and its header files, and the Info files of the
310manual, type @code{make install}. This will
311build things, if necessary, before installing them; however, you should
312still compile everything first. If you are installing @theglibc{} as your
313primary C library, we recommend that you shut the system down to
314single-user mode first, and reboot afterward. This minimizes the risk
315of breaking things when the library changes out from underneath.
316
317@samp{make install} will do the entire job of upgrading from a
318previous installation of @theglibc{} version 2.x. There may sometimes
319be headers
320left behind from the previous installation, but those are generally
321harmless. If you want to avoid leaving headers behind you can do
322things in the following order.
323
324You must first build the library (@samp{make}), optionally check it
325(@samp{make check}), switch the include directories and then install
326(@samp{make install}). The steps must be done in this order. Not moving
327the directory before install will result in an unusable mixture of header
328files from both libraries, but configuring, building, and checking the
329library requires the ability to compile and run programs against the old
330library. The new @file{/usr/include}, after switching the include
331directories and before installing the library should contain the Linux
332headers, but nothing else. If you do this, you will need to restore
333any headers from libraries other than @theglibc{} yourself after installing the
334library.
335
336You can install @theglibc{} somewhere other than where you configured
337it to go by setting the @code{DESTDIR} GNU standard make variable on
338the command line for @samp{make install}. The value of this variable
339is prepended to all the paths for installation. This is useful when
340setting up a chroot environment or preparing a binary distribution.
341The directory should be specified with an absolute file name. Installing
342with the @code{prefix} and @code{exec_prefix} GNU standard make variables
343set is not supported.
344
345@Theglibc{} includes a daemon called @code{nscd}, which you
346may or may not want to run. @code{nscd} caches name service lookups; it
347can dramatically improve performance with NIS+, and may help with DNS as
348well.
349
350One auxiliary program, @file{/usr/libexec/pt_chown}, is installed setuid
351@code{root} if the @samp{--enable-pt_chown} configuration option is used.
352This program is invoked by the @code{grantpt} function; it sets the
353permissions on a pseudoterminal so it can be used by the calling process.
354If you are using a Linux kernel with the @code{devpts} filesystem enabled
355and mounted at @file{/dev/pts}, you don't need this program.
356
357After installation you might want to configure the timezone and locale
358installation of your system. @Theglibc{} comes with a locale
359database which gets configured with @code{localedef}. For example, to
360set up a German locale with name @code{de_DE}, simply issue the command
361@samp{localedef -i de_DE -f ISO-8859-1 de_DE}. To configure all locales
362that are supported by @theglibc{}, you can issue from your build directory the
363command @samp{make localedata/install-locales}.
364
365To configure the locally used timezone, set the @code{TZ} environment
366variable. The script @code{tzselect} helps you to select the right value.
367As an example, for Germany, @code{tzselect} would tell you to use
368@samp{TZ='Europe/Berlin'}. For a system wide installation (the given
369paths are for an installation with @samp{--prefix=/usr}), link the
370timezone file which is in @file{/usr/share/zoneinfo} to the file
371@file{/etc/localtime}. For Germany, you might execute @samp{ln -s
372/usr/share/zoneinfo/Europe/Berlin /etc/localtime}.
373
374@node Tools for Compilation
375@appendixsec Recommended Tools for Compilation
376@cindex installation tools
377@cindex tools, for installing library
378
379We recommend installing the following GNU tools before attempting to
380build @theglibc{}:
381
382@itemize @bullet
383@item
384GNU @code{make} 3.79 or newer
385
386You need the latest version of GNU @code{make}. Modifying @theglibc{}
387to work with other @code{make} programs would be so difficult that
388we recommend you port GNU @code{make} instead. @strong{Really.} We
389recommend GNU @code{make} version 3.79. All earlier versions have severe
390bugs or lack features.
391
392@item
393GCC 4.6 or newer
394
395GCC 4.6 or higher is required. In general it is recommended to use
396the newest version of the compiler that is known to work for building
397@theglibc{}, as newer compilers usually produce better code. As of
398release time, GCC 4.9.2 is the newest compiler verified to work to build
399@theglibc{}.
400
401You can use whatever compiler you like to compile programs that use
402@theglibc{}.
403
404Check the FAQ for any special compiler issues on particular platforms.
405
406@item
407GNU @code{binutils} 2.22 or later
408
409You must use GNU @code{binutils} (as and ld) to build @theglibc{}.
410No other assembler or linker has the necessary functionality at the
411moment. As of release time, GNU @code{binutils} 2.25 is the newest
412verified to work to build @theglibc{}.
413
414@item
415GNU @code{texinfo} 4.7 or later
416
417To correctly translate and install the Texinfo documentation you need
418this version of the @code{texinfo} package. Earlier versions do not
419understand all the tags used in the document, and the installation
420mechanism for the info files is not present or works differently.
421As of release time, @code{texinfo} 5.2 is the newest verified to work
422to build @theglibc{}.
423
424@item
425GNU @code{awk} 3.1.2, or higher
426
427@code{awk} is used in several places to generate files.
428Some @code{gawk} extensions are used, including the @code{asorti}
429function, which was introduced in version 3.1.2 of @code{gawk}.
430
431@item
432Perl 5
433
434Perl is not required, but it is used if present to test the
435installation. We may decide to use it elsewhere in the future.
436
437@item
438GNU @code{sed} 3.02 or newer
439
440@code{Sed} is used in several places to generate files. Most scripts work
441with any version of @code{sed}. The known exception is the script
442@code{po2test.sed} in the @code{intl} subdirectory which is used to
443generate @code{msgs.h} for the test suite. This script works correctly
444only with GNU @code{sed} 3.02. If you like to run the test suite, you
445should definitely upgrade @code{sed}.
446
447@end itemize
448
449@noindent
450If you change any of the @file{configure.ac} files you will also need
451
452@itemize @bullet
453@item
454GNU @code{autoconf} 2.69 (exactly)
455@end itemize
456
457@noindent
458and if you change any of the message translation files you will need
459
460@itemize @bullet
461@item
462GNU @code{gettext} 0.10.36 or later
463@end itemize
464
465@noindent
466If you wish to regenerate the @code{yacc} parser code in the @file{intl}
467subdirectory you will need
468
469@itemize @bullet
470@item
471GNU @code{bison} 2.7 or later
472@end itemize
473
474@noindent
475You may also need these packages if you upgrade your source tree using
476patches, although we try to avoid this.
477
478@node Linux
479@appendixsec Specific advice for @gnulinuxsystems{}
480@cindex kernel header files
481
482If you are installing @theglibc{} on @gnulinuxsystems{}, you need to have
483the header files from a 2.6.32 or newer kernel around for reference.
484These headers must be installed using @samp{make headers_install}; the
485headers present in the kernel source directory are not suitable for
486direct use by @theglibc{}. You do not need to use that kernel, just have
487its headers installed where @theglibc{} can access them, referred to here as
488@var{install-directory}. The easiest way to do this is to unpack it
489in a directory such as @file{/usr/src/linux-@var{version}}. In that
490directory, run @samp{make headers_install
491INSTALL_HDR_PATH=@var{install-directory}}. Finally, configure @theglibc{}
492with the option @samp{--with-headers=@var{install-directory}/include}.
493Use the most recent kernel you can get your hands on. (If you are
494cross-compiling @theglibc{}, you need to specify
495@samp{ARCH=@var{architecture}} in the @samp{make headers_install}
496command, where @var{architecture} is the architecture name used by the
497Linux kernel, such as @samp{x86} or @samp{powerpc}.)
498
499After installing @theglibc{}, you may need to remove or rename
500directories such as @file{/usr/include/linux} and
501@file{/usr/include/asm}, and replace them with copies of directories
502such as @file{linux} and @file{asm} from
503@file{@var{install-directory}/include}. All directories present in
504@file{@var{install-directory}/include} should be copied, except that
505@theglibc{} provides its own version of @file{/usr/include/scsi}; the
506files provided by the kernel should be copied without replacing those
507provided by @theglibc{}. The @file{linux}, @file{asm} and
508@file{asm-generic} directories are required to compile programs using
509@theglibc{}; the other directories describe interfaces to the kernel but
510are not required if not compiling programs using those interfaces.
511You do not need to copy kernel headers if you did not specify an
512alternate kernel header source using @samp{--with-headers}.
513
514The Filesystem Hierarchy Standard for @gnulinuxsystems{} expects some
515components of the @glibcadj{} installation to be in
516@file{/lib} and some in @file{/usr/lib}. This is handled automatically
517if you configure @theglibc{} with @samp{--prefix=/usr}. If you set some other
518prefix or allow it to default to @file{/usr/local}, then all the
519components are installed there.
520
521@node Reporting Bugs
522@appendixsec Reporting Bugs
523@cindex reporting bugs
524@cindex bugs, reporting
525
526There are probably bugs in @theglibc{}. There are certainly
527errors and omissions in this manual. If you report them, they will get
528fixed. If you don't, no one will ever know about them and they will
529remain unfixed for all eternity, if not longer.
530
531It is a good idea to verify that the problem has not already been
532reported. Bugs are documented in two places: The file @file{BUGS}
533describes a number of well known bugs and the central @glibcadj{}
534bug tracking system has a
535WWW interface at
536@url{http://sourceware.org/bugzilla/}. The WWW
537interface gives you access to open and closed reports. A closed report
538normally includes a patch or a hint on solving the problem.
539
540To report a bug, first you must find it. With any luck, this will be the
541hard part. Once you've found a bug, make sure it's really a bug. A
542good way to do this is to see if @theglibc{} behaves the same way
543some other C library does. If so, probably you are wrong and the
544libraries are right (but not necessarily). If not, one of the libraries
545is probably wrong. It might not be @theglibc{}. Many historical
546Unix C libraries permit things that we don't, such as closing a file
547twice.
548
549If you think you have found some way in which @theglibc{} does not
550conform to the ISO and POSIX standards (@pxref{Standards and
551Portability}), that is definitely a bug. Report it!
552
553Once you're sure you've found a bug, try to narrow it down to the
554smallest test case that reproduces the problem. In the case of a C
555library, you really only need to narrow it down to one library
556function call, if possible. This should not be too difficult.
557
558The final step when you have a simple test case is to report the bug.
559Do this at @value{REPORT_BUGS_TO}.
560
561If you are not sure how a function should behave, and this manual
562doesn't tell you, that's a bug in the manual. Report that too! If the
563function's behavior disagrees with the manual, then either the library
564or the manual has a bug, so report the disagreement. If you find any
565errors or omissions in this manual, please report them to the
566bug database. If you refer to specific
567sections of the manual, please include the section names for easier
568identification.