| 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. |
| |
| The library must be configured from the top source directory. Don't |
| try to run configure in this directory. Follow the configuration |
| instructions in ../README. |
| |
| 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. |