* EGLIBC.cross-building, EGLIBC.cross-testing,

	EGLIBC.option-groups: New files.
	* README, INSTALL: Identify ourselves as EGLIBC, and refer to the
	above files.


git-svn-id: svn://svn.eglibc.org/trunk@1512 7b3dc134-2b1b-0410-93df-9e9f96275f8d

6 files changed, 730 insertions, 0 deletions

diff --git a/libc/ChangeLog.eglibc b/libc/ChangeLog.eglibc
index 6a011a1dd..eafbb2614 100644
--- a/libc/ChangeLog.eglibc
+++ b/libc/ChangeLog.eglibc
@@ -1,3 +1,10 @@
+2007-02-19  Jim Blandy  <jimb@codesourcery.com>
+
+	* EGLIBC.cross-building, EGLIBC.cross-testing,
+	EGLIBC.option-groups: New files.
+	* README, INSTALL: Identify ourselves as EGLIBC, and refer to the
+	above files.
+
 2007-02-16  Jim Blandy  <jimb@codesourcery.com>
 
 	Make configuration script more friendly to cross-compilation.
diff --git a/libc/EGLIBC.cross-building b/libc/EGLIBC.cross-building
new file mode 100644
index 000000000..aadc8d217
--- /dev/null
+++ b/libc/EGLIBC.cross-building
@@ -0,0 +1,347 @@
+                                                        -*- mode: text -*-
+
+                        Cross-Compiling EGLIBC
+                  Jim Blandy <jimb@codesourcery.com>
+
+
+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!
diff --git a/libc/EGLIBC.cross-testing b/libc/EGLIBC.cross-testing
new file mode 100644
index 000000000..4c6e06106
--- /dev/null
+++ b/libc/EGLIBC.cross-testing
@@ -0,0 +1,205 @@
+                                                        -*- mode: text -*-
+
+                      Cross-Testing With EGLIBC
+                  Jim Blandy <jimb@codesourcery.com>
+
+
+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.
diff --git a/libc/EGLIBC.option-groups b/libc/EGLIBC.option-groups
new file mode 100644
index 000000000..1bbbe66ae
--- /dev/null
+++ b/libc/EGLIBC.option-groups
@@ -0,0 +1,131 @@
+                                                        -*- mode: text -*-
+
+              The EGLIBC Component Configuration System
+                  Jim Blandy <jimb@codesourcery.com>
+
+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.
diff --git a/libc/INSTALL b/libc/INSTALL
index 8d61b3e48..eb614e574 100644
--- a/libc/INSTALL
+++ b/libc/INSTALL
@@ -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
 ****************************
 
diff --git a/libc/README b/libc/README
index 97b3a61e0..1e790e028 100644
--- a/libc/README
+++ b/libc/README
@@ -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,