path: root/manual/install.texi

@include macros.texi
@include pkgvers.texi

@ifclear plain
@node Installation, Maintenance, Library Summary, Top
@end ifclear

@c %MENU% How to install the GNU C Library
@appendix Installing @theglibc{}

Before you do anything else, you should read the FAQ at
@url{https://sourceware.org/glibc/wiki/FAQ}.  It answers common
questions and describes problems you may experience with compilation
and installation.

You will need recent versions of several GNU tools: definitely GCC and
GNU Make, and possibly others.  @xref{Tools for Compilation}, below.

@ifclear plain
@menu
* Configuring and compiling::   How to compile and test GNU libc.
* Running make install::        How to install it once you've got it
 compiled.
* Tools for Compilation::       You'll need these first.
* Linux::                       Specific advice for GNU/Linux systems.
* Reporting Bugs::              So they'll get fixed.
@end menu
@end ifclear

@node Configuring and compiling
@appendixsec Configuring and compiling @theglibc{}
@cindex configuring
@cindex compiling

@Theglibc{} cannot be compiled in the source directory.  You must build
it in a separate build directory.  For example, if you have unpacked
the @glibcadj{} sources in @file{/src/gnu/glibc-@var{version}},
create a directory
@file{/src/gnu/glibc-build} to put the object files in.  This allows
removing the whole build directory in case an error occurs, which is
the safest way to get a fresh start and should always be done.

From your object directory, run the shell script @file{configure} located
at the top level of the source tree.  In the scenario above, you'd type

@smallexample
$ ../glibc-@var{version}/configure @var{args@dots{}}
@end smallexample

Please note that even though you're building in a separate build
directory, the compilation may need to create or modify files and
directories in the source directory.

@noindent
@code{configure} takes many options, but the only one that is usually
mandatory is @samp{--prefix}.  This option tells @code{configure}
where you want @theglibc{} installed.  This defaults to @file{/usr/local},
but the normal setting to install as the standard system library is
@samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an
empty prefix) for @gnuhurdsystems{}.

It may also be useful to pass @samp{CC=@var{compiler}} and
@code{CFLAGS=@var{flags}} arguments to @code{configure}.  @code{CC}
selects the C compiler that will be used, and @code{CFLAGS} sets
optimization options for the compiler.  Any compiler options required
for all compilations, such as options selecting an ABI or a processor
for which to generate code, should be included in @code{CC}.  Options
that may be overridden by the @glibcadj{} build system for particular
files, such as for optimization and debugging, should go in
@code{CFLAGS}.  The default value of @code{CFLAGS} is @samp{-g -O2},
and @theglibc{} cannot be compiled without optimization, so if
@code{CFLAGS} is specified it must enable optimization.  For example:

@smallexample
$ ../glibc-@var{version}/configure CC="gcc -m32" CFLAGS="-O3"
@end smallexample

The following list describes all of the available options for
 @code{configure}:

@table @samp
@item --prefix=@var{directory}
Install machine-independent data files in subdirectories of
@file{@var{directory}}.  The default is to install in @file{/usr/local}.

@item --exec-prefix=@var{directory}
Install the library and other machine-dependent files in subdirectories
of @file{@var{directory}}.  The default is to the @samp{--prefix}
directory if that option is specified, or @file{/usr/local} otherwise.

@item --with-headers=@var{directory}
Look for kernel header files in @var{directory}, not
@file{/usr/include}.  @Theglibc{} needs information from the kernel's header
files describing the interface to the kernel.  @Theglibc{} will normally
look in @file{/usr/include} for them,
but if you specify this option, it will look in @var{DIRECTORY} instead.

This option is primarily of use on a system where the headers in
@file{/usr/include} come from an older version of @theglibc{}.  Conflicts can
occasionally happen in this case.  You can also use this option if you want to
compile @theglibc{} with a newer set of kernel headers than the ones found in
@file{/usr/include}.

@item --enable-kernel=@var{version}
This option is currently only useful on @gnulinuxsystems{}.  The
@var{version} parameter should have the form X.Y.Z and describes the
smallest version of the Linux kernel the generated library is expected
to support.  The higher the @var{version} number is, the less
compatibility code is added, and the faster the code gets.

@item --with-binutils=@var{directory}
Use the binutils (assembler and linker) in @file{@var{directory}}, not
the ones the C compiler would default to.  You can use this option if
the default binutils on your system cannot deal with all the constructs
in @theglibc{}.  In that case, @code{configure} will detect the
problem and suppress these constructs, so that the library will still be
usable, but functionality may be lost---for example, you can't build a
shared libc with old binutils.

@item --with-nonshared-cflags=@var{cflags}
Use additional compiler flags @var{cflags} to build the parts of the
library which are always statically linked into applications and
libraries even with shared linking (that is, the object files contained
in @file{lib*_nonshared.a} libraries).  The build process will
automatically use the appropriate flags, but this option can be used to
set additional flags required for building applications and libraries,
to match local policy.  For example, if such a policy requires that all
code linked into applications must be built with source fortification,
@samp{--with-nonshared-cflags=-Wp,-D_FORTIFY_SOURCE=2} will make sure
that the objects in @file{libc_nonshared.a} are compiled with this flag
(although this will not affect the generated code in this particular
case and potentially change debugging information and metadata only).

@c disable static doesn't work currently
@c @item --disable-static
@c Don't build static libraries.  Static libraries aren't that useful these
@c days, but we recommend you build them in case you need them.

@item --disable-shared
Don't build shared libraries even if it is possible.  Not all systems
support shared libraries; you need ELF support and (currently) the GNU
linker.

@item --enable-static-pie
Enable static position independent executable (static PIE) support.
Static PIE is similar to static executable, but can be loaded at any
address without help from a dynamic linker.  All static programs as
well as static tests are built as static PIE, except for those marked
with no-pie.  The resulting glibc can be used with the GCC option,
-static-pie, which is available with GCC 8 or above, to create static
PIE.  This option also implies that glibc programs and tests are created
as dynamic position independent executables (PIE) by default.

@item --enable-cet
@itemx --enable-cet=permissive
Enable Intel Control-flow Enforcement Technology (CET) support.  When
@theglibc{} is built with @option{--enable-cet} or
@option{--enable-cet=permissive}, the resulting library
is protected with indirect branch tracking (IBT) and shadow stack
(SHSTK)@.  When CET is enabled, @theglibc{} is compatible with all
existing executables and shared libraries.  This feature is currently
supported on i386, x86_64 and x32 with GCC 8 and binutils 2.29 or later.
Note that when CET is enabled, @theglibc{} requires CPUs capable of
multi-byte NOPs, like x86-64 processors as well as Intel Pentium Pro or
newer.  With @option{--enable-cet}, it is an error to dlopen a non CET
enabled shared library in CET enabled application.  With
@option{--enable-cet=permissive}, CET is disabled when dlopening a
non CET enabled shared library in CET enabled application.

NOTE: @option{--enable-cet} has been tested for i686, x86_64 and x32
on non-CET processors.  @option{--enable-cet} has been tested for
i686, x86_64 and x32 on CET processors.

@item --enable-memory-tagging
Enable memory tagging support if the architecture supports it.  When
@theglibc{} is built with this option then the resulting library will
be able to control the use of tagged memory when hardware support is
present by use of the tunable @samp{glibc.mem.tagging}.  This includes
the generation of tagged memory when using the @code{malloc} APIs.

At present only AArch64 platforms with MTE provide this functionality,
although the library will still operate (without memory tagging) on
older versions of the architecture.

The default is to disable support for memory tagging.

@item --disable-profile
Don't build libraries with profiling information.  You may want to use
this option if you don't plan to do profiling.

@item --enable-static-nss
Compile static versions of the NSS (Name Service Switch) libraries.
This is not recommended because it defeats the purpose of NSS; a program
linked statically with the NSS libraries cannot be dynamically
reconfigured to use a different name database.

@item --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.

@item --disable-timezone-tools
By default, timezone related utilities (@command{zic}, @command{zdump},
and @command{tzselect}) are installed with @theglibc{}.  If you are building
these independently (e.g. by using the @samp{tzcode} package), then this
option will allow disabling the install of these.

Note that you need to make sure the external tools are kept in sync with
the versions that @theglibc{} expects as the data formats may change over
time.  Consult the @file{timezone} subdirectory for more details.

@item --enable-stack-protector
@itemx --enable-stack-protector=strong
@itemx --enable-stack-protector=all
Compile the C library and all other parts of the glibc package
(including the threading and math libraries, NSS modules, and
transliteration modules) using the GCC @option{-fstack-protector},
@option{-fstack-protector-strong} or @option{-fstack-protector-all}
options to detect stack overruns.  Only the dynamic linker and a small
number of routines called directly from assembler are excluded from this
protection.

@item --enable-bind-now
Disable lazy binding for installed shared objects and programs.  This
provides additional security hardening because it enables full RELRO
and a read-only global offset table (GOT), at the cost of slightly
increased program load times.

@pindex pt_chown
@findex grantpt
@item --enable-pt_chown
The file @file{pt_chown} is a helper binary for @code{grantpt}
(@pxref{Allocation, Pseudo-Terminals}) that is installed setuid root to
fix up pseudo-terminal ownership on GNU/Hurd.  It is not required on
GNU/Linux, and @theglibc{} will not use the installed @file{pt_chown}
program when configured with @option{--enable-pt_chown}.

@item --disable-werror
By default, @theglibc{} is built with @option{-Werror}.  If you wish
to build without this option (for example, if building with a newer
version of GCC than this version of @theglibc{} was tested with, so
new warnings cause the build with @option{-Werror} to fail), you can
configure with @option{--disable-werror}.

@item --disable-mathvec
By default for x86_64, @theglibc{} is built with the vector math library.
Use this option