1 files changed, 129 insertions, 0 deletions
diff --git a/libiberty/README b/libiberty/README
new file mode 100644
index 00000000000..5081bbac196
--- /dev/null
+++ b/libiberty/README
@@ -0,0 +1,129 @@
+This directory contains the -liberty library of free software.
+It is a collection of subroutines used by various GNU programs.
+Current members include:
+
+	getopt -- get options from command line
+	obstack -- stacks of arbitrarily-sized objects
+	strerror -- error message strings corresponding to errno
+	strtol -- string-to-long conversion
+	strtoul -- string-to-unsigned-long conversion
+
+We expect many of the GNU subroutines that are floating around to
+eventually arrive here.
+
+To build the library, do:
+
+	./configure HOSTTYPE
+	make
+
+Please report bugs and fixes to "bug-gnu-utils@prep.ai.mit.edu".  Thank you.
+
+ADDING A NEW FILE
+=================
+
+There are two sets of files:  Those that are "required" will be
+included in the library for all configurations, while those
+that are "optional" will be included in the library only if "needed."
+
+To add a new required file, edit Makefile to add the source file
+name to CFILES and the object file to REQUIRED_OFILES.
+
+Adding a new optional file is more fragile.  As a general rule,
+an optional file will be included in the library if it provides
+functionality missing in the "standard" C library.
+For most hosts, the Makefile automatically figures out which
+functionality is missing by compiling and linking a dummy test
+program, and examining the error messages.
+
+So to get this to work, you should do the following:
+
+1) Select one function defined in the file you're adding.
+For example, the getcwd function.
+2) Add that function to the list in the file functions.def.
+3) The name of the new file must be the same as the function
+you've chosen with the .c suffix added.  E.g. getcwd() must be
+defined in getcwd.c.  (The file can define other functions as well.)
+4) In Makefile.in, add the name of the source file (e.g. getcwd.c)
+to CFILES.
+
+The file you've added (e.g. getcwd.c) should compile and work
+on all hosts where it is needed (e.g. not found when linking
+the dummy.c program).  It does not have to work or even
+compile on hosts where it is not needed.
+
+HOW THE AUTOMATIC CONFIGURATION WORKS
+=====================================
+
+The libiberty.a target (in RULE1) depends on $(DO_ALSO).
+For normal configurations, DO_ALSO=needed-list.
+
+So needed-list is first made.  The needed-list rule compiles
+dummy.c.  Because dummy.c includes functions.def, the
+resulting object file will contain a call to each of the
+optional functions (for simplicity assume each optional file
+defines a single function).  This object file will be linked
+against the standard libraries (as defined by using $(CC)
+and various flags).  Any function missing will causes the
+linker to emit an error message.  We assume the name
+of the missing function(s) are in the error message(s).
+The awk script find-needed.awk has been generated from
+functions.def.  It is used to search the linker output
+messages for words that match the functions listed in
+functions.def.  The list of functions found is written
+on a single line to the file needed-list.
+
+After needed-list has been generated, the libiberty.a
+target (in RULE1) just calls 'make' recursively.
+It passes the contents of needed-list using the
+definition (expanded) HOST_OFILES="`cat needed-list`".
+It also tells the inferior 'make' to use RULE2.
+
+The inferior 'make' is very conventional:  The main
+rule is $(RULE2) (which is libiberty.a).  It depends
+on a list of object files: $(REQUIRED_OFILES) $(HOST_OFILES)
+(and $(EXTRA_OFILES), which is usually empty).  The superior
+'make' passes in $(HOST_OFILES); the others are fixed
+in the Makefile.
+
+ADDING A NEW CONFIGURATION
+==========================
+
+On most hosts you should be able to use the scheme for automatically
+figuring out which files are needed.  In that case, you probably
+don't need a special Makefile stub for that configuration.
+
+If the fully automatic scheme doesn't work, you may be able to get
+by with defining EXTRA_OFILES in your Makefile stub.  This is
+a list of object file names that should be treated as required
+for this configuration - they will be included in libiberty.a,
+regardless of whatever might be in the C library.  Moreover,
+when the dummy.c program is linked, it will be linked with
+$(EXTRA_OFILES).  Therefore, if a function in functions.def
+is defined by one of the EXTRA_OFILES, it will not be listed as
+"needed".  Thus if your hal9000 host needs a special implementation
+of getcwd, you can just create hal9000-getcwd.c, and define:
+	EXTRA_OFILES=hal9000-getcwd.o
+Or if you want to use the libiberty version of strstr(),
+even though there is a version in the C library (it might be
+buggy or slow), just define:
+	EXTRA_OFILES=strstr.o
+
+You can create a "manual" host configuration FOO with a file
+config/mh-FOO.  In it, the HOST_OFILES macro should explicitly
+list that subset of the optional files that should be in the
+library.  You should also set:
+	DO_ALSO =
+This overrides all of the magic needed to automatically
+determine which files are "needed."  However, keeping that list
+up to date is another matter...
+
+HOW THE MANUAL CONFIGURATION WORKS
+==================================
+
+This also uses a recursive make, but the superior make
+does not do anything interesting - it just calls the
+inferior make with HOST_OFILES defined as $(HOST_OFILES),
+which is the list you created in your configuration.
+
+You probably don't want to depend on manual configuration,
+because keeping the HOST_OFILES list up-to-date will be a pain.