1@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{https://sourceware.org/glibc/wiki/FAQ}. It answers common 13questions and describes problems you may experience with compilation 14and installation. 15 16You will need recent versions of several GNU tools: definitely GCC and 17GNU Make, and possibly others. @xref{Tools for Compilation}, below. 18 19@ifclear plain 20@menu 21* Configuring and compiling:: How to compile and test GNU libc. 22* Running make install:: How to install it once you've got it 23 compiled. 24* Tools for Compilation:: You'll need these first. 25* Linux:: Specific advice for GNU/Linux systems. 26* Reporting Bugs:: So they'll get fixed. 27@end menu 28@end ifclear 29 30@node Configuring and compiling 31@appendixsec Configuring and compiling @theglibc{} 32@cindex configuring 33@cindex compiling 34 35@Theglibc{} cannot be compiled in the source directory. You must build 36it in a separate build directory. For example, if you have unpacked 37the @glibcadj{} sources in @file{/src/gnu/glibc-@var{version}}, 38create a directory 39@file{/src/gnu/glibc-build} to put the object files in. This allows 40removing the whole build directory in case an error occurs, which is 41the safest way to get a fresh start and should always be done. 42 43From your object directory, run the shell script @file{configure} located 44at the top level of the source tree. In the scenario above, you'd type 45 46@smallexample 47$ ../glibc-@var{version}/configure @var{args@dots{}} 48@end smallexample 49 50Please note that even though you're building in a separate build 51directory, the compilation may need to create or modify files and 52directories in the source directory. 53 54@noindent 55@code{configure} takes many options, but the only one that is usually 56mandatory is @samp{--prefix}. This option tells @code{configure} 57where you want @theglibc{} installed. This defaults to @file{/usr/local}, 58but the normal setting to install as the standard system library is 59@samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an 60empty prefix) for @gnuhurdsystems{}. 61 62It may also be useful to pass @samp{CC=@var{compiler}} and 63@code{CFLAGS=@var{flags}} arguments to @code{configure}. @code{CC} 64selects the C compiler that will be used, and @code{CFLAGS} sets 65optimization options for the compiler. Any compiler options required 66for all compilations, such as options selecting an ABI or a processor 67for which to generate code, should be included in @code{CC}. Options 68that may be overridden by the @glibcadj{} build system for particular 69files, such as for optimization and debugging, should go in 70@code{CFLAGS}. The default value of @code{CFLAGS} is @samp{-g -O2}, 71and @theglibc{} cannot be compiled without optimization, so if 72@code{CFLAGS} is specified it must enable optimization. For example: 73 74@smallexample 75$ ../glibc-@var{version}/configure CC="gcc -m32" CFLAGS="-O3" 76@end smallexample 77 78The following list describes all of the available options for 79 @code{configure}: 80 81@table @samp 82@item --prefix=@var{directory} 83Install machine-independent data files in subdirectories of 84@file{@var{directory}}. The default is to install in @file{/usr/local}. 85 86@item --exec-prefix=@var{directory} 87Install the library and other machine-dependent files in subdirectories 88of @file{@var{directory}}. The default is to the @samp{--prefix} 89directory if that option is specified, or @file{/usr/local} otherwise. 90 91@item --with-headers=@var{directory} 92Look for kernel header files in @var{directory}, not 93@file{/usr/include}. @Theglibc{} needs information from the kernel's header 94files describing the interface to the kernel. @Theglibc{} will normally 95look in @file{/usr/include} for them, 96but if you specify this option, it will look in @var{DIRECTORY} instead. 97 98This option is primarily of use on a system where the headers in 99@file{/usr/include} come from an older version of @theglibc{}. Conflicts can 100occasionally happen in this case. You can also use this option if you want to 101compile @theglibc{} with a newer set of kernel headers than the ones found in 102@file{/usr/include}. 103 104@item --enable-kernel=@var{version} 105This option is currently only useful on @gnulinuxsystems{}. The 106@var{version} parameter should have the form X.Y.Z and describes the 107smallest version of the Linux kernel the generated library is expected 108to support. The higher the @var{version} number is, the less 109compatibility code is added, and the faster the code gets. 110 111@item --with-binutils=@var{directory} 112Use the binutils (assembler and linker) in @file{@var{directory}}, not 113the ones the C compiler would default to. You can use this option if 114the default binutils on your system cannot deal with all the constructs 115in @theglibc{}. In that case, @code{configure} will detect the 116problem and suppress these constructs, so that the library will still be 117usable, but functionality may be lost---for example, you can't build a 118shared libc with old binutils. 119 120@item --with-default-link 121With @code{--with-default-link}, the build system does not use a custom 122linker script for linking shared objects. The default is 123@code{--without-default-link}, because the custom linker script is 124needed for full RELRO protection. 125 126@item --with-nonshared-cflags=@var{cflags} 127Use additional compiler flags @var{cflags} to build the parts of the 128library which are always statically linked into applications and 129libraries even with shared linking (that is, the object files contained 130in @file{lib*_nonshared.a} libraries). The build process will 131automatically use the appropriate flags, but this option can be used to 132set additional flags required for building applications and libraries, 133to match local policy. For example, if such a policy requires that all 134code linked into applications must be built with source fortification, 135@samp{--with-nonshared-cflags=-Wp,-D_FORTIFY_SOURCE=2} will make sure 136that the objects in @file{libc_nonshared.a} are compiled with this flag 137(although this will not affect the generated code in this particular 138case and potentially change debugging information and metadata only). 139 140@item --with-rtld-early-cflags=@var{cflags} 141Use additional compiler flags @var{cflags} to build the early startup 142code of the dynamic linker. These flags can be used to enable early 143dynamic linker diagnostics to run on CPUs which are not compatible with 144the rest of @theglibc{}, for example, due to compiler flags which target 145a later instruction set architecture (ISA). 146 147@item --with-timeoutfactor=@var{NUM} 148Specify an integer @var{NUM} to scale the timeout of test programs. 149This factor can be changed at run time using @env{TIMEOUTFACTOR} 150environment variable. 151 152@c disable static doesn't work currently 153@c @item --disable-static 154@c Don't build static libraries. Static libraries aren't that useful these 155@c days, but we recommend you build them in case you need them. 156 157@item --disable-shared 158Don't build shared libraries even if it is possible. Not all systems 159support shared libraries; you need ELF support and (currently) the GNU 160linker. 161 162@item --disable-default-pie 163Don't build glibc programs and the testsuite as position independent 164executables (PIE). By default, glibc programs and tests are created as 165position independent executables on targets that support it. If the toolchain 166and architecture support it, static executables are built as static PIE and the 167resulting glibc can be used with the GCC option, -static-pie, which is 168available with GCC 8 or above, to create static PIE. 169 170@item --enable-cet 171@itemx --enable-cet=permissive 172Enable Intel Control-flow Enforcement Technology (CET) support. When 173@theglibc{} is built with @option{--enable-cet} or 174@option{--enable-cet=permissive}, the resulting library 175is protected with indirect branch tracking (IBT) and shadow stack 176(SHSTK)@. When CET is enabled, @theglibc{} is compatible with all 177existing executables and shared libraries. This feature is currently 178supported on i386, x86_64 and x32 with GCC 8 and binutils 2.29 or later. 179Note that when CET is enabled, @theglibc{} requires CPUs capable of 180multi-byte NOPs, like x86-64 processors as well as Intel Pentium Pro or 181newer. With @option{--enable-cet}, it is an error to dlopen a non CET 182enabled shared library in CET enabled application. With 183@option{--enable-cet=permissive}, CET is disabled when dlopening a 184non CET enabled shared library in CET enabled application. 185 186NOTE: @option{--enable-cet} has been tested for i686, x86_64 and x32 187on non-CET processors. @option{--enable-cet} has been tested for 188i686, x86_64 and x32 on CET processors. 189 190@item --enable-memory-tagging 191Enable memory tagging support if the architecture supports it. When 192@theglibc{} is built with this option then the resulting library will 193be able to control the use of tagged memory when hardware support is 194present by use of the tunable @samp{glibc.mem.tagging}. This includes 195the generation of tagged memory when using the @code{malloc} APIs. 196 197At present only AArch64 platforms with MTE provide this functionality, 198although the library will still operate (without memory tagging) on 199older versions of the architecture. 200 201The default is to disable support for memory tagging. 202 203@item --disable-profile 204Don't build libraries with profiling information. You may want to use 205this option if you don't plan to do profiling. 206 207@item --enable-static-nss 208Compile static versions of the NSS (Name Service Switch) libraries. 209This is not recommended because it defeats the purpose of NSS; a program 210linked statically with the NSS libraries cannot be dynamically 211reconfigured to use a different name database. 212 213@item --enable-hardcoded-path-in-tests 214By default, dynamic tests are linked to run with the installed C library. 215This option hardcodes the newly built C library path in dynamic tests 216so that they can be invoked directly. 217 218@item --disable-timezone-tools 219By default, timezone related utilities (@command{zic}, @command{zdump}, 220and @command{tzselect}) are installed with @theglibc{}. If you are building 221these independently (e.g. by using the @samp{tzcode} package), then this 222option will allow disabling the install of these. 223 224Note that you need to make sure the external tools are kept in sync with 225the versions that @theglibc{} expects as the data formats may change over 226time. Consult the @file{timezone} subdirectory for more details. 227 228@item --enable-stack-protector 229@itemx --enable-stack-protector=strong 230@itemx --enable-stack-protector=all 231Compile the C library and all other parts of the glibc package 232(including the threading and math libraries, NSS modules, and 233transliteration modules) using the GCC @option{-fstack-protector}, 234@option{-fstack-protector-strong} or @option{-fstack-protector-all} 235options to detect stack overruns. Only the dynamic linker and a small 236number of routines called directly from assembler are excluded from this 237protection. 238 239@item --enable-bind-now 240Disable lazy binding for installed shared objects and programs. This 241provides additional security hardening because it enables full RELRO 242and a read-only global offset table (GOT), at the cost of slightly 243increased program load times. 244 245@pindex pt_chown 246@findex grantpt 247@item --enable-pt_chown 248The file @file{pt_chown} is a helper binary for @code{grantpt} 249(@pxref{Allocation, Pseudo-Terminals}) that is installed setuid root to 250fix up pseudo-terminal ownership on GNU/Hurd. It is not required on 251GNU/Linux, and @theglibc{} will not use the installed @file{pt_chown} 252program when configured with @option{--enable-pt_chown}. 253 254@item --disable-werror 255By default, @theglibc{} is built with @option{-Werror}. If you wish 256to build without this option (for example, if building with a newer 257version of GCC than this version of @theglibc{} was tested with, so 258new warnings cause the build with @option{-Werror} to fail), you can 259configure with @option{--disable-werror}. 260 261@item --disable-mathvec 262By default for x86_64, @theglibc{} is built with the vector math library. 263Use this option to disable the vector math library. 264 265@item --enable-tunables 266Tunables support allows additional library parameters to be customized at 267runtime. This feature is enabled by default. This option can take the 268following values: 269 270@table @code 271@item yes 272This is the default if no option is passed to configure. This enables tunables 273and selects the default frontend (currently @samp{valstring}). 274 275@item no 276This option disables tunables. 277 278@item valstring 279This enables tunables and selects the @samp{valstring} frontend for tunables. 280This frontend allows users to specify tunables as a colon-separated list in a 281single environment variable @env{GLIBC_TUNABLES}. 282@end table 283 284@item --disable-crypt 285Do not install the passphrase-hashing library @file{libcrypt} or the 286header file @file{crypt.h}. @file{unistd.h} will still declare the 287function @code{crypt}. Using this option does not change the set of 288programs that may need to be linked with @option{-lcrypt}; it only 289means that @theglibc{} will not provide that library. 290 291This option is for hackers and distributions experimenting with 292independently-maintained implementations of libcrypt. It may become 293the default in a future release. 294 295@item --disable-experimental-malloc 296By default, a per-thread cache is enabled in @code{malloc}. While 297this cache can be disabled on a per-application basis using tunables 298(set glibc.malloc.tcache_count to zero), this option can be used to 299remove it from the build completely. 300 301@item --disable-scv 302Disable using @code{scv} instruction for syscalls. All syscalls will use 303@code{sc} instead, even if the kernel supports @code{scv}. PowerPC only. 304 305@item --build=@var{build-system} 306@itemx --host=@var{host-system} 307These options are for cross-compiling. If you specify both options and 308@var{build-system} is different from @var{host-system}, @code{configure} 309will prepare to cross-compile @theglibc{} from @var{build-system} to be used 310on @var{host-system}. You'll probably need the @samp{--with-headers} 311option too, and you may have to override @var{configure}'s selection of 312the compiler and/or binutils. 313 314If you only specify @samp{--host}, @code{configure} will prepare for a 315native compile but use what you specify instead of guessing what your 316system is. This is most useful to change the CPU submodel. For example, 317if @code{configure} guesses your machine as @code{i686-pc-linux-gnu} but 318you want to compile a library for 586es, give 319@samp{--host=i586-pc-linux-gnu} or just @samp{--host=i586-linux} and add 320the appropriate compiler flags (@samp{-mcpu=i586} will do the trick) to 321@code{CC}. 322 323If you specify just @samp{--build}, @code{configure} will get confused. 324 325@item --with-pkgversion=@var{version} 326Specify a description, possibly including a build number or build 327date, of the binaries being built, to be included in 328@option{--version} output from programs installed with @theglibc{}. 329For example, @option{--with-pkgversion='FooBar GNU/Linux glibc build 330123'}. The default value is @samp{GNU libc}. 331 332@item --with-bugurl=@var{url} 333Specify the URL that users should visit if they wish to report a bug, 334to be included in @option{--help} output from programs installed with 335@theglibc{}. The default value refers to the main bug-reporting 336information for @theglibc{}. 337@end table 338 339To build the library and related programs, type @code{make}. This will 340produce a lot of output, some of which may look like errors from 341@code{make} but aren't. Look for error messages from @code{make} 342containing @samp{***}. Those indicate that something is seriously wrong. 343 344The compilation process can take a long time, depending on the 345configuration and the speed of your machine. Some complex modules may 346take a very long time to compile, as much as several minutes on slower 347machines. Do not panic if the compiler appears to hang. 348 349If you want to run a parallel make, simply pass the @samp{-j} option 350with an appropriate numeric parameter to @code{make}. You need a recent 351GNU @code{make} version, though. 352 353To build and run test programs which exercise some of the library 354facilities, type @code{make check}. If it does not complete 355successfully, do not use the built library, and report a bug after 356verifying that the problem is not already known. @xref{Reporting Bugs}, 357for instructions on reporting bugs. Note that some of the tests assume 358they are not being run by @code{root}. We recommend you compile and 359test @theglibc{} as an unprivileged user. 360 361Before reporting bugs make sure there is no problem with your system. 362The tests (and later installation) use some pre-existing files of the 363system such as @file{/etc/passwd}, @file{/etc/nsswitch.conf} and others. 364These files must all contain correct and sensible content. 365 366Normally, @code{make check} will run all the tests before reporting 367all problems found and exiting with error status if any problems 368occurred. You can specify @samp{stop-on-test-failure=y} when running 369@code{make check} to make the test run stop and exit with an error 370status immediately when a failure occurs. 371 372To format the @cite{GNU C Library Reference Manual} for printing, type 373@w{@code{make dvi}}. You need a working @TeX{} installation to do 374this. The distribution builds the on-line formatted version of the 375manual, as Info files, as part of the build process. You can build 376them manually with @w{@code{make info}}. 377 378The library has a number of special-purpose configuration parameters 379which you can find in @file{Makeconfig}. These can be overwritten with 380the file @file{configparms}. To change them, create a 381@file{configparms} in your build directory and add values as appropriate 382for your system. The file is included and parsed by @code{make} and has 383to follow the conventions for makefiles. 384 385It is easy to configure @theglibc{} for cross-compilation by 386setting a few variables in @file{configparms}. Set @code{CC} to the 387cross-compiler for the target you configured the library for; it is 388important to use this same @code{CC} value when running 389@code{configure}, like this: @samp{configure @var{target} 390CC=@var{target}-gcc}. Set @code{BUILD_CC} to the compiler to use for programs 391run on the build system as part of compiling the library. You may need to 392set @code{AR} to cross-compiling versions of @code{ar} 393if the native tools are not configured to work with 394object files for the target you configured for. When cross-compiling 395@theglibc{}, it may be tested using @samp{make check 396test-wrapper="@var{srcdir}/scripts/cross-test-ssh.sh @var{hostname}"}, 397where @var{srcdir} is the absolute directory name for the main source 398directory and @var{hostname} is the host name of a system that can run 399the newly built binaries of @theglibc{}. The source and build 400directories must be visible at the same locations on both the build 401system and @var{hostname}. 402The @samp{cross-test-ssh.sh} script requires @samp{flock} from 403@samp{util-linux} to work when @var{glibc_test_allow_time_setting} 404environment variable is set. 405 406It is also possible to execute tests, which require setting the date on 407the target machine. Following use cases are supported: 408@itemize @bullet 409@item 410@code{GLIBC_TEST_ALLOW_TIME_SETTING} is set in the environment in 411which eligible tests are executed and have the privilege to run 412@code{clock_settime}. In this case, nothing prevents those tests from 413running in parallel, so the caller shall assure that those tests 414are serialized or provide a proper wrapper script for them. 415 416@item 417The @code{cross-test-ssh.sh} script is used and one passes the 418@option{--allow-time-setting} flag. In this case, both sets 419@code{GLIBC_TEST_ALLOW_TIME_SETTING} and serialization of test 420execution are assured automatically. 421@end itemize 422 423In general, when testing @theglibc{}, @samp{test-wrapper} may be set 424to the name and arguments of any program to run newly built binaries. 425This program must preserve the arguments to the binary being run, its 426working directory and the standard input, output and error file 427descriptors. If @samp{@var{test-wrapper} env} will not work to run a 428program with environment variables set, then @samp{test-wrapper-env} 429must be set to a program that runs a newly built program with 430environment variable assignments in effect, those assignments being 431specified as @samp{@var{var}=@var{value}} before the name of the 432program to be run. If multiple assignments to the same variable are 433specified, the last assignment specified must take precedence. 434Similarly, if @samp{@var{test-wrapper} env -i} will not work to run a 435program with an environment completely empty of variables except those 436directly assigned, then @samp{test-wrapper-env-only} must be set; its 437use has the same syntax as @samp{test-wrapper-env}, the only 438difference in its semantics being starting with an empty set of 439environment variables rather than the ambient set. 440 441For AArch64 with SVE, when testing @theglibc{}, @samp{test-wrapper} 442may be set to "@var{srcdir}/sysdeps/unix/sysv/linux/aarch64/vltest.py 443@var{vector-length}" to change Vector Length. 444 445@node Running make install 446@appendixsec Installing the C Library 447@cindex installing 448 449To install the library and its header files, and the Info files of the 450manual, type @code{make install}. This will 451build things, if necessary, before installing them; however, you should 452still compile everything first. If you are installing @theglibc{} as your 453primary C library, we recommend that you shut the system down to 454single-user mode first, and reboot afterward. This minimizes the risk 455of breaking things when the library changes out from underneath. 456 457@samp{make install} will do the entire job of upgrading from a 458previous installation of @theglibc{} version 2.x. There may sometimes 459be headers 460left behind from the previous installation, but those are generally 461harmless. If you want to avoid leaving headers behind you can do 462things in the following order. 463 464You must first build the library (@samp{make}), optionally check it 465(@samp{make check}), switch the include directories and then install 466(@samp{make install}). The steps must be done in this order. Not moving 467the directory before install will result in an unusable mixture of header 468files from both libraries, but configuring, building, and checking the 469library requires the ability to compile and run programs against the old 470library. The new @file{/usr/include}, after switching the include 471directories and before installing the library should contain the Linux 472headers, but nothing else. If you do this, you will need to restore 473any headers from libraries other than @theglibc{} yourself after installing the 474library. 475 476You can install @theglibc{} somewhere other than where you configured 477it to go by setting the @code{DESTDIR} GNU standard make variable on 478the command line for @samp{make install}. The value of this variable 479is prepended to all the paths for installation. This is useful when 480setting up a chroot environment or preparing a binary distribution. 481The directory should be specified with an absolute file name. Installing 482with the @code{prefix} and @code{exec_prefix} GNU standard make variables 483set is not supported. 484 485@Theglibc{} includes a daemon called @code{nscd}, which you 486may or may not want to run. @code{nscd} caches name service lookups; it 487can dramatically improve performance with NIS+, and may help with DNS as 488well. 489 490One auxiliary program, @file{/usr/libexec/pt_chown}, is installed setuid 491@code{root} if the @samp{--enable-pt_chown} configuration option is used. 492This program is invoked by the @code{grantpt} function; it sets the 493permissions on a pseudoterminal so it can be used by the calling process. 494If you are using a Linux kernel with the @code{devpts} filesystem enabled 495and mounted at @file{/dev/pts}, you don't need this program. 496 497After installation you should configure the timezone and install locales 498for your system. The time zone configuration ensures that your system 499time matches the time for your current timezone. The locales ensure that 500the display of information on your system matches the expectations of 501your language and geographic region. 502 503@Theglibc{} is able to use two kinds of localization information sources, the 504first is a locale database named @file{locale-archive} which is generally 505installed as @file{/usr/lib/locale/locale-archive}. The locale archive has the 506benefit of taking up less space and being very fast to load, but only if you 507plan to install sixty or more locales. If you plan to install one or two 508locales you can instead install individual locales into their self-named 509directories e.g.@: @file{/usr/lib/locale/en_US.utf8}. For example to install 510the German locale using the character set for UTF-8 with name @code{de_DE} into 511the locale archive issue the command @samp{localedef -i de_DE -f UTF-8 de_DE}, 512and to install just the one locale issue the command @samp{localedef 513--no-archive -i de_DE -f UTF-8 de_DE}. To configure all locales that are 514supported by @theglibc{}, you can issue from your build directory the command 515@samp{make localedata/install-locales} to install all locales into the locale 516archive or @samp{make localedata/install-locale-files} to install all locales 517as files in the default configured locale installation directory (derived from 518@samp{--prefix} or @code{--localedir}). To install into an alternative system 519root use @samp{DESTDIR} e.g.@: @samp{make localedata/install-locale-files 520DESTDIR=/opt/glibc}, but note that this does not change the configured prefix. 521 522To configure the locally used timezone, set the @code{TZ} environment 523variable. The script @code{tzselect} helps you to select the right value. 524As an example, for Germany, @code{tzselect} would tell you to use 525@samp{TZ='Europe/Berlin'}. For a system wide installation (the given 526paths are for an installation with @samp{--prefix=/usr}), link the 527timezone file which is in @file{/usr/share/zoneinfo} to the file 528@file{/etc/localtime}. For Germany, you might execute @samp{ln -s 529/usr/share/zoneinfo/Europe/Berlin /etc/localtime}. 530 531@node Tools for Compilation 532@appendixsec Recommended Tools for Compilation 533@cindex installation tools 534@cindex tools, for installing library 535 536We recommend installing the following GNU tools before attempting to 537build @theglibc{}: 538 539@itemize @bullet 540@item 541GNU @code{make} 4.0 or newer 542 543As of relase time, GNU @code{make} 4.3 is the newest verified to work 544to build @theglibc{}. 545 546@item 547GCC 6.2 or newer 548 549GCC 6.2 or higher is required. In general it is recommended to use 550the newest version of the compiler that is known to work for building 551@theglibc{}, as newer compilers usually produce better code. As of 552release time, GCC 12.1 is the newest compiler verified to work to build 553@theglibc{}. 554 555For PowerPC 64-bits little-endian (powerpc64le), a GCC version with support 556for @option{-mno-gnu-attribute}, @option{-mabi=ieeelongdouble}, and 557@option{-mabi=ibmlondouble} is required. Likewise, the compiler must also 558support passing @option{-mlong-double-128} with the preceding options. As 559of release, this implies GCC 7.4 and newer (excepting GCC 7.5.0, see GCC 560PR94200). These additional features are required for building the GNU C 561Library with support for IEEE long double. 562 563@c powerpc64le performs an autoconf test to verify the compiler compiles with 564@c commands like "$CC -c foo.c -mabi=ibmlongdouble -mlong-double-128". 565 566For ARC architecture builds, GCC 8.3 or higher is needed. 567 568For s390x architecture builds, GCC 7.1 or higher is needed (See gcc Bug 98269). 569 570For multi-arch support it is recommended to use a GCC which has been built with 571support for GNU indirect functions. This ensures that correct debugging 572information is generated for functions selected by IFUNC resolvers. This 573support can either be enabled by configuring GCC with 574@samp{--enable-gnu-indirect-function}, or by enabling it by default by setting 575@samp{default_gnu_indirect_function} variable for a particular architecture in 576the GCC source file @file{gcc/config.gcc}. 577 578You can use whatever compiler you like to compile programs that use 579@theglibc{}. 580 581Check the FAQ for any special compiler issues on particular platforms. 582 583@item 584GNU @code{binutils} 2.25 or later 585 586You must use GNU @code{binutils} (as and ld) to build @theglibc{}. 587No other assembler or linker has the necessary functionality at the 588moment. As of release time, GNU @code{binutils} 2.38 is the newest 589verified to work to build @theglibc{}. 590 591For PowerPC 64-bits little-endian (powerpc64le), @command{objcopy} is required 592to support @option{--update-section}. This option requires binutils 2.26 or 593newer. 594 595ARC architecture needs @code{binutils} 2.32 or higher for TLS related fixes. 596 597@item 598GNU @code{texinfo} 4.7 or later 599 600To correctly translate and install the Texinfo documentation you need 601this version of the @code{texinfo} package. Earlier versions do not 602understand all the tags used in the document, and the installation 603mechanism for the info files is not present or works differently. 604As of release time, @code{texinfo} 6.8 is the newest verified to work 605to build @theglibc{}. 606 607@item 608GNU @code{awk} 3.1.2, or higher 609 610@code{awk} is used in several places to generate files. 611Some @code{gawk} extensions are used, including the @code{asorti} 612function, which was introduced in version 3.1.2 of @code{gawk}. 613As of release time, @code{gawk} version 5.1.1 is the newest verified 614to work to build @theglibc{}. 615 616@item 617GNU @code{bison} 2.7 or later 618 619@code{bison} is used to generate the @code{yacc} parser code in the @file{intl} 620subdirectory. As of release time, @code{bison} version 3.8.2 is the newest 621verified to work to build @theglibc{}. 622 623@item 624Perl 5 625 626Perl is not required, but if present it is used in some tests and the 627@code{mtrace} program, to build the @glibcadj{} manual. As of release 628time @code{perl} version 5.34.1 is the newest verified to work to 629build @theglibc{}. 630 631@item 632GNU @code{sed} 3.02 or newer 633 634@code{Sed} is used in several places to generate files. Most scripts work 635with any version of @code{sed}. As of release time, @code{sed} version 6364.8 is the newest verified to work to build @theglibc{}. 637 638@item 639Python 3.4 or later 640 641Python is required to build @theglibc{}. As of release time, Python 6423.10.5 is the newest verified to work for building and testing 643@theglibc{}. 644 645@item PExpect 4.0 646 647The pretty printer tests drive GDB through test programs and compare 648its output to the printers'. PExpect is used to capture the output of 649GDB, and should be compatible with the Python version in your system. 650As of release time PExpect 4.8.0 is the newest verified to work to test 651the pretty printers. 652 653@item 654GDB 7.8 or later with support for Python 2.7/3.4 or later 655 656GDB itself needs to be configured with Python support in order to use 657the pretty printers. Notice that your system having Python available 658doesn't imply that GDB supports it, nor that your system's Python and 659GDB's have the same version. As of release time GNU @code{debugger} 66012.1 is the newest verified to work to test the pretty printers. 661 662Unless Python, PExpect and GDB with Python support are present, the 663printer tests will report themselves as @code{UNSUPPORTED}. Notice 664that some of the printer tests require @theglibc{} to be compiled with 665debugging symbols. 666@end itemize 667 668@noindent 669If you change any of the @file{configure.ac} files you will also need 670 671@itemize @bullet 672@item 673GNU @code{autoconf} 2.69 (exactly) 674@end itemize 675 676@noindent 677and if you change any of the message translation files you will need 678 679@itemize @bullet 680@item 681GNU @code{gettext} 0.10.36 or later 682 683As of release time, GNU @code{gettext} version 0.21 is the newest 684version verified to work to build @theglibc{}. 685@end itemize 686 687 688@noindent 689You may also need these packages if you upgrade your source tree using 690patches, although we try to avoid this. 691 692@node Linux 693@appendixsec Specific advice for @gnulinuxsystems{} 694@cindex kernel header files 695 696If you are installing @theglibc{} on @gnulinuxsystems{}, you need to have 697the header files from a 3.2 or newer kernel around for reference. 698(For the ia64 architecture, you need version 3.2.18 or newer because this 699is the first version with support for the @code{accept4} system call.) 700These headers must be installed using @samp{make headers_install}; the 701headers present in the kernel source directory are not suitable for 702direct use by @theglibc{}. You do not need to use that kernel, just have 703its headers installed where @theglibc{} can access them, referred to here as 704@var{install-directory}. The easiest way to do this is to unpack it 705in a directory such as @file{/usr/src/linux-@var{version}}. In that 706directory, run @samp{make headers_install 707INSTALL_HDR_PATH=@var{install-directory}}. Finally, configure @theglibc{} 708with the option @samp{--with-headers=@var{install-directory}/include}. 709Use the most recent kernel you can get your hands on. (If you are 710cross-compiling @theglibc{}, you need to specify 711@samp{ARCH=@var{architecture}} in the @samp{make headers_install} 712command, where @var{architecture} is the architecture name used by the 713Linux kernel, such as @samp{x86} or @samp{powerpc}.) 714 715After installing @theglibc{}, you may need to remove or rename 716directories such as @file{/usr/include/linux} and 717@file{/usr/include/asm}, and replace them with copies of directories 718such as @file{linux} and @file{asm} from 719@file{@var{install-directory}/include}. All directories present in 720@file{@var{install-directory}/include} should be copied, except that 721@theglibc{} provides its own version of @file{/usr/include/scsi}; the 722files provided by the kernel should be copied without replacing those 723provided by @theglibc{}. The @file{linux}, @file{asm} and 724@file{asm-generic} directories are required to compile programs using 725@theglibc{}; the other directories describe interfaces to the kernel but 726are not required if not compiling programs using those interfaces. 727You do not need to copy kernel headers if you did not specify an 728alternate kernel header source using @samp{--with-headers}. 729 730The Filesystem Hierarchy Standard for @gnulinuxsystems{} expects some 731components of the @glibcadj{} installation to be in 732@file{/lib} and some in @file{/usr/lib}. This is handled automatically 733if you configure @theglibc{} with @samp{--prefix=/usr}. If you set some other 734prefix or allow it to default to @file{/usr/local}, then all the 735components are installed there. 736 737As of release time, Linux version 5.18 is the newest stable version verified 738to work to build @theglibc{}. 739 740@node Reporting Bugs 741@appendixsec Reporting Bugs 742@cindex reporting bugs 743@cindex bugs, reporting 744 745There are probably bugs in @theglibc{}. There are certainly 746errors and omissions in this manual. If you report them, they will get 747fixed. If you don't, no one will ever know about them and they will 748remain unfixed for all eternity, if not longer. 749 750It is a good idea to verify that the problem has not already been 751reported. Bugs are documented in two places: The file @file{BUGS} 752describes a number of well known bugs and the central @glibcadj{} 753bug tracking system has a 754WWW interface at 755@url{https://sourceware.org/bugzilla/}. The WWW 756interface gives you access to open and closed reports. A closed report 757normally includes a patch or a hint on solving the problem. 758 759To report a bug, first you must find it. With any luck, this will be the 760hard part. Once you've found a bug, make sure it's really a bug. A 761good way to do this is to see if @theglibc{} behaves the same way 762some other C library does. If so, probably you are wrong and the 763libraries are right (but not necessarily). If not, one of the libraries 764is probably wrong. It might not be @theglibc{}. Many historical 765Unix C libraries permit things that we don't, such as closing a file 766twice. 767 768If you think you have found some way in which @theglibc{} does not 769conform to the ISO and POSIX standards (@pxref{Standards and 770Portability}), that is definitely a bug. Report it! 771 772Once you're sure you've found a bug, try to narrow it down to the 773smallest test case that reproduces the problem. In the case of a C 774library, you really only need to narrow it down to one library 775function call, if possible. This should not be too difficult. 776 777The final step when you have a simple test case is to report the bug. 778Do this at @value{REPORT_BUGS_TO}. 779 780If you are not sure how a function should behave, and this manual 781doesn't tell you, that's a bug in the manual. Report that too! If the 782function's behavior disagrees with the manual, then either the library 783or the manual has a bug, so report the disagreement. If you find any 784errors or omissions in this manual, please report them to the 785bug database. If you refer to specific 786sections of the manual, please include the section names for easier 787identification. 788