README revision 38889
133965SjdpThis directory contains the -liberty library of free software. 233965SjdpIt is a collection of subroutines used by various GNU programs. 333965SjdpCurrent members include: 433965Sjdp 533965Sjdp getopt -- get options from command line 633965Sjdp obstack -- stacks of arbitrarily-sized objects 733965Sjdp strerror -- error message strings corresponding to errno 833965Sjdp strtol -- string-to-long conversion 933965Sjdp strtoul -- string-to-unsigned-long conversion 1033965Sjdp 1133965SjdpWe expect many of the GNU subroutines that are floating around to 1233965Sjdpeventually arrive here. 1333965Sjdp 1438889SjdpThe library must be configured from the top source directory. Don't 1538889Sjdptry to run configure in this directory. Follow the configuration 1638889Sjdpinstructions in ../README. 1733965Sjdp 1833965SjdpPlease report bugs and fixes to "bug-gnu-utils@prep.ai.mit.edu". Thank you. 1933965Sjdp 2033965SjdpADDING A NEW FILE 2133965Sjdp================= 2233965Sjdp 2333965SjdpThere are two sets of files: Those that are "required" will be 2433965Sjdpincluded in the library for all configurations, while those 2533965Sjdpthat are "optional" will be included in the library only if "needed." 2633965Sjdp 2733965SjdpTo add a new required file, edit Makefile to add the source file 2833965Sjdpname to CFILES and the object file to REQUIRED_OFILES. 2933965Sjdp 3033965SjdpAdding a new optional file is more fragile. As a general rule, 3133965Sjdpan optional file will be included in the library if it provides 3233965Sjdpfunctionality missing in the "standard" C library. 3333965SjdpFor most hosts, the Makefile automatically figures out which 3433965Sjdpfunctionality is missing by compiling and linking a dummy test 3533965Sjdpprogram, and examining the error messages. 3633965Sjdp 3733965SjdpSo to get this to work, you should do the following: 3833965Sjdp 3933965Sjdp1) Select one function defined in the file you're adding. 4033965SjdpFor example, the getcwd function. 4133965Sjdp2) Add that function to the list in the file functions.def. 4233965Sjdp3) The name of the new file must be the same as the function 4333965Sjdpyou've chosen with the .c suffix added. E.g. getcwd() must be 4433965Sjdpdefined in getcwd.c. (The file can define other functions as well.) 4533965Sjdp4) In Makefile.in, add the name of the source file (e.g. getcwd.c) 4633965Sjdpto CFILES. 4733965Sjdp 4833965SjdpThe file you've added (e.g. getcwd.c) should compile and work 4933965Sjdpon all hosts where it is needed (e.g. not found when linking 5033965Sjdpthe dummy.c program). It does not have to work or even 5133965Sjdpcompile on hosts where it is not needed. 5233965Sjdp 5333965SjdpHOW THE AUTOMATIC CONFIGURATION WORKS 5433965Sjdp===================================== 5533965Sjdp 5633965SjdpThe libiberty.a target (in RULE1) depends on $(DO_ALSO). 5733965SjdpFor normal configurations, DO_ALSO=needed-list. 5833965Sjdp 5933965SjdpSo needed-list is first made. The needed-list rule compiles 6033965Sjdpdummy.c. Because dummy.c includes functions.def, the 6133965Sjdpresulting object file will contain a call to each of the 6233965Sjdpoptional functions (for simplicity assume each optional file 6333965Sjdpdefines a single function). This object file will be linked 6433965Sjdpagainst the standard libraries (as defined by using $(CC) 6533965Sjdpand various flags). Any function missing will causes the 6633965Sjdplinker to emit an error message. We assume the name 6733965Sjdpof the missing function(s) are in the error message(s). 6833965SjdpThe awk script find-needed.awk has been generated from 6933965Sjdpfunctions.def. It is used to search the linker output 7033965Sjdpmessages for words that match the functions listed in 7133965Sjdpfunctions.def. The list of functions found is written 7233965Sjdpon a single line to the file needed-list. 7333965Sjdp 7433965SjdpAfter needed-list has been generated, the libiberty.a 7533965Sjdptarget (in RULE1) just calls 'make' recursively. 7633965SjdpIt passes the contents of needed-list using the 7733965Sjdpdefinition (expanded) HOST_OFILES="`cat needed-list`". 7833965SjdpIt also tells the inferior 'make' to use RULE2. 7933965Sjdp 8033965SjdpThe inferior 'make' is very conventional: The main 8133965Sjdprule is $(RULE2) (which is libiberty.a). It depends 8233965Sjdpon a list of object files: $(REQUIRED_OFILES) $(HOST_OFILES) 8333965Sjdp(and $(EXTRA_OFILES), which is usually empty). The superior 8433965Sjdp'make' passes in $(HOST_OFILES); the others are fixed 8533965Sjdpin the Makefile. 8633965Sjdp 8733965SjdpADDING A NEW CONFIGURATION 8833965Sjdp========================== 8933965Sjdp 9033965SjdpOn most hosts you should be able to use the scheme for automatically 9133965Sjdpfiguring out which files are needed. In that case, you probably 9233965Sjdpdon't need a special Makefile stub for that configuration. 9333965Sjdp 9433965SjdpIf the fully automatic scheme doesn't work, you may be able to get 9533965Sjdpby with defining EXTRA_OFILES in your Makefile stub. This is 9633965Sjdpa list of object file names that should be treated as required 9733965Sjdpfor this configuration - they will be included in libiberty.a, 9833965Sjdpregardless of whatever might be in the C library. Moreover, 9933965Sjdpwhen the dummy.c program is linked, it will be linked with 10033965Sjdp$(EXTRA_OFILES). Therefore, if a function in functions.def 10133965Sjdpis defined by one of the EXTRA_OFILES, it will not be listed as 10233965Sjdp"needed". Thus if your hal9000 host needs a special implementation 10333965Sjdpof getcwd, you can just create hal9000-getcwd.c, and define: 10433965Sjdp EXTRA_OFILES=hal9000-getcwd.o 10533965SjdpOr if you want to use the libiberty version of strstr(), 10633965Sjdpeven though there is a version in the C library (it might be 10733965Sjdpbuggy or slow), just define: 10833965Sjdp EXTRA_OFILES=strstr.o 10933965Sjdp 11033965SjdpYou can create a "manual" host configuration FOO with a file 11133965Sjdpconfig/mh-FOO. In it, the HOST_OFILES macro should explicitly 11233965Sjdplist that subset of the optional files that should be in the 11333965Sjdplibrary. You should also set: 11433965Sjdp DO_ALSO = 11533965SjdpThis overrides all of the magic needed to automatically 11633965Sjdpdetermine which files are "needed." However, keeping that list 11733965Sjdpup to date is another matter... 11833965Sjdp 11933965SjdpHOW THE MANUAL CONFIGURATION WORKS 12033965Sjdp================================== 12133965Sjdp 12233965SjdpThis also uses a recursive make, but the superior make 12333965Sjdpdoes not do anything interesting - it just calls the 12433965Sjdpinferior make with HOST_OFILES defined as $(HOST_OFILES), 12533965Sjdpwhich is the list you created in your configuration. 12633965Sjdp 12733965SjdpYou probably don't want to depend on manual configuration, 12833965Sjdpbecause keeping the HOST_OFILES list up-to-date will be a pain. 129