Return to README CVS log

Up to [Apple XNU] / GNUtools / libg++ / libiberty

Annotation of GNUtools/libg++/libiberty/README, revision 1.1

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.