diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 583 |
1 files changed, 0 insertions, 583 deletions
diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 920c4df0ef..0000000000 --- a/INSTALL +++ /dev/null @@ -1,583 +0,0 @@ -Installing the GNU C Library -**************************** - -Before you do anything else, you should read the FAQ at -<http://sourceware.org/glibc/wiki/FAQ>. It answers common questions and -describes problems you may experience with compilation and installation. - - Features can be added to the GNU C Library via "add-on" bundles. -These are separate tar files, which you unpack into the top level of the -source tree. Then you give 'configure' the '--enable-add-ons' option to -activate them, and they will be compiled into the library. - - You will need recent versions of several GNU tools: definitely GCC -and GNU Make, and possibly others. *Note Tools for Compilation::, -below. - -Configuring and compiling the GNU C Library -=========================================== - -The GNU C Library cannot be compiled in the source directory. You must -build it in a separate build directory. For example, if you have -unpacked the GNU C Library sources in '/src/gnu/glibc-VERSION', create a -directory '/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 'configure' located -at the top level of the source tree. In the scenario above, you'd type - - $ ../glibc-VERSION/configure ARGS... - - 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. - -'configure' takes many options, but the only one that is usually -mandatory is '--prefix'. This option tells 'configure' where you want -the GNU C Library installed. This defaults to '/usr/local', but the -normal setting to install as the standard system library is -'--prefix=/usr' for GNU/Linux systems and '--prefix=' (an empty prefix) -for GNU/Hurd systems. - - It may also be useful to set the CC and CFLAGS variables in the -environment when running 'configure'. CC selects the C compiler that -will be used, and CFLAGS sets optimization options for the compiler. - - The following list describes all of the available options for -'configure': - -'--prefix=DIRECTORY' - Install machine-independent data files in subdirectories of - 'DIRECTORY'. The default is to install in '/usr/local'. - -'--exec-prefix=DIRECTORY' - Install the library and other machine-dependent files in - subdirectories of 'DIRECTORY'. The default is to the '--prefix' - directory if that option is specified, or '/usr/local' otherwise. - -'--with-headers=DIRECTORY' - Look for kernel header files in DIRECTORY, not '/usr/include'. The - GNU C Library needs information from the kernel's header files - describing the interface to the kernel. The GNU C Library will - normally look in '/usr/include' for them, but if you specify this - option, it will look in DIRECTORY instead. - - This option is primarily of use on a system where the headers in - '/usr/include' come from an older version of the GNU C Library. - Conflicts can occasionally happen in this case. You can also use - this option if you want to compile the GNU C Library with a newer - set of kernel headers than the ones found in '/usr/include'. - -'--enable-add-ons[=LIST]' - Specify add-on packages to include in the build. If this option is - specified with no list, it enables all the add-on packages it finds - in the main source directory; this is the default behavior. You - may specify an explicit list of add-ons to use in LIST, separated - by spaces or commas (if you use spaces, remember to quote them from - the shell). Each add-on in LIST can be an absolute directory name - or can be a directory name relative to the main source directory, - or relative to the build directory (that is, the current working - directory). For example, - '--enable-add-ons=nptl,../glibc-libidn-VERSION'. - -'--enable-kernel=VERSION' - This option is currently only useful on GNU/Linux systems. The - 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 VERSION number is, the less - compatibility code is added, and the faster the code gets. - -'--with-binutils=DIRECTORY' - Use the binutils (assembler and linker) in '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 the GNU C Library. In that case, '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. - -'--without-fp' - Use this option if your computer lacks hardware floating-point - support and your operating system does not emulate an FPU. - -'--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. - -'--disable-profile' - Don't build libraries with profiling information. You may want to - use this option if you don't plan to do profiling. - -'--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. - -'--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. - -'--disable-timezone-tools' - By default, timezone related utilities ('zic', 'zdump', and - 'tzselect') are installed with the GNU C Library. If you are - building these independently (e.g. by using the '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 the GNU C Library expects as the data - formats may change over time. Consult the 'timezone' subdirectory - for more details. - -'--enable-lock-elision=yes' - Enable lock elision for pthread mutexes by default. - -'--enable-stack-protector' -'--enable-stack-protector=strong' -'--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 '-fstack-protector', - '-fstack-protector-strong' or '-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. - -'--enable-bind-now' - Disable lazy binding for installed shared objects. 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. - -'--enable-pt_chown' - The file 'pt_chown' is a helper binary for 'grantpt' (*note - Pseudo-Terminals: Allocation.) that is installed setuid root to fix - up pseudo-terminal ownership. It is not built by default because - systems using the Linux kernel are commonly built with the 'devpts' - filesystem enabled and mounted at '/dev/pts', which manages - pseudo-terminal ownership automatically. By using - '--enable-pt_chown', you may build 'pt_chown' and install it setuid - and owned by 'root'. The use of 'pt_chown' introduces additional - security risks to the system and you should enable it only if you - understand and accept those risks. - -'--disable-werror' - By default, the GNU C Library is built with '-Werror'. If you wish - to build without this option (for example, if building with a newer - version of GCC than this version of the GNU C Library was tested - with, so new warnings cause the build with '-Werror' to fail), you - can configure with '--disable-werror'. - -'--disable-mathvec' - By default for x86_64, the GNU C Library is built with the vector - math library. Use this option to disable the vector math library. - -'--enable-tunables' - Tunables support allows additional library parameters to be - customized at runtime. This is an experimental feature and affects - startup time and is thus disabled by default. This option can take - the following values: - - 'no' - This is the default if the option is not passed to configure. - This disables tunables. - - 'yes' - This is the default if the option is passed to configure. - This enables tunables and selects the default frontend - (currently 'valstring'). - - 'valstring' - This enables tunables and selects the 'valstring' frontend for - tunables. This frontend allows users to specify tunables as a - colon-separated list in a single environment variable - 'GLIBC_TUNABLES'. - -'--enable-obsolete-nsl' - By default, libnsl is only built as shared library for backward - compatibility and the NSS modules libnss_compat, libnss_nis and - libnss_nisplus are not built at all. Use this option to enable - libnsl with all depending NSS modules and header files. - -'--build=BUILD-SYSTEM' -'--host=HOST-SYSTEM' - These options are for cross-compiling. If you specify both options - and BUILD-SYSTEM is different from HOST-SYSTEM, 'configure' will - prepare to cross-compile the GNU C Library from BUILD-SYSTEM to be - used on HOST-SYSTEM. You'll probably need the '--with-headers' - option too, and you may have to override CONFIGURE's selection of - the compiler and/or binutils. - - If you only specify '--host', 'configure' will prepare for a native - compile but use what you specify instead of guessing what your - system is. This is most useful to change the CPU submodel. For - example, if 'configure' guesses your machine as 'i686-pc-linux-gnu' - but you want to compile a library for 586es, give - '--host=i586-pc-linux-gnu' or just '--host=i586-linux' and add the - appropriate compiler flags ('-mcpu=i586' will do the trick) to - CFLAGS. - - If you specify just '--build', 'configure' will get confused. - -'--with-pkgversion=VERSION' - Specify a description, possibly including a build number or build - date, of the binaries being built, to be included in '--version' - output from programs installed with the GNU C Library. For - example, '--with-pkgversion='FooBar GNU/Linux glibc build 123''. - The default value is 'GNU libc'. - -'--with-bugurl=URL' - Specify the URL that users should visit if they wish to report a - bug, to be included in '--help' output from programs installed with - the GNU C Library. The default value refers to the main - bug-reporting information for the GNU C Library. - - To build the library and related programs, type 'make'. This will -produce a lot of output, some of which may look like errors from 'make' -but aren't. Look for error messages from 'make' containing '***'. -Those indicate that something is seriously wrong. - - The compilation process can take a long time, depending on the -configuration and the speed of your machine. Some complex modules may -take a very long time to compile, as much as several minutes on slower -machines. Do not panic if the compiler appears to hang. - - If you want to run a parallel make, simply pass the '-j' option with -an appropriate numeric parameter to 'make'. You need a recent GNU -'make' version, though. - - To build and run test programs which exercise some of the library -facilities, type 'make check'. If it does not complete successfully, do -not use the built library, and report a bug after verifying that the -problem is not already known. *Note Reporting Bugs::, for instructions -on reporting bugs. Note that some of the tests assume they are not -being run by 'root'. We recommend you compile and test the GNU C -Library as an unprivileged user. - - Before reporting bugs make sure there is no problem with your system. -The tests (and later installation) use some pre-existing files of the -system such as '/etc/passwd', '/etc/nsswitch.conf' and others. These -files must all contain correct and sensible content. - - Normally, 'make check' will run all the tests before reporting all -problems found and exiting with error status if any problems occurred. -You can specify 'stop-on-test-failure=y' when running 'make check' to -make the test run stop and exit with an error status immediately when a -failure occurs. - - The GNU C Library pretty printers come with their own set of scripts -for testing, which run together with the rest of the testsuite through -'make check'. These scripts require the following tools to run -successfully: - - * Python 2.7.6/3.4.3 or later - - Python is required for running the printers' test scripts. - - * PExpect 4.0 - - The printer tests drive GDB through test programs and compare its - output to the printers'. PExpect is used to capture the output of - GDB, and should be compatible with the Python version in your - system. - - * GDB 7.8 or later with support for Python 2.7.6/3.4.3 or later - - GDB itself needs to be configured with Python support in order to - use the pretty printers. Notice that your system having Python - available doesn't imply that GDB supports it, nor that your - system's Python and GDB's have the same version. - -If these tools are absent, the printer tests will report themselves as -'UNSUPPORTED'. Notice that some of the printer tests require the GNU C -Library to be compiled with debugging symbols. - - To format the 'GNU C Library Reference Manual' for printing, type -'make dvi'. You need a working TeX installation to do this. The -distribution builds the on-line formatted version of the manual, as Info -files, as part of the build process. You can build them manually with -'make info'. - - The library has a number of special-purpose configuration parameters -which you can find in 'Makeconfig'. These can be overwritten with the -file 'configparms'. To change them, create a 'configparms' in your -build directory and add values as appropriate for your system. The file -is included and parsed by 'make' and has to follow the conventions for -makefiles. - - It is easy to configure the GNU C Library for cross-compilation by -setting a few variables in 'configparms'. Set 'CC' to the -cross-compiler for the target you configured the library for; it is -important to use this same 'CC' value when running 'configure', like -this: 'CC=TARGET-gcc configure TARGET'. Set 'BUILD_CC' to the compiler -to use for programs run on the build system as part of compiling the -library. You may need to set 'AR' to cross-compiling versions of 'ar' -if the native tools are not configured to work with object files for the -target you configured for. When cross-compiling the GNU C Library, it -may be tested using 'make check -test-wrapper="SRCDIR/scripts/cross-test-ssh.sh HOSTNAME"', where SRCDIR -is the absolute directory name for the main source directory and -HOSTNAME is the host name of a system that can run the newly built -binaries of the GNU C Library. The source and build directories must be -visible at the same locations on both the build system and HOSTNAME. - - In general, when testing the GNU C Library, 'test-wrapper' may be set -to the name and arguments of any program to run newly built binaries. -This program must preserve the arguments to the binary being run, its -working directory and the standard input, output and error file -descriptors. If 'TEST-WRAPPER env' will not work to run a program with -environment variables set, then 'test-wrapper-env' must be set to a -program that runs a newly built program with environment variable -assignments in effect, those assignments being specified as 'VAR=VALUE' -before the name of the program to be run. If multiple assignments to -the same variable are specified, the last assignment specified must take -precedence. Similarly, if 'TEST-WRAPPER env -i' will not work to run a -program with an environment completely empty of variables except those -directly assigned, then 'test-wrapper-env-only' must be set; its use has -the same syntax as 'test-wrapper-env', the only difference in its -semantics being starting with an empty set of environment variables -rather than the ambient set. - -Installing the C Library -======================== - -To install the library and its header files, and the Info files of the -manual, type 'make install'. This will build things, if necessary, -before installing them; however, you should still compile everything -first. If you are installing the GNU C Library as your primary C -library, we recommend that you shut the system down to single-user mode -first, and reboot afterward. This minimizes the risk of breaking things -when the library changes out from underneath. - - 'make install' will do the entire job of upgrading from a previous -installation of the GNU C Library version 2.x. There may sometimes be -headers left behind from the previous installation, but those are -generally harmless. If you want to avoid leaving headers behind you can -do things in the following order. - - You must first build the library ('make'), optionally check it ('make -check'), switch the include directories and then install ('make -install'). The steps must be done in this order. Not moving the -directory before install will result in an unusable mixture of header -files from both libraries, but configuring, building, and checking the -library requires the ability to compile and run programs against the old -library. The new '/usr/include', after switching the include -directories and before installing the library should contain the Linux -headers, but nothing else. If you do this, you will need to restore any -headers from libraries other than the GNU C Library yourself after -installing the library. - - You can install the GNU C Library somewhere other than where you -configured it to go by setting the 'DESTDIR' GNU standard make variable -on the command line for 'make install'. The value of this variable is -prepended to all the paths for installation. This is useful when -setting up a chroot environment or preparing a binary distribution. The -directory should be specified with an absolute file name. Installing -with the 'prefix' and 'exec_prefix' GNU standard make variables set is -not supported. - - The GNU C Library includes a daemon called 'nscd', which you may or -may not want to run. 'nscd' caches name service lookups; it can -dramatically improve performance with NIS+, and may help with DNS as -well. - - One auxiliary program, '/usr/libexec/pt_chown', is installed setuid -'root' if the '--enable-pt_chown' configuration option is used. This -program is invoked by the 'grantpt' function; it sets the permissions on -a pseudoterminal so it can be used by the calling process. If you are -using a Linux kernel with the 'devpts' filesystem enabled and mounted at -'/dev/pts', you don't need this program. - - After installation you might want to configure the timezone and -locale installation of your system. The GNU C Library comes with a -locale database which gets configured with 'localedef'. For example, to -set up a German locale with name 'de_DE', simply issue the command -'localedef -i de_DE -f ISO-8859-1 de_DE'. To configure all locales that -are supported by the GNU C Library, you can issue from your build -directory the command 'make localedata/install-locales'. - - To configure the locally used timezone, set the 'TZ' environment -variable. The script 'tzselect' helps you to select the right value. -As an example, for Germany, 'tzselect' would tell you to use -'TZ='Europe/Berlin''. For a system wide installation (the given paths -are for an installation with '--prefix=/usr'), link the timezone file -which is in '/usr/share/zoneinfo' to the file '/etc/localtime'. For -Germany, you might execute 'ln -s /usr/share/zoneinfo/Europe/Berlin -/etc/localtime'. - -Recommended Tools for Compilation -================================= - -We recommend installing the following GNU tools before attempting to -build the GNU C Library: - - * GNU 'make' 3.79 or newer - - You need the latest version of GNU 'make'. Modifying the GNU C - Library to work with other 'make' programs would be so difficult - that we recommend you port GNU 'make' instead. *Really.* We - recommend GNU 'make' version 3.79. All earlier versions have - severe bugs or lack features. - - * GCC 4.7 or newer - - GCC 4.7 or higher is required. In general it is recommended to use - the newest version of the compiler that is known to work for - building the GNU C Library, as newer compilers usually produce - better code. As of release time, GCC 6.3 is the newest compiler - verified to work to build the GNU C Library. - - For multi-arch support it is recommended to use a GCC which has - been built with support for GNU indirect functions. This ensures - that correct debugging information is generated for functions - selected by IFUNC resolvers. This support can either be enabled by - configuring GCC with '--enable-gnu-indirect-function', or by - enabling it by default by setting 'default_gnu_indirect_function' - variable for a particular architecture in the GCC source file - 'gcc/config.gcc'. - - You can use whatever compiler you like to compile programs that use - the GNU C Library. - - Check the FAQ for any special compiler issues on particular - platforms. - - * GNU 'binutils' 2.22 or later - - You must use GNU 'binutils' (as and ld) to build the GNU C Library. - No other assembler or linker has the necessary functionality at the - moment. As of release time, GNU 'binutils' 2.25 is the newest - verified to work to build the GNU C Library. - - * GNU 'texinfo' 4.7 or later - - To correctly translate and install the Texinfo documentation you - need this version of the 'texinfo' package. Earlier versions do - not understand all the tags used in the document, and the - installation mechanism for the info files is not present or works - differently. As of release time, 'texinfo' 6.0 is the newest - verified to work to build the GNU C Library. - - * GNU 'awk' 3.1.2, or higher - - 'awk' is used in several places to generate files. Some 'gawk' - extensions are used, including the 'asorti' function, which was - introduced in version 3.1.2 of 'gawk'. As of release time, 'gawk' - version 4.1.3 is the newest verified to work to build the GNU C - Library. - - * Perl 5 - - Perl is not required, but it is used if present to test the - installation. We may decide to use it elsewhere in the future. - - * GNU 'sed' 3.02 or newer - - 'Sed' is used in several places to generate files. Most scripts - work with any version of 'sed'. As of release time, 'sed' version - 4.2.2 is the newest verified to work to build the GNU C Library. - -If you change any of the 'configure.ac' files you will also need - - * GNU 'autoconf' 2.69 (exactly) - -and if you change any of the message translation files you will need - - * GNU 'gettext' 0.10.36 or later - -If you wish to regenerate the 'yacc' parser code in the 'intl' -subdirectory you will need - - * GNU 'bison' 2.7 or later - -You may also need these packages if you upgrade your source tree using -patches, although we try to avoid this. - -Specific advice for GNU/Linux systems -===================================== - -If you are installing the GNU C Library on GNU/Linux systems, you need -to have the header files from a 3.2 or newer kernel around for -reference. (For the ia64 architecture, you need version 3.2.18 or newer -because this is the first version with support for the 'accept4' system -call.) These headers must be installed using 'make headers_install'; -the headers present in the kernel source directory are not suitable for -direct use by the GNU C Library. You do not need to use that kernel, -just have its headers installed where the GNU C Library can access them, -referred to here as INSTALL-DIRECTORY. The easiest way to do this is to -unpack it in a directory such as '/usr/src/linux-VERSION'. In that -directory, run 'make headers_install -INSTALL_HDR_PATH=INSTALL-DIRECTORY'. Finally, configure the GNU C -Library with the option '--with-headers=INSTALL-DIRECTORY/include'. Use -the most recent kernel you can get your hands on. (If you are -cross-compiling the GNU C Library, you need to specify -'ARCH=ARCHITECTURE' in the 'make headers_install' command, where -ARCHITECTURE is the architecture name used by the Linux kernel, such as -'x86' or 'powerpc'.) - - After installing the GNU C Library, you may need to remove or rename -directories such as '/usr/include/linux' and '/usr/include/asm', and -replace them with copies of directories such as 'linux' and 'asm' from -'INSTALL-DIRECTORY/include'. All directories present in -'INSTALL-DIRECTORY/include' should be copied, except that the GNU C -Library provides its own version of '/usr/include/scsi'; the files -provided by the kernel should be copied without replacing those provided -by the GNU C Library. The 'linux', 'asm' and 'asm-generic' directories -are required to compile programs using the GNU C Library; the other -directories describe interfaces to the kernel but are not required if -not compiling programs using those interfaces. You do not need to copy -kernel headers if you did not specify an alternate kernel header source -using '--with-headers'. - - The Filesystem Hierarchy Standard for GNU/Linux systems expects some -components of the GNU C Library installation to be in '/lib' and some in -'/usr/lib'. This is handled automatically if you configure the GNU C -Library with '--prefix=/usr'. If you set some other prefix or allow it -to default to '/usr/local', then all the components are installed there. - -Reporting Bugs -============== - -There are probably bugs in the GNU C Library. There are certainly -errors and omissions in this manual. If you report them, they will get -fixed. If you don't, no one will ever know about them and they will -remain unfixed for all eternity, if not longer. - - It is a good idea to verify that the problem has not already been -reported. Bugs are documented in two places: The file 'BUGS' describes -a number of well known bugs and the central GNU C Library bug tracking -system has a WWW interface at <http://sourceware.org/bugzilla/>. The -WWW interface gives you access to open and closed reports. A closed -report normally includes a patch or a hint on solving the problem. - - To report a bug, first you must find it. With any luck, this will be -the hard part. Once you've found a bug, make sure it's really a bug. A -good way to do this is to see if the GNU C Library behaves the same way -some other C library does. If so, probably you are wrong and the -libraries are right (but not necessarily). If not, one of the libraries -is probably wrong. It might not be the GNU C Library. Many historical -Unix C libraries permit things that we don't, such as closing a file -twice. - - If you think you have found some way in which the GNU C Library does -not conform to the ISO and POSIX standards (*note Standards and -Portability::), that is definitely a bug. Report it! - - Once you're sure you've found a bug, try to narrow it down to the -smallest test case that reproduces the problem. In the case of a C -library, you really only need to narrow it down to one library function -call, if possible. This should not be too difficult. - - The final step when you have a simple test case is to report the bug. -Do this at <http://www.gnu.org/software/libc/bugs.html>. - - If you are not sure how a function should behave, and this manual -doesn't tell you, that's a bug in the manual. Report that too! If the -function's behavior disagrees with the manual, then either the library -or the manual has a bug, so report the disagreement. If you find any -errors or omissions in this manual, please report them to the bug -database. If you refer to specific sections of the manual, please -include the section names for easier identification. |