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