129 lines
5.4 KiB
Plaintext
129 lines
5.4 KiB
Plaintext
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.
|