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