[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[patches] COMMIT: EGLIBC doc fixes
- To: patches@xxxxxxxxxx
- Subject: [patches] COMMIT: EGLIBC doc fixes
- From: Jim Blandy <jimb@xxxxxxxxxxxxxxxx>
- Date: Mon, 19 Feb 2007 12:00:57 -0800
I've committed the patch below to the trunk and the 2.5 branch. Mark,
the URL for the cross-building instructions is:
http://www.eglibc.org/cgi-bin/viewcvs.cgi/*checkout*/branches/eglibc-2_5/libc/EGLIBC.cross-building?rev=1513
ChangeLog.eglibc:
2007-02-19 Jim Blandy <jimb@xxxxxxxxxxxxxxxx>
* EGLIBC.cross-building, EGLIBC.cross-testing,
EGLIBC.option-groups: New files.
* README, INSTALL: Identify ourselves as EGLIBC, and refer to the
above files.
Index: README
===================================================================
--- README (revision 1512)
+++ README (revision 1513)
@@ -1,3 +1,31 @@
+This directory contains the Embedded GNU C Library (EGLIBC).
+
+EGLIBC is a variant of the GNU C Library (GLIBC) that is designed to
+work well on embedded systems. EGLIBC strives to be source and binary
+compatible with GLIBC. EGLIBC's goals include reduced footprint,
+configurable components, better support for cross-compilation and
+cross-testing. More information is available at
+http://www.eglibc.org.
+
+Files in this directory describe EGLIBC's features for embedded
+developers:
+
+- EGLIBC.cross-building provides general instructions for building
+ EGLIBC and an accompanying compiler for cross-development. (And
+ explains why this isn't as simple as 'configure; make'.)
+
+- EGLIBC.option-groups explains EGLIBC's facilities for paring down
+ the library functionality to the features you really need, to reduce
+ disk and memory consumption. (A one-line file disabling the
+ OPTION_EGLIBC_LOCALES option reduces the on-disk footprint of EGLIBC
+ by 92%.)
+
+- EGLIBC.cross-testing explains how to test a cross-compiled EGLIBC.
+
+Here is the original GLIBC README:
+
+---
+
This directory contains the version 2.5 release of the GNU C Library.
The GNU C Library is the standard system C library for all GNU systems,
Index: INSTALL
===================================================================
--- INSTALL (revision 1512)
+++ INSTALL (revision 1513)
@@ -1,3 +1,15 @@
+Installing EGLIBC
+*****************
+
+This is EGLIBC, a variant of the GNU C Library (GLIBC) that is
+designed to work well on embedded systems. This file contains the
+original GLIBC installation instructions, which mostly deal with
+native develelopment. 'EGLIBC.cross-building' provides general
+instructions for building EGLIBC and an accompanying compiler for
+cross-development.
+
+Here are the original GLIBC installation instructions:
+
Installing the GNU C Library
****************************
Index: EGLIBC.cross-building
===================================================================
--- EGLIBC.cross-building (revision 0)
+++ EGLIBC.cross-building (revision 1513)
@@ -0,0 +1,347 @@
+ -*- mode: text -*-
+
+ Cross-Compiling EGLIBC
+ Jim Blandy <jimb@xxxxxxxxxxxxxxxx>
+
+
+Introduction
+
+Most GNU tools have a simple build procedure: you run their
+'configure' script, and then you run 'make'. Unfortunately, the
+process of cross-compiling the GNU C library is quite a bit more
+involved:
+
+1) Build a cross-compiler, with certain facilities disabled.
+
+2) Configure the C library using the compiler you built in step 1).
+ Build a few of the C run-time object files, but not the rest of the
+ library. Install the library's header files and the run-time
+ object files, and create a dummy libc.so.
+
+3) Build a second cross-compiler, using the header files and object
+ files you installed in step 2.
+
+4) Configure, build, and install a fresh C library, using the compiler
+ built in step 3.
+
+5) Build a third cross-compiler, based on the C library built in step 4.
+
+The reason for this complexity is that, although GCC and the GNU C
+library are distributed separately, they are not actually independent
+of each other: GCC requires the C library's headers and some object
+files to compile its own libraries, while the C library depends on
+GCC's libraries. EGLIBC includes features and bug fixes to the stock
+GNU C library that simplify this process, but the fundamental
+interdependency stands.
+
+In this document, we explain how to cross-compile an EGLIBC/GCC pair
+from source. Our intended audience is developers who are already
+familiar with the GNU toolchain and comfortable working with
+cross-development tools. While we do present a worked example to
+accompany the explanation, for clarity's sake we do not cover many of
+the options available to cross-toolchain users.
+
+
+Preparation
+
+EGLIBC requires recent versions of the GNU binutils, GCC, and the
+Linux kernel. The web page <http://www.eglibc.org/prerequisites>
+documents the current requirements, and lists patches needed for
+certain target architectures. As of this writing, EGLIBC required
+binutils 2.17, GCC 4.1, and Linux 2.6.19.1.
+
+First, let's set some variables, to simplify later commands. We'll
+build EGLIBC and GCC for a PowerPC target, known to the Linux kernel
+as 'powerpc', and we'll do the build on an Intel Linux box:
+
+ $ build=i686-pc-linux-gnu
+ $ host=$build
+ $ target=powerpc-none-linux-gnu
+ $ linux_arch=powerpc
+
+We're using the aforementioned versions of Binutils, GCC, and Linux:
+
+ $ binutilsv=binutils-2.17
+ $ gccv=gcc-4.1.1
+ $ linuxv=linux-2.6.20
+
+We're carrying out the entire process under '~/cross-build', which
+contains unpacked source trees:
+
+ $ top=$HOME/cross-build/ppc
+ $ src=$HOME/cross-build/src
+ $ ls $src
+ binutils-2.17 gcc-4.1.1 libc linux-2.6.20
+
+We're going to place our build directories in a subdirectory 'obj',
+we'll install the cross-development toolchain in 'tools', and we'll
+place our sysroot (containing files to be installed on the target
+system) in 'sysroot':
+
+ $ obj=$top/obj
+ $ tools=$top/tools
+ $ sysroot=$top/sysroot
+
+
+Binutils
+
+Configuring and building binutils for the target is straightforward:
+
+ $ mkdir -p $obj/binutils
+ $ cd $obj/binutils
+ $ $src/$binutilsv/configure \
+ > --target=$target \
+ > --prefix=$tools \
+ > --with-sysroot=$sysroot
+ $ make
+ $ make install
+
+
+The First GCC
+
+For our work, we need a cross-compiler targeting a PowerPC Linux
+system. However, that configuration includes the shared library
+'libgcc_s.so', which is compiled against the EGLIBC headers (which we
+haven't installed yet) and linked against 'libc.so' (which we haven't
+built yet).
+
+Fortunately, there are configuration options for GCC which tell it not
+to build 'libgcc_s.so'. The '--without-headers' option is supposed to
+take care of this, but its implementation is incomplete, so you must
+also configure with the '--with-newlib' option. While '--with-newlib'
+appears to mean "Use the Newlib C library", its effect is to tell the
+GCC build machinery, "Don't assume there is a C library available."
+
+We also need to disable some of the libraries that would normally be
+built along with GCC, and specify that only the compiler for the C
+language is needed.
+
+So, we create a build directory, configure, make, and install.
+
+ $ mkdir -p $obj/gcc1
+ $ cd $obj/gcc1
+ $ $src/$gccv/configure \
+ > --target=$target \
+ > --prefix=$tools \
+ > --without-headers --with-newlib \
+ > --disable-shared --disable-threads --disable-libssp \
+ > --disable-libgomp --disable-libmudflap \
+ > --enable-languages=c
+ $ PATH=$tools/bin:$PATH make
+ $ PATH=$tools/bin:$PATH make install
+
+
+Linux Kernel Headers
+
+To configure EGLIBC, we also need Linux kernel headers in place.
+Fortunately, the Linux makefiles have a target that installs them for
+us. Since the process does modify the source tree a bit, we make a
+copy first:
+
+ $ cp -r $src/$linuxv $obj/linux
+ $ cd $obj/linux
+
+Now we're ready to install the headers into the sysroot:
+
+ $ PATH=$tools/bin:$PATH \
+ > make headers_install \
+ > ARCH=$linux_arch CROSS_COMPILE=$target- \
+ > INSTALL_HDR_PATH=$sysroot/usr
+
+
+EGLIBC Headers and Preliminary Objects
+
+Using the cross-compiler we've just built, we can now configure EGLIBC
+well enough to install the headers and build the object files that the
+full cross-compiler will need:
+
+ $ mkdir -p $obj/eglibc-headers
+ $ cd $obj/eglibc-headers
+ $ BUILD_CC=gcc \
+ > CC=$tools/bin/$target-gcc \
+ > CXX=$tools/bin/$target-g++ \
+ > AR=$tools/bin/$target-ar \
+ > RANLIB=$tools/bin/$target-ranlib \
+ > $src/libc/configure \
+ > --prefix=/usr \
+ > --with-headers=$sysroot/usr/include \
+ > --build=$build \
+ > --host=$target \
+ > --disable-profile --without-gd --without-cvs --enable-add-ons
+
+The option '--prefix=/usr' may look strange, but you should never
+configure EGLIBC with a prefix other than '/usr': in various places,
+EGLIBC's build system checks whether the prefix is '/usr', and does
+special handling only if that is the case. Unless you use this
+prefix, you will get a sysroot that does not use the standard Linux
+directory layouts and cannot be used as a basis for the root
+filesystem on your target system compatibly with normal GLIBC
+installations.
+
+The '--with-headers' option tells EGLIBC where the Linux headers have
+been installed.
+
+We can now use the 'install-headers' makefile target to install the
+headers:
+
+ $ make install-headers install_root=$sysroot \
+ > install-bootstrap-headers=yes
+
+The 'install_root' variable indicates where the files should actually
+be installed; its value is treated as the parent of the '--prefix'
+directory we passed to the configure script, so the headers will go in
+'$sysroot/usr/include'. The 'install-bootstrap-headers' variable
+requests special handling for certain tricky header files.
+
+Next, there are a few object files needed to link shared libraries,
+which we build and install by hand:
+
+ $ mkdir -p $sysroot/usr/lib
+ $ make csu/subdir_lib
+ $ cp csu/crt1.o csu/crti.o csu/crtn.o $sysroot/usr/lib
+
+Finally, 'libgcc_s.so' requires a 'libc.so' to link against. However,
+since we will never actually execute its code, it doesn't matter what
+it contains. So, treating '/dev/null' as a C source file, we produce
+a dummy 'libc.so' in one step:
+
+ $ $tools/bin/$target-gcc -nostdlib -nostartfiles -shared -x c /dev/null \
+ > -o $sysroot/usr/lib/libc.so
+
+
+The Second GCC
+
+With the EGLIBC headers and selected object files installed, we can
+now build a GCC that is capable of compiling EGLIBC. We configure,
+build, and install the second GCC, again building only the C compiler,
+and avoiding libraries we won't use:
+
+ $ mkdir -p $obj/gcc2
+ $ cd $obj/gcc2
+ $ $src/$gccv/configure \
+ > --target=$target \
+ > --prefix=$tools \
+ > --with-sysroot=$sysroot \
+ > --disable-libssp --disable-libgomp --disable-libmudflap \
+ > --enable-languages=c
+ $ PATH=$tools/bin:$PATH make
+ $ PATH=$tools/bin:$PATH make install
+
+
+EGLIBC, Complete
+
+With the second compiler built and installed, we're now ready for the
+full EGLIBC build:
+
+ $ mkdir -p $obj/eglibc
+ $ cd $obj/eglibc
+ $ BUILD_CC=gcc \
+ > CC=$tools/bin/$target-gcc \
+ > CXX=$tools/bin/$target-g++ \
+ > AR=$tools/bin/$target-ar \
+ > RANLIB=$tools/bin/$target-ranlib \
+ > $src/libc/configure \
+ > --prefix=/usr \
+ > --with-headers=$sysroot/usr/include \
+ > --build=$build \
+ > --host=$target \
+ > --disable-profile --without-gd --without-cvs --enable-add-ons
+ $ PATH=$tools/bin:$PATH make
+ $ PATH=$tools/bin:$PATH make install install_root=$sysroot
+
+At this point, we have a complete EGLIBC installation in '$sysroot',
+with header files, library files, and most of the C runtime startup
+files in place.
+
+
+The Third GCC
+
+Finally, we recompile GCC against this full installation, enabling
+whatever languages and libraries we would like to use:
+
+ $ mkdir -p $obj/gcc3
+ $ cd $obj/gcc3
+ $ $src/$gccv/configure \
+ > --target=$target \
+ > --prefix=$tools \
+ > --with-sysroot=$sysroot \
+ > --disable-libssp --disable-libgomp --disable-libmudflap \
+ > --enable-languages=c,c++
+ $ PATH=$tools/bin:$PATH make
+ $ PATH=$tools/bin:$PATH make install
+
+And since GCC's installation process isn't designed to help construct
+sysroot trees, we must manually copy certain libraries into place in
+the sysroot.
+
+ $ cp -d $tools/$target/lib/libgcc_s.so* $sysroot/lib
+ $ cp -d $tools/$target/lib/libstdc++.so* $sysroot/usr/lib
+
+
+Trying Things Out
+
+At this point, '$tools' contains a cross toolchain ready to use
+the EGLIBC installation in '$sysroot':
+
+ $ cat > hello.c <<EOF
+ > #include <stdio.h>
+ > int
+ > main (int argc, char **argv)
+ > {
+ > puts ("Hello, world!");
+ > return 0;
+ > }
+ > EOF
+ $ $tools/bin/$target-gcc -Wall hello.c -o hello
+ $ cat > c++-hello.cc <<EOF
+ > #include <iostream>
+ > int
+ > main (int argc, char **argv)
+ > {
+ > std::cout << "Hello, C++ world!" << std::endl;
+ > return 0;
+ > }
+ > EOF
+ $ $tools/bin/$target-g++ -Wall c++-hello.cc -o c++-hello
+
+
+We can use 'readelf' to verify that these are indeed executables for
+our target, using our dynamic linker:
+
+ $ $tools/bin/$target-readelf -hl hello
+ ELF Header:
+ ...
+ Type: EXEC (Executable file)
+ Machine: PowerPC
+
+ ...
+ Program Headers:
+ Type Offset VirtAddr PhysAddr FileSiz MemSiz Flg Align
+ PHDR 0x000034 0x10000034 0x10000034 0x00100 0x00100 R E 0x4
+ INTERP 0x000134 0x10000134 0x10000134 0x0000d 0x0000d R 0x1
+ [Requesting program interpreter: /lib/ld.so.1]
+ LOAD 0x000000 0x10000000 0x10000000 0x008f0 0x008f0 R E 0x10000
+ ...
+
+Looking at the dynamic section of the installed 'libgcc_s.so', we see
+that the 'NEEDED' entry for the C library does include the '.6'
+suffix, indicating that was linked against our fully build EGLIBC, and
+not our dummy 'libc.so':
+
+ $ $tools/bin/$target-readelf -d $sysroot/lib/libgcc_s.so.1
+ Dynamic section at offset 0x1083c contains 24 entries:
+ Tag Type Name/Value
+ 0x00000001 (NEEDED) Shared library: [libc.so.6]
+ 0x00000001 (NEEDED) Shared library: [ld.so.1]
+ 0x0000000e (SONAME) Library soname: [libgcc_s.so.1]
+ ...
+
+
+And on the target machine, we can run our programs:
+
+ $ $sysroot/lib/ld.so.1 --library-path $sysroot/lib:$sysroot/usr/lib \
+ > ./hello
+ Hello, world!
+ $ $sysroot/lib/ld.so.1 --library-path $sysroot/lib:$sysroot/usr/lib \
+ > ./c++-hello
+ Hello, C++ world!
Index: EGLIBC.cross-testing
===================================================================
--- EGLIBC.cross-testing (revision 0)
+++ EGLIBC.cross-testing (revision 1513)
@@ -0,0 +1,205 @@
+ -*- mode: text -*-
+
+ Cross-Testing With EGLIBC
+ Jim Blandy <jimb@xxxxxxxxxxxxxxxx>
+
+
+Introduction
+
+Developers writing software for embedded systems often use a desktop
+or other similarly capable computer for development, but need to run
+tests on the embedded system, or perhaps on a simulator. When
+configured for cross-compilation, the stock GNU C library simply
+disables running tests altogether: the command 'make tests' builds
+test programs, but does not run them. EGLIBC, however, provides
+facilities for compiling tests and generating data files on the build
+system, but running the test programs themselves on a remote system or
+simulator.
+
+
+Test environment requirements
+
+The test environment must meet certain conditions for EGLIBC's
+cross-testing facilities to work:
+
+- Shared filesystems. The 'build' system, on which you configure and
+ compile EGLIBC, and the 'host' system, on which you intend to run
+ EGLIBC, must share a filesystem containing the EGLIBC build and
+ source trees. Files must appear at the same paths on both systems.
+
+- Remote-shell like invocation. There must be a way to run a program
+ on the host system from the build system, passing it properly quoted
+ command-line arguments, setting environment variables, and
+ inheriting the caller's standard input and output.
+
+
+Usage
+
+To use EGLIBC's cross-testing support, provide values for the
+following Make variables when you invoke 'make':
+
+- cross-test-wrapper
+
+ This should be the name of the cross-testing wrapper command, along
+ with any arguments.
+
+- cross-localedef
+
+ This should be the name of a cross-capable localedef program, like
+ that included in the EGLIBC 'localedef' module, along with any
+ arguments needed.
+
+These are each explained in detail below.
+
+
+The Cross-Testing Wrapper
+
+To run test programs reliably, the stock GNU C library takes care to
+ensure that test programs use the newly compiled dynamic linker and
+shared libraries, and never the host system's installed libraries. To
+accomplish this, it runs the tests by explicitly invoking the dynamic
+linker from the build tree, passing it a list of build tree
+directories to search for shared libraries, followed by the name of
+the executable to run and its arguments.
+
+For example, where one might normally run a test program like this:
+
+ $ ./tst-foo arg1 arg2
+
+the GNU C library might run that program like this:
+
+ $ $objdir/elf/ld-linux.so.3 --library-path $objdir \
+ ./tst-foo arg1 arg2
+
+(where $objdir is the path to the top of the build tree, and the
+trailing backslash indicates a continuation of the command). In other
+words, each test program invocation is 'wrapped up' inside an explicit
+invocation of the dynamic linker, which must itself execute the test
+program, having loaded shared libraries from the appropriate
+directories.
+
+To support cross-testing, EGLIBC allows the developer to optionally
+set the 'cross-test-wrapper' Make variable to another wrapper command,
+to which it passes the entire dynamic linker invocation shown above as
+arguments. For example, if the developer supplies a wrapper of
+'my-wrapper hostname', then EGLIBC would run the test above as
+follows:
+
+ $ my-wrapper hostname \
+ $objdir/elf/ld-linux.so.3 --library-path $objdir \
+ ./tst-foo arg1 arg2
+
+The 'my-wrapper' command is responsible for executing the command
+given on the host system.
+
+Since tests are run in varying directories, the wrapper should either
+be in your command search path, or 'cross-test-wrapper' should give an
+absolute path for the wrapper.
+
+The wrapper must meet several requirements:
+
+- It must preserve the current directory. As explained above, the
+ build directory tree must be visible on both the build and host
+ systems, at the same path. The test wrapper must ensure that the
+ current directory it inherits is also inherited by the dynamic
+ linker (and thus the test program itself).
+
+- It must preserve environment variables' values. Many EGLIBC tests
+ set environment variables for test runs; in native testing, it
+ invokes programs like this:
+
+ $ GCONV_PATH=$objdir/iconvdata \
+ $objdir/elf/ld-linux.so.3 --library-path $objdir \
+ ./tst-foo arg1 arg2
+
+ With the cross-testing wrapper, that invocation becomes:
+
+ $ GCONV_PATH=$objdir/iconvdata \
+ my-wrapper hostname \
+ $objdir/elf/ld-linux.so.3 --library-path $objdir \
+ ./tst-foo arg1 arg2
+
+ Here, 'my-wrapper' must ensure that the value it sees for
+ 'GCONV_PATH' will be seen by the dynamic linker, and thus 'tst-foo'
+ itself. (The wrapper supplied with GLIBC simply preserves the
+ values of *all* enviroment variables, with a fixed set of
+ exceptions.)
+
+ If your wrapper is a shell script, take care to correctly propagate
+ environment variables whose values contain spaces and shell
+ metacharacters.
+
+- It must pass the command's arguments, unmodified. The arguments
+ seen by the test program should be exactly those seen by the wrapper
+ (after whatever arguments are given to the wrapper itself). The
+ EGLIBC test framework performs all needed shell word splitting and
+ expansion (wildcard expansion, parameter substitution, and so on)
+ before invoking the wrapper; further expansion may break the tests.
+
+
+The 'cross-test-ssh.sh' script
+
+If you want to use 'ssh' (or something sufficiently similar) to run
+test programs on your host system, EGLIBC includes a shell script,
+'scripts/cross-test-ssh.sh', which you can use as your wrapper
+command. This script takes care of setting the test command's current
+directory, propagating environment variable values, and carrying
+command-line arguments, all across an 'ssh' connection. You may even
+supply an alternative to 'ssh' on the command line, if needed.
+
+For more details, pass 'cross-test-ssh.sh' the '--help' option.
+
+
+The Cross-Compiling Locale Definition Command
+
+Some EGLIBC tests rely on locales generated especially for the test
+process. In a native configuration, these tests simply run the
+'localedef' command built by the normal EGLIBC build process,
+'locale/localedef', to process and install their locales. However, in
+a cross-compiling configuration, this 'localedef' is built for the
+host system, not the build system, and since it requires quite a bit
+of memory to run (we have seen it fail on systems with 64MiB of
+memory), it may not be practical to run it on the host system.
+
+If set, EGLIBC uses the 'cross-localedef' Make variable as the command
+to run on the build system to process and install locales. The
+localedef program built from the EGLIBC 'localedef' module is
+suitable.
+
+The value of 'cross-localedef' may also include command-line arguments
+to be passed to the program; if you are using EGLIBC's 'localedef',
+you may include endianness and 'uint32_t' alignment arguments here.
+
+
+Example
+
+In developing EGLIBC's cross-testing facility, we invoked 'make' with
+the following script:
+
+ #!/bin/sh
+
+ srcdir=...
+ test_hostname=...
+ localedefdir=...
+ cross_gxx=...-g++
+
+ wrapper="$srcdir/scripts/cross-test-ssh.sh $test_hostname"
+ localedef="$localedefdir/localedef --little-endian --uint32-align=4"
+
+ make cross-test-wrapper="$wrapper" \
+ cross-localedef="$localedef" \
+ CXX="$cross_gxx" \
+ "$@"
+
+
+Other Cross-Testing Concerns
+
+Here are notes on some other issues which you may encounter in running
+the EGLIBC tests in a cross-compiling environment:
+
+- Some tests require a C++ cross-compiler; you should set the 'CXX'
+ Make variable to the name of an appropriate cross-compiler.
+
+- Some tests require access to libstdc++.so.6 and libgcc_s.so.1; we
+ simply place copies of these libraries in the top EGLIBC build
+ directory.
Index: EGLIBC.option-groups
===================================================================
--- EGLIBC.option-groups (revision 0)
+++ EGLIBC.option-groups (revision 1513)
@@ -0,0 +1,131 @@
+ -*- mode: text -*-
+
+ The EGLIBC Component Configuration System
+ Jim Blandy <jimb@xxxxxxxxxxxxxxxx>
+
+Introduction
+
+The GNU C library (GLIBC) provides a broad range of functionality,
+ranging from internationalization support to transcendental
+mathematical functions. Its website boasts that "nearly all known and
+useful functions from any other C library are available." This
+exhaustive approach has been one of GLIBC's strengths on desktop and
+server systems, but it has also given GLIBC a large footprint, both in
+memory and on disk, making it a challenge to use in embedded systems
+with limited resources.
+
+The Embedded GNU C library (EGLIBC) is a variant of the GNU C library
+designed to work well on embedded systems. In particular, EGLIBC's
+component configuration system allows embedded developers to build
+customized versions of the library that include only the features
+their application uses, reducing its space requirements.
+
+EGLIBC's component configuration system categorizes the library's
+functions into "option groups", and allows you to include or exclude
+option groups individually. Some option groups depend on others;
+EGLIBC tracks these relationships, and ensures that the selected
+configuration yields a functioning library.
+
+
+Consistent and Predictable Behavior
+
+A flexible configuration system is a mixed blessing: if the options
+offered are poorly designed, it can be hard to see which choices will
+have the desired effects, and choices with obscure consequences can
+make debugging difficult. EGLIBC's configuration follows some general
+principles to reduce these risks:
+
+- EGLIBC has a single default configuration for each target
+ architecture.
+
+- In the default configuration, all option groups are enabled, and
+ EGLIBC is upwardly API- and ABI-compatible with GLIBC.
+
+- As much as possible, configurations only affect what functions are
+ present, not how they behave. If the system works with an option
+ group disabled, it will still work with it enabled.
+
+- As much as possible, configurations only select option groups ---
+ they do not describe characteristics of the target architecture.
+
+These rules mean that you have a simple debugging strategy available
+if you suspect that your EGLIBC configuration might be the source of a
+problem: fall back to the default configuration, re-test, and then
+disable option groups one by one, until the problem reappears.
+
+
+The Option Groups
+
+The POSIX.1-2001 specification includes a suggested partition of all
+the functions in the POSIX C API into option groups: math functions
+like 'sin' and 'cos'; networking functions like 'socket' and
+'connect'; and so on. EGLIBC uses this partitioning as the basis for
+its own option groups, and follows the POSIX naming scheme.
+
+
+Implementation
+
+The EGLIBC component configuration system resembles the approach used
+by the Linux kernel to select device drivers, network protocols, and
+other features. A file named 'option-groups.config' in the top-level
+build directory contains assignments to Make variables, each of which
+enables or disables a particular option group. If the variable's
+value is set to 'y', then the option group is enabled; if it set to
+anything else, the option group is omitted. The file
+'option-groups.defaults', at the top of the source tree, establishes
+default values for all variables; all option groups are enabled by
+default.
+
+For example, the following 'option-groups.config' would omit
+mathematical functions, but include networking functions, and
+everything else:
+
+ OPTION_POSIX_C_LANG_MATH = n
+ OPTION_POSIX_NETWORKING = y
+
+In general, each option group variable controls whether a given set of
+object files in EGLIBC is compiled and included in the final
+libraries, or omitted from the build.
+
+Each subdirectory's Makefile categorizes its routines by option group.
+For example, EGLIBC's 'inet/Makefile' places its functions in the
+POSIX_NETWORKING group as follows:
+
+ routines-$(OPTION_POSIX_NETWORKING) += \
+ htonl htons \
+ inet_lnaof inet_mkadr \
+ inet_netof inet_ntoa inet_net herrno herrno-loc \
+ gethstbyad gethstbyad_r gethstbynm gethstbynm2 gethstbynm2_r \
+ ...
+
+Finally, common code in 'Makerules' cites the value of the variable
+'routines-y', selecting only those object files that belong to enabled
+option groups for inclusion in the resulting libraries.
+
+
+Current Status and Future Directions
+
+The EGLIBC component configuration system described here is still
+under development.
+
+We have used the system to subset some portions of EGLIBC's
+functionality. It needs to be extended to cover more of the library.
+
+At the moment, EGLIBC performs no sanity checks on the contents of
+'option-groups.config'; if an option group's name is mistyped, the
+option group is silently included in the build. EGLIBC should check
+that all variables set in 'option-groups.config' are proper option
+group names, and that their values are appropriate.
+
+Some portions of EGLIBC depend on others; for example, the Sun Remote
+Procedure Call functions in 'sunrpc' depend on the networking
+functions in 'inet'. The sanity checking described above should check
+that the selection configuration satisfies dependencies within EGLIBC,
+and produce a legible error message if it does not. At the moment,
+inconsistent configurations produce link errors late in the build
+process.
+
+The Linux kernel's configuration system provides interactive
+interfaces for creating and modifying configuration files (which also
+perform the sanity checking and dependency tracking described above).
+EGLIBC should provide similar interfaces.