README revision 38889
1This directory contains the -liberty library of free software. 2It is a collection of subroutines used by various GNU programs. 3Current members include: 4 5 getopt -- get options from command line 6 obstack -- stacks of arbitrarily-sized objects 7 strerror -- error message strings corresponding to errno 8 strtol -- string-to-long conversion 9 strtoul -- string-to-unsigned-long conversion 10 11We expect many of the GNU subroutines that are floating around to 12eventually arrive here. 13 14The library must be configured from the top source directory. Don't 15try to run configure in this directory. Follow the configuration 16instructions in ../README. 17 18Please report bugs and fixes to "bug-gnu-utils@prep.ai.mit.edu". Thank you. 19 20ADDING A NEW FILE 21================= 22 23There are two sets of files: Those that are "required" will be 24included in the library for all configurations, while those 25that are "optional" will be included in the library only if "needed." 26 27To add a new required file, edit Makefile to add the source file 28name to CFILES and the object file to REQUIRED_OFILES. 29 30Adding a new optional file is more fragile. As a general rule, 31an optional file will be included in the library if it provides 32functionality missing in the "standard" C library. 33For most hosts, the Makefile automatically figures out which 34functionality is missing by compiling and linking a dummy test 35program, and examining the error messages. 36 37So to get this to work, you should do the following: 38 391) Select one function defined in the file you're adding. 40For example, the getcwd function. 412) Add that function to the list in the file functions.def. 423) The name of the new file must be the same as the function 43you've chosen with the .c suffix added. E.g. getcwd() must be 44defined in getcwd.c. (The file can define other functions as well.) 454) In Makefile.in, add the name of the source file (e.g. getcwd.c) 46to CFILES. 47 48The file you've added (e.g. getcwd.c) should compile and work 49on all hosts where it is needed (e.g. not found when linking 50the dummy.c program). It does not have to work or even 51compile on hosts where it is not needed. 52 53HOW THE AUTOMATIC CONFIGURATION WORKS 54===================================== 55 56The libiberty.a target (in RULE1) depends on $(DO_ALSO). 57For normal configurations, DO_ALSO=needed-list. 58 59So needed-list is first made. The needed-list rule compiles 60dummy.c. Because dummy.c includes functions.def, the 61resulting object file will contain a call to each of the 62optional functions (for simplicity assume each optional file 63defines a single function). This object file will be linked 64against the standard libraries (as defined by using $(CC) 65and various flags). Any function missing will causes the 66linker to emit an error message. We assume the name 67of the missing function(s) are in the error message(s). 68The awk script find-needed.awk has been generated from 69functions.def. It is used to search the linker output 70messages for words that match the functions listed in 71functions.def. The list of functions found is written 72on a single line to the file needed-list. 73 74After needed-list has been generated, the libiberty.a 75target (in RULE1) just calls 'make' recursively. 76It passes the contents of needed-list using the 77definition (expanded) HOST_OFILES="`cat needed-list`". 78It also tells the inferior 'make' to use RULE2. 79 80The inferior 'make' is very conventional: The main 81rule is $(RULE2) (which is libiberty.a). It depends 82on a list of object files: $(REQUIRED_OFILES) $(HOST_OFILES) 83(and $(EXTRA_OFILES), which is usually empty). The superior 84'make' passes in $(HOST_OFILES); the others are fixed 85in the Makefile. 86 87ADDING A NEW CONFIGURATION 88========================== 89 90On most hosts you should be able to use the scheme for automatically 91figuring out which files are needed. In that case, you probably 92don't need a special Makefile stub for that configuration. 93 94If the fully automatic scheme doesn't work, you may be able to get 95by with defining EXTRA_OFILES in your Makefile stub. This is 96a list of object file names that should be treated as required 97for this configuration - they will be included in libiberty.a, 98regardless of whatever might be in the C library. Moreover, 99when the dummy.c program is linked, it will be linked with 100$(EXTRA_OFILES). Therefore, if a function in functions.def 101is defined by one of the EXTRA_OFILES, it will not be listed as 102"needed". Thus if your hal9000 host needs a special implementation 103of getcwd, you can just create hal9000-getcwd.c, and define: 104 EXTRA_OFILES=hal9000-getcwd.o 105Or if you want to use the libiberty version of strstr(), 106even though there is a version in the C library (it might be 107buggy or slow), just define: 108 EXTRA_OFILES=strstr.o 109 110You can create a "manual" host configuration FOO with a file 111config/mh-FOO. In it, the HOST_OFILES macro should explicitly 112list that subset of the optional files that should be in the 113library. You should also set: 114 DO_ALSO = 115This overrides all of the magic needed to automatically 116determine which files are "needed." However, keeping that list 117up to date is another matter... 118 119HOW THE MANUAL CONFIGURATION WORKS 120================================== 121 122This also uses a recursive make, but the superior make 123does not do anything interesting - it just calls the 124inferior make with HOST_OFILES defined as $(HOST_OFILES), 125which is the list you created in your configuration. 126 127You probably don't want to depend on manual configuration, 128because keeping the HOST_OFILES list up-to-date will be a pain. 129