libiberty/README

   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 "bug-gnu-utils@prep.ai.mit.edu".  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.