contrib/binutils-2.21/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 to "gcc-bugs@gcc.gnu.org" and send fixes to
  19 "gcc-patches@gcc.gnu.org".  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.in to add the source file
  29 name to CFILES and the object file to REQUIRED_OFILES.
  30
  31 To add a new optional file, it must provide a single function, and the
  32 name of the function must be the same as the name of the file.
  33
  34     * Add the source file name to CFILES in Makefile.in and the object
  35       file to CONFIGURED_OFILES.
  36
  37     * Add the function to name to the funcs shell variable in
  38       configure.ac.
  39
  40     * Add the function to the AC_CHECK_FUNCS lists just after the
  41       setting of the funcs shell variable.  These AC_CHECK_FUNCS calls
  42       are never executed; they are there to make autoheader work
  43       better.
  44
  45     * Consider the special cases of building libiberty; as of this
  46       writing, the special cases are newlib and VxWorks.  If a
  47       particular special case provides the function, you do not need
  48       to do anything.  If it does not provide the function, add the
  49       object file to LIBOBJS, and add the function name to the case
  50       controlling whether to define HAVE_func.
  51
  52 Finally, in the build directory of libiberty, configure with
  53 "--enable-maintainer-mode", run "make maint-deps" to update
  54 Makefile.in, and run 'make stamp-functions' to regenerate
  55 functions.texi.
  56
  57 The optional file you've added (e.g. getcwd.c) should compile and work
  58 on all hosts where it is needed.  It does not have to work or even
  59 compile on hosts where it is not needed.
  60
  61 ADDING A NEW CONFIGURATION
  62 ==========================
  63
  64 On most hosts you should be able to use the scheme for automatically
  65 figuring out which files are needed.  In that case, you probably
  66 don't need a special Makefile stub for that configuration.
  67
  68 If the fully automatic scheme doesn't work, you may be able to get
  69 by with defining EXTRA_OFILES in your Makefile stub.  This is
  70 a list of object file names that should be treated as required
  71 for this configuration - they will be included in libiberty.a,
  72 regardless of whatever might be in the C library.