[thirdparty/gcc.git] / libiberty / README

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 to "gcc-bugs@gcc.gnu.org" and send fixes to
"gcc-patches@gcc.gnu.org".  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.

To add a new optional file, it must provide a single function, and the
name of the function must be the same as the name of the file.

    * Add the source file name to CFILES.

    * Add the function to name to the funcs shell variable in
      configure.ac.

    * Add the function to the AC_CHECK_FUNCS lists just after the
      setting of the funcs shell variable.  These AC_CHECK_FUNCS calls
      are never executed; they are there to make autoheader work
      better.

    * Consider the special cases of building libiberty; as of this
      writing, the special cases are newlib and VxWorks.  If a
      particular special case provides the function, you do not need
      to do anything.  If it does not provide the function, add the
      object file to LIBOBJS, and add the function name to the case
      controlling whether to define HAVE_func.

The optional file you've added (e.g. getcwd.c) should compile and work
on all hosts where it is needed.  It does not have to work or even
compile on hosts where it is not needed.

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.
Commit	Line	Data
6599da04 JM	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
19ddc834 JM	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.
6599da04	17
8d87f295 NC	18	Please report bugs to "gcc-bugs@gcc.gnu.org" and send fixes to
8d87f295 NC	19	"gcc-patches@gcc.gnu.org". Thank you.
6599da04 JM	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
3affd5f0 JL	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.
	35
	36	* Add the function to name to the funcs shell variable in
c31d56ed	37	configure.ac.
6599da04	38
3affd5f0 JL	39	* Add the function to the AC_CHECK_FUNCS lists just after the
	40	setting of the funcs shell variable. These AC_CHECK_FUNCS calls
	41	are never executed; they are there to make autoheader work
	42	better.
	43
	44	* Consider the special cases of building libiberty; as of this
	45	writing, the special cases are newlib and VxWorks. If a
	46	particular special case provides the function, you do not need
	47	to do anything. If it does not provide the function, add the
	48	object file to LIBOBJS, and add the function name to the case
	49	controlling whether to define HAVE_func.
	50
	51	The optional file you've added (e.g. getcwd.c) should compile and work
	52	on all hosts where it is needed. It does not have to work or even
	53	compile on hosts where it is not needed.
6599da04 JM	54
	55	ADDING A NEW CONFIGURATION
	56	==========================
	57
	58	On most hosts you should be able to use the scheme for automatically
	59	figuring out which files are needed. In that case, you probably
	60	don't need a special Makefile stub for that configuration.
	61
	62	If the fully automatic scheme doesn't work, you may be able to get
	63	by with defining EXTRA_OFILES in your Makefile stub. This is
	64	a list of object file names that should be treated as required
	65	for this configuration - they will be included in libiberty.a,
3affd5f0	66	regardless of whatever might be in the C library.