newlib/README - native_client/nacl-newlib - Git at Google

                         README for newlib-2.1.0 release
            (mostly cribbed from the README in the gdb-4.13 release)

 This is `newlib', a simple ANSI C library, math library, and collection
 of board support packages.

 The newlib and libgloss subdirectories are a collection of software from
 several sources, each wi6h their own copyright and license.  See the file
 COPYING.NEWLIB for details.  The rest of the release tree is under either
 the GNU GPL or LGPL licenses.

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.


 Unpacking and Installation -- quick overview
 ==========================

 When you unpack the newlib-2.1.0.tar.gz file, you'll find a directory
 called `newlib-2.1.0', which contains:

 COPYING          config/          install-sh*      mpw-configure
 COPYING.LIB      config-ml.in     libgloss/        mpw-install
 COPYING.NEWLIB   config.guess*    mkinstalldirs*   newlib/
 CYGNUS           config.sub*      move-if-change*  symlink-tree*
 ChangeLog        configure*       mpw-README       texinfo/
 Makefile.in      configure.in     mpw-build.in
 README           etc/             mpw-config.in

 To build NEWLIB, you must follow the instructions in the section entitled
 "Compiling NEWLIB".

 This will configure and build all the libraries and crt0 (if one exists).
 If `configure' can't determine your host system type, specify one as its
 argument, e.g., sun4 or sun4sol2.  NEWLIB is most often used in cross
 environments.

 NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS.


 More Documentation
 ==================

    Newlib documentation is available on the net via:
    http://sourceware.org/newlib/docs.html

    All the documentation for NEWLIB comes as part of the machine-readable
 distribution.  The documentation is written in Texinfo format, which is
 a documentation system that uses a single source file to produce both
 on-line information and a printed manual.  You can use one of the Info
 formatting commands to create the on-line version of the documentation
 and TeX (or `texi2roff') to typeset the printed version.

    If you want to format these Info files yourself, you need one of the
 Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.

    If you want to typeset and print copies of this manual, you need TeX,
 a program to print its DVI output files, and `texinfo.tex', the Texinfo
 definitions file.

    TeX is a typesetting program; it does not print files directly, but
 produces output files called DVI files.  To print a typeset document,
 you need a program to print DVI files.  If your system has TeX
 installed, chances are it has such a program.  The precise command to
 use depends on your system; `lpr -d' is common; another (for PostScript
 devices) is `dvips'.  The DVI print command may require a file name
 without any extension or a `.dvi' extension.

    TeX also requires a macro definitions file called `texinfo.tex'.
 This file tells TeX how to typeset a document written in Texinfo
 format.  On its own, TeX cannot read, much less typeset a Texinfo file.
 `texinfo.tex' is distributed with NEWLIB and is located in the
 `newlib-VERSION-NUMBER/texinfo' directory.


 Compiling NEWLIB
 ================

    To compile NEWLIB, you must build it in a directory separate from
 the source directory.  If you want to run NEWLIB versions for several host
 or target machines, you need a different `newlib' compiled for each combination
 of host and target.  `configure' is designed to make this easy by allowing
 you to generate each configuration in a separate subdirectory.
 If your `make' program handles the `VPATH' feature correctly (like GNU `make')
 running `make' in each of these directories builds the `newlib' libraries
 specified there.

    To build `newlib' in a specific directory, run `configure' with the
 `--srcdir' option to specify where to find the source. (You also need
 to specify a path to find `configure' itself from your working
 directory.  If the path to `configure' would be the same as the
 argument to `--srcdir', you can leave out the `--srcdir' option; it
 will be assumed.)

    For example, with version 2.1.0, you can build NEWLIB in a separate
 directory for a Sun 4 cross m68k-aout environment like this:

      cd newlib-2.1.0
      mkdir ../newlib-m68k-aout
      cd ../newlib-m68k-aout
      ../newlib-2.1.0/configure --host=sun4 --target=m68k-aout
      make

    When `configure' builds a configuration using a remote source
 directory, it creates a tree for the binaries with the same structure
 (and using the same names) as the tree under the source directory.  In
 the example, you'd find the Sun 4 library `libiberty.a' in the
 directory `newlib-m68k-aout/libiberty', and NEWLIB itself in
 `newlib-m68k-aout/newlib'.

    When you run `make' to build a program or library, you must run it
 in a configured directory--whatever directory you were in when you
 called `configure' (or one of its subdirectories).

    The `Makefile' that `configure' generates in each source directory
 also runs recursively.  If you type `make' in a source directory such
 as `newlib-2.1.0' (or in a separate configured directory configured with
 `--srcdir=PATH/newlib-2.1.0'), you will build all the required libraries.

    When you have multiple hosts or targets configured in separate
 directories, you can run `make' on them in parallel (for example, if
 they are NFS-mounted on each of the hosts); they will not interfere
 with each other.


 Specifying names for hosts and targets
 ======================================

    The specifications used for hosts and targets in the `configure'
 script are based on a three-part naming scheme, but some short
 predefined aliases are also supported.  The full naming scheme encodes
 three pieces of information in the following pattern:

      ARCHITECTURE-VENDOR-OS

    For example, you can use the alias `sun4' as a HOST argument or in a
 `--target=TARGET' option.  The equivalent full name is
 `sparc-sun-sunos4'.

    The `configure' script accompanying NEWLIB does not provide any query
 facility to list all supported host and target names or aliases.
 `configure' calls the Bourne shell script `config.sub' to map
 abbreviations to full names; you can read the script, if you wish, or
 you can use it to test your guesses on abbreviations--for example:

      % sh config.sub sun4
      sparc-sun-sunos4.1.1
      % sh config.sub sun3
      m68k-sun-sunos4.1.1
      % sh config.sub decstation
      mips-dec-ultrix4.2
      % sh config.sub hp300bsd
      m68k-hp-bsd
      % sh config.sub i386v
      i386-pc-sysv
      % sh config.sub i786v
      Invalid configuration `i786v': machine `i786v' not recognized

 The Build, Host and Target Concepts in newlib
 =============================================

 The build, host and target concepts are defined for gcc as follows:

 build: the platform on which gcc is built.
 host: the platform on which gcc is run.
 target: the platform for which gcc generates code.

 Since newlib is a library, the target concept does not apply to it, and the
 build, host, and target options given to the top-level configure script must
 be changed for newlib's use.

 The options are shifted according to these correspondences:

 gcc's build platform has no equivalent in newlib.
 gcc's host platform is newlib's build platform.
 gcc's target platform is newlib's host platform.
 and as mentioned before, newlib has no concept of target.

 `configure' options
 ===================

    Here is a summary of the `configure' options and arguments that are
 most often useful for building NEWLIB.  `configure' also has several other
 options not listed here.

      configure [--help]
                [--prefix=DIR]
                [--srcdir=PATH]
                [--target=TARGET] HOST

 You may introduce options with a single `-' rather than `--' if you
 prefer; but you may abbreviate option names if you use `--'.

 `--help'
      Display a quick summary of how to invoke `configure'.

 `--prefix=DIR'
      Configure the source to install programs and files in directory
      `DIR'.

 `--exec-prefix=DIR'
      Configure the source to install host-dependent files in directory
      `DIR'.

 `--srcdir=PATH'
      *Warning: using this option requires GNU `make', or another `make'
      that compatibly implements the `VPATH' feature.
      Use this option to make configurations in directories separate
      from the NEWLIB source directories.  Among other things, you can use
      this to build (or maintain) several configurations simultaneously,
      in separate directories.  `configure' writes configuration
      specific files in the current directory, but arranges for them to
      use the source in the directory PATH.  `configure' will create
      directories under the working directory in parallel to the source
      directories below PATH.

 `--norecursion'
      Configure only the directory level where `configure' is executed;
      do not propagate configuration to subdirectories.

 `--target=TARGET'
      Configure NEWLIB for running on the specified TARGET.

      There is no convenient way to generate a list of all available
      targets.

 `HOST ...'
      Configure NEWLIB to be built using a cross compiler running on
      the specified HOST.

      There is no convenient way to generate a list of all available
      hosts.

 To fit diverse usage models, NEWLIB supports a group of configuration
 options so that library features can be turned on/off according to
 target system's requirements.

 One feature can be enabled by specifying `--enable-FEATURE=yes' or
 `--enable-FEATURE'.  Or it can be disable by `--enable-FEATURE=no' or
 `--disable-FEATURE'.

 `--enable-newlib-io-pos-args'
      Enable printf-family positional arg support.
      Disabled by default, but some hosts enable it in configure.host.

 `--enable-newlib-io-c99-formats'
      Enable C99 support in IO functions like printf/scanf.
      Disabled by default, but some hosts enable it in configure.host.

 `--enable-newlib-register-fini'
      Enable finalization function registration using atexit.
      Disabled by default.

 `--enable-newlib-io-long-long'
      Enable long long type support in IO functions like printf/scanf.
      Disabled by default, but many hosts enable it in configure.host.

 `--enable-newlib-io-long-double'
      Enable long double type support in IO functions printf/scanf.
      Disabled by default, but some hosts enable it in configure.host.

 `--enable-newlib-mb'
      Enable multibyte support.
      Disabled by default.

 `--enable-newlib-iconv-encodings'
      Enable specific comma-separated list of bidirectional iconv
      encodings to be built-in.
      Disabled by default.

 `--enable-newlib-iconv-from-encodings'
      Enable specific comma-separated list of \"from\" iconv encodings
      to be built-in.
      Disabled by default.

 `--enable-newlib-iconv-to-encodings'
      Enable specific comma-separated list of \"to\" iconv encodings
      to be built-in.
      Disabled by default.

 `--enable-newlib-iconv-external-ccs'
      Enable capabilities to load external CCS files for iconv.
      Disabled by default.

 `--disable-newlib-atexit-dynamic-alloc'
      Disable dynamic allocation of atexit entries.
      Most hosts and targets have it enabled in configure.host.

 `--enable-newlib-global-atexit'
      Enable atexit data structure as global variable.  By doing so it is
      move out of _reent structure, and can be garbage collected if atexit
      is not referenced.
      Disabled by default.

 `--enable-newlib-reent-small'
      Enable small reentrant struct support.
      Disabled by default.

 `--disable-newlib-fvwrite-in-streamio'
      NEWLIB implements the vector buffer mechanism to support stream IO
      buffering required by C standard.  This feature is possibly
      unnecessary for embedded systems which won't change file buffering
      with functions like `setbuf' or `setvbuf'.  The buffering mechanism
      still acts as default for STDIN/STDOUT/STDERR even if this option
      is specified.
      Enabled by default.

 `--disable-newlib-fseek-optimization'
      Disable fseek optimization.  It can decrease code size of application
      calling `fseek`.
      Enabled by default.

 `--disable-newlib-wide-orient'
      C99 states that each stream has an orientation, wide or byte.  This
      feature is possibly unnecessary for embedded systems which only do
      byte input/output operations on stream.  It can decrease code size
      by disable the feature.
      Enabled by default.

 `--enable-newlib-nano-malloc'
      NEWLIB has two implementations of malloc family's functions, one in
      `mallocr.c' and the other one in `nano-mallocr.c'.  This options
      enables the nano-malloc implementation, which is for small systems
      with very limited memory.  Note that this implementation does not
      support `--enable-malloc-debugging' any more.
      Disabled by default.

 `--disable-newlib-unbuf-stream-opt'
      NEWLIB does optimization when `fprintf to write only unbuffered unix
      file'.  It creates a temorary buffer to do the optimization that
      increases stack consumption by about `BUFSIZ' bytes.  This option
      disables the optimization and saves size of text and stack.
      Enabled by default.

 `--enable-multilib'
      Build many library versions.
      Enabled by default.

 `--enable-target-optspace'
      Optimize for space.
      Disabled by default.

 `--enable-malloc-debugging'
      Indicate malloc debugging requested.
      Disabled by default.

 `--enable-newlib-multithread'
      Enable support for multiple threads.
      Enabled by default.

 `--enable-newlib-iconv'
      Enable iconv library support.
      Disabled by default.

 `--enable-newlib-elix-level'
      Supply desired elix library level (1-4).  Please refer to HOWTO for
      more information about this option.
      Set to level 0 by default.

 `--disable-newlib-io-float'
      Disable printf/scanf family float support.
      Enabled by default.

 `--disable-newlib-supplied-syscalls'
      Disable newlib from supplying syscalls.
      Enabled by default.

 `--enable-lite-exit'
      Enable lite exit, a size-reduced implementation of exit that doesn't
      invoke clean-up functions such as _fini or global destructors.
      Disabled by default.

 Running the Testsuite
 =====================

 To run newlib's testsuite, you'll need a site.exp in your home
 directory which points dejagnu to the proper baseboards directory and
 the proper exp file for your target.

 Before running make check-target-newlib, set the DEJAGNU environment
 variable to point to ~/site.exp.

 Here is a sample site.exp:

 # Make sure we look in the right place for the board description files.
 if ![info exists boards_dir] {
     set boards_dir {}
 }
 lappend boards_dir "your dejagnu/baseboards here"

 verbose "Global Config File: target_triplet is $target_triplet" 2

 global target_list
 case "$target_triplet" in {

     { "mips-*elf*" } {
 	set target_list "mips-sim"
     }

     default {
 	set target_list { "unix" }
     }
 }

 mips-sim refers to an exp file in the baseboards directory.  You'll
 need to add the other targets you're testing to the case statement.

 Now type make check-target-newlib in the top-level build directory to
 run the testsuite.

 Shared newlib
 =============

 newlib uses libtool when it is being compiled natively (with
 --target=i[34567]86-pc-linux-gnu) on an i[34567]86-pc-linux-gnu
 host. This allows newlib to be compiled as a shared library.

 To configure newlib, do the following from your build directory:

 $(source_dir)/src/configure --with-newlib --prefix=$(install_dir)

 configure will recognize that host == target ==
 i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using
 libtool. By default, libtool will build shared and static versions of
 newlib.

 To compile a program against shared newlib, do the following (where
 target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu):

 gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc

 To run the program, make sure that $(target_install_dir)/lib is listed
 in the LD_LIBRARY_PATH environment variable.

 To create a static binary linked against newlib, do the following:

 gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm

 libtool can be instructed to produce only static libraries. To build
 newlib as a static library only, do the following from your build
 directory:

 $(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared

 Regenerating Configuration Files
 ================================

 At times you will need to make changes to configure.in and Makefile.am files.
 This will mean that configure and Makefile.in files will need to be
 regenerated.

 At the top level of newlib is the file: acinclude.m4.  This file contains
 the definition of the NEWLIB_CONFIGURE macro which is used by all configure.in
 files in newlib.  You will notice that each directory in newlib containing
 a configure.in file also contains an aclocal.m4 file.  This file is
 generated by issuing: aclocal -I${relative_path_to_toplevel_newlib_dir}
 -I${relative_path_to_toplevel_src_dir}
 The first relative directory is to access acinclude.m4.  The second relative
 directory is to access libtool information in the top-level src directory.

 For example, to regenerate aclocal.m4 in newlib/libc/machine/arm:

   aclocal -I ../../.. -I ../../../..

 Note that if the top level acinclude.m4 is altered, every aclocal.m4 file
 in newlib should be regenerated.

 If the aclocal.m4 file is regenerated due to a change in acinclude.m4 or
 if a configure.in file is modified, the corresponding configure file in the
 directory must be regenerated using autoconf.  No parameters are necessary.
 In the previous example, we would issue:

   autoconf

 from the newlib/libc/machine/arm directory.

 If you have regenerated a configure file or if you have modified a Makefile.am
 file, you will need to regenerate the appropriate Makefile.in file(s).
 For newlib, automake is a bit trickier.  First of all, all Makefile.in
 files in newlib (and libgloss) are generated using the --cygnus option
 of automake.

 Makefile.in files are generated from the nearest directory up the chain
 which contains a configure.in file.  In most cases, this is the same
 directory containing configure.in, but there are exceptions.
 For example, the newlib/libc directory has a number of
 subdirectories that do not contain their own configure.in files (e.g. stdio).
 For these directories, you must issue the automake command from newlib/libc
 which is the nearest parent directory that contains a configure.in.
 When you issue the automake command, you specify the subdirectory for
 the Makefile.in you are regenerating.  For example:

    automake --cygnus stdio/Makefile stdlib/Makefile

 Note how multiple Makefile.in files can be created in the same step.  You
 would not specify machine/Makefile or sys/Makefile in the previous example
 because both of these subdirectories contain their own configure.in files.
 One would change to each of these subdirectories and in turn issue:

    automake --cygnus Makefile

 Let's say you create a new machine directory XXXX off of newlib/libc/machine.
 After creating a new configure.in and Makefile.am file, you would issue:

    aclocal -I ../../..
    autoconf
    automake --cygnus Makefile

 from newlib/libc/machine/XXXX

 It is strongly advised that you use an adequate version of autotools.
 For this latest release, the following were used: autoconf 2.69, aclocal 1.13.4, and
 automake 1.13.4.

 Reporting Bugs
 ==============

 The correct address for reporting bugs found in NEWLIB is
 "newlib@sourceware.org".  Please email all bug reports to that
 address.  Please include the NEWLIB version number (e.g., newlib-2.1.0),
 and how you configured it (e.g., "sun4 host and m68k-aout target").
 Since NEWLIB supports many different configurations, it is important
 that you be precise about this.

 Archives of the newlib mailing list are on-line, see
 	http://sourceware.org/ml/newlib/
	README for newlib-2.1.0 release
	(mostly cribbed from the README in the gdb-4.13 release)

	This is `newlib', a simple ANSI C library, math library, and collection
	of board support packages.

	The newlib and libgloss subdirectories are a collection of software from
	several sources, each wi6h their own copyright and license. See the file
	COPYING.NEWLIB for details. The rest of the release tree is under either
	the GNU GPL or LGPL licenses.

	THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
	IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
	WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.


	Unpacking and Installation -- quick overview
	==========================

	When you unpack the newlib-2.1.0.tar.gz file, you'll find a directory
	called `newlib-2.1.0', which contains:

	COPYING config/ install-sh* mpw-configure
	COPYING.LIB config-ml.in libgloss/ mpw-install
	COPYING.NEWLIB config.guess* mkinstalldirs* newlib/
	CYGNUS config.sub* move-if-change* symlink-tree*
	ChangeLog configure* mpw-README texinfo/
	Makefile.in configure.in mpw-build.in
	README etc/ mpw-config.in

	To build NEWLIB, you must follow the instructions in the section entitled
	"Compiling NEWLIB".

	This will configure and build all the libraries and crt0 (if one exists).
	If `configure' can't determine your host system type, specify one as its
	argument, e.g., sun4 or sun4sol2. NEWLIB is most often used in cross
	environments.

	NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS.


	More Documentation
	==================

	Newlib documentation is available on the net via:
	http://sourceware.org/newlib/docs.html

	All the documentation for NEWLIB comes as part of the machine-readable
	distribution. The documentation is written in Texinfo format, which is
	a documentation system that uses a single source file to produce both
	on-line information and a printed manual. You can use one of the Info
	formatting commands to create the on-line version of the documentation
	and TeX (or `texi2roff') to typeset the printed version.

	If you want to format these Info files yourself, you need one of the
	Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.

	If you want to typeset and print copies of this manual, you need TeX,
	a program to print its DVI output files, and `texinfo.tex', the Texinfo
	definitions file.

	TeX is a typesetting program; it does not print files directly, but
	produces output files called DVI files. To print a typeset document,
	you need a program to print DVI files. If your system has TeX
	installed, chances are it has such a program. The precise command to
	use depends on your system; `lpr -d' is common; another (for PostScript
	devices) is `dvips'. The DVI print command may require a file name
	without any extension or a `.dvi' extension.

	TeX also requires a macro definitions file called `texinfo.tex'.
	This file tells TeX how to typeset a document written in Texinfo
	format. On its own, TeX cannot read, much less typeset a Texinfo file.
	`texinfo.tex' is distributed with NEWLIB and is located in the
	`newlib-VERSION-NUMBER/texinfo' directory.



	Compiling NEWLIB
	================

	To compile NEWLIB, you must build it in a directory separate from
	the source directory. If you want to run NEWLIB versions for several host
	or target machines, you need a different `newlib' compiled for each combination
	of host and target. `configure' is designed to make this easy by allowing
	you to generate each configuration in a separate subdirectory.
	If your `make' program handles the `VPATH' feature correctly (like GNU `make')
	running `make' in each of these directories builds the `newlib' libraries
	specified there.

	To build `newlib' in a specific directory, run `configure' with the
	`--srcdir' option to specify where to find the source. (You also need
	to specify a path to find `configure' itself from your working
	directory. If the path to `configure' would be the same as the
	argument to `--srcdir', you can leave out the `--srcdir' option; it
	will be assumed.)

	For example, with version 2.1.0, you can build NEWLIB in a separate
	directory for a Sun 4 cross m68k-aout environment like this:

	cd newlib-2.1.0
	mkdir ../newlib-m68k-aout
	cd ../newlib-m68k-aout
	../newlib-2.1.0/configure --host=sun4 --target=m68k-aout
	make

	When `configure' builds a configuration using a remote source
	directory, it creates a tree for the binaries with the same structure
	(and using the same names) as the tree under the source directory. In
	the example, you'd find the Sun 4 library `libiberty.a' in the
	directory `newlib-m68k-aout/libiberty', and NEWLIB itself in
	`newlib-m68k-aout/newlib'.

	When you run `make' to build a program or library, you must run it
	in a configured directory--whatever directory you were in when you
	called `configure' (or one of its subdirectories).

	The `Makefile' that `configure' generates in each source directory
	also runs recursively. If you type `make' in a source directory such
	as `newlib-2.1.0' (or in a separate configured directory configured with
	`--srcdir=PATH/newlib-2.1.0'), you will build all the required libraries.

	When you have multiple hosts or targets configured in separate
	directories, you can run `make' on them in parallel (for example, if
	they are NFS-mounted on each of the hosts); they will not interfere
	with each other.


	Specifying names for hosts and targets
	======================================

	The specifications used for hosts and targets in the `configure'
	script are based on a three-part naming scheme, but some short
	predefined aliases are also supported. The full naming scheme encodes
	three pieces of information in the following pattern:

	ARCHITECTURE-VENDOR-OS

	For example, you can use the alias `sun4' as a HOST argument or in a
	`--target=TARGET' option. The equivalent full name is
	`sparc-sun-sunos4'.

	The `configure' script accompanying NEWLIB does not provide any query
	facility to list all supported host and target names or aliases.
	`configure' calls the Bourne shell script `config.sub' to map
	abbreviations to full names; you can read the script, if you wish, or
	you can use it to test your guesses on abbreviations--for example:

	% sh config.sub sun4
	sparc-sun-sunos4.1.1
	% sh config.sub sun3
	m68k-sun-sunos4.1.1
	% sh config.sub decstation
	mips-dec-ultrix4.2
	% sh config.sub hp300bsd
	m68k-hp-bsd
	% sh config.sub i386v
	i386-pc-sysv
	% sh config.sub i786v
	Invalid configuration `i786v': machine `i786v' not recognized

	The Build, Host and Target Concepts in newlib
	=============================================

	The build, host and target concepts are defined for gcc as follows:

	build: the platform on which gcc is built.
	host: the platform on which gcc is run.
	target: the platform for which gcc generates code.

	Since newlib is a library, the target concept does not apply to it, and the
	build, host, and target options given to the top-level configure script must
	be changed for newlib's use.

	The options are shifted according to these correspondences:

	gcc's build platform has no equivalent in newlib.
	gcc's host platform is newlib's build platform.
	gcc's target platform is newlib's host platform.
	and as mentioned before, newlib has no concept of target.

	`configure' options
	===================

	Here is a summary of the `configure' options and arguments that are
	most often useful for building NEWLIB. `configure' also has several other
	options not listed here.

	configure [--help]
	[--prefix=DIR]
	[--srcdir=PATH]
	[--target=TARGET] HOST

	You may introduce options with a single `-' rather than `--' if you
	prefer; but you may abbreviate option names if you use `--'.

	`--help'
	Display a quick summary of how to invoke `configure'.

	`--prefix=DIR'
	Configure the source to install programs and files in directory
	`DIR'.

	`--exec-prefix=DIR'
	Configure the source to install host-dependent files in directory
	`DIR'.

	`--srcdir=PATH'
	*Warning: using this option requires GNU `make', or another `make'
	that compatibly implements the `VPATH' feature.
	Use this option to make configurations in directories separate
	from the NEWLIB source directories. Among other things, you can use
	this to build (or maintain) several configurations simultaneously,
	in separate directories. `configure' writes configuration
	specific files in the current directory, but arranges for them to
	use the source in the directory PATH. `configure' will create
	directories under the working directory in parallel to the source
	directories below PATH.

	`--norecursion'
	Configure only the directory level where `configure' is executed;
	do not propagate configuration to subdirectories.

	`--target=TARGET'
	Configure NEWLIB for running on the specified TARGET.

	There is no convenient way to generate a list of all available
	targets.

	`HOST ...'
	Configure NEWLIB to be built using a cross compiler running on
	the specified HOST.

	There is no convenient way to generate a list of all available
	hosts.

	To fit diverse usage models, NEWLIB supports a group of configuration
	options so that library features can be turned on/off according to
	target system's requirements.

	One feature can be enabled by specifying `--enable-FEATURE=yes' or
	`--enable-FEATURE'. Or it can be disable by `--enable-FEATURE=no' or
	`--disable-FEATURE'.

	`--enable-newlib-io-pos-args'
	Enable printf-family positional arg support.
	Disabled by default, but some hosts enable it in configure.host.

	`--enable-newlib-io-c99-formats'
	Enable C99 support in IO functions like printf/scanf.
	Disabled by default, but some hosts enable it in configure.host.

	`--enable-newlib-register-fini'
	Enable finalization function registration using atexit.
	Disabled by default.

	`--enable-newlib-io-long-long'
	Enable long long type support in IO functions like printf/scanf.
	Disabled by default, but many hosts enable it in configure.host.

	`--enable-newlib-io-long-double'
	Enable long double type support in IO functions printf/scanf.
	Disabled by default, but some hosts enable it in configure.host.

	`--enable-newlib-mb'
	Enable multibyte support.
	Disabled by default.

	`--enable-newlib-iconv-encodings'
	Enable specific comma-separated list of bidirectional iconv
	encodings to be built-in.
	Disabled by default.

	`--enable-newlib-iconv-from-encodings'
	Enable specific comma-separated list of \"from\" iconv encodings
	to be built-in.
	Disabled by default.

	`--enable-newlib-iconv-to-encodings'
	Enable specific comma-separated list of \"to\" iconv encodings
	to be built-in.
	Disabled by default.

	`--enable-newlib-iconv-external-ccs'
	Enable capabilities to load external CCS files for iconv.
	Disabled by default.

	`--disable-newlib-atexit-dynamic-alloc'
	Disable dynamic allocation of atexit entries.
	Most hosts and targets have it enabled in configure.host.

	`--enable-newlib-global-atexit'
	Enable atexit data structure as global variable. By doing so it is
	move out of _reent structure, and can be garbage collected if atexit
	is not referenced.
	Disabled by default.

	`--enable-newlib-reent-small'
	Enable small reentrant struct support.
	Disabled by default.

	`--disable-newlib-fvwrite-in-streamio'
	NEWLIB implements the vector buffer mechanism to support stream IO
	buffering required by C standard. This feature is possibly
	unnecessary for embedded systems which won't change file buffering
	with functions like `setbuf' or `setvbuf'. The buffering mechanism
	still acts as default for STDIN/STDOUT/STDERR even if this option
	is specified.
	Enabled by default.

	`--disable-newlib-fseek-optimization'
	Disable fseek optimization. It can decrease code size of application
	calling `fseek`.
	Enabled by default.

	`--disable-newlib-wide-orient'
	C99 states that each stream has an orientation, wide or byte. This
	feature is possibly unnecessary for embedded systems which only do
	byte input/output operations on stream. It can decrease code size
	by disable the feature.
	Enabled by default.

	`--enable-newlib-nano-malloc'
	NEWLIB has two implementations of malloc family's functions, one in
	`mallocr.c' and the other one in `nano-mallocr.c'. This options
	enables the nano-malloc implementation, which is for small systems
	with very limited memory. Note that this implementation does not
	support `--enable-malloc-debugging' any more.
	Disabled by default.

	`--disable-newlib-unbuf-stream-opt'
	NEWLIB does optimization when `fprintf to write only unbuffered unix
	file'. It creates a temorary buffer to do the optimization that
	increases stack consumption by about `BUFSIZ' bytes. This option
	disables the optimization and saves size of text and stack.
	Enabled by default.

	`--enable-multilib'
	Build many library versions.
	Enabled by default.

	`--enable-target-optspace'
	Optimize for space.
	Disabled by default.

	`--enable-malloc-debugging'
	Indicate malloc debugging requested.
	Disabled by default.

	`--enable-newlib-multithread'
	Enable support for multiple threads.
	Enabled by default.

	`--enable-newlib-iconv'
	Enable iconv library support.
	Disabled by default.

	`--enable-newlib-elix-level'
	Supply desired elix library level (1-4). Please refer to HOWTO for
	more information about this option.
	Set to level 0 by default.

	`--disable-newlib-io-float'
	Disable printf/scanf family float support.
	Enabled by default.

	`--disable-newlib-supplied-syscalls'
	Disable newlib from supplying syscalls.
	Enabled by default.

	`--enable-lite-exit'
	Enable lite exit, a size-reduced implementation of exit that doesn't
	invoke clean-up functions such as _fini or global destructors.
	Disabled by default.

	Running the Testsuite
	=====================

	To run newlib's testsuite, you'll need a site.exp in your home
	directory which points dejagnu to the proper baseboards directory and
	the proper exp file for your target.

	Before running make check-target-newlib, set the DEJAGNU environment
	variable to point to ~/site.exp.

	Here is a sample site.exp:

	# Make sure we look in the right place for the board description files.
	if ![info exists boards_dir] {
	set boards_dir {}
	}
	lappend boards_dir "your dejagnu/baseboards here"

	verbose "Global Config File: target_triplet is $target_triplet" 2

	global target_list
	case "$target_triplet" in {

	{ "mips-elf" } {
	set target_list "mips-sim"
	}

	default {
	set target_list { "unix" }
	}
	}

	mips-sim refers to an exp file in the baseboards directory. You'll
	need to add the other targets you're testing to the case statement.

	Now type make check-target-newlib in the top-level build directory to
	run the testsuite.

	Shared newlib
	=============

	newlib uses libtool when it is being compiled natively (with
	--target=i[34567]86-pc-linux-gnu) on an i[34567]86-pc-linux-gnu
	host. This allows newlib to be compiled as a shared library.

	To configure newlib, do the following from your build directory:

	$(source_dir)/src/configure --with-newlib --prefix=$(install_dir)

	configure will recognize that host == target ==
	i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using
	libtool. By default, libtool will build shared and static versions of
	newlib.

	To compile a program against shared newlib, do the following (where
	target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu):

	gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc

	To run the program, make sure that $(target_install_dir)/lib is listed
	in the LD_LIBRARY_PATH environment variable.

	To create a static binary linked against newlib, do the following:

	gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm

	libtool can be instructed to produce only static libraries. To build
	newlib as a static library only, do the following from your build
	directory:

	$(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared

	Regenerating Configuration Files
	================================

	At times you will need to make changes to configure.in and Makefile.am files.
	This will mean that configure and Makefile.in files will need to be
	regenerated.

	At the top level of newlib is the file: acinclude.m4. This file contains
	the definition of the NEWLIB_CONFIGURE macro which is used by all configure.in
	files in newlib. You will notice that each directory in newlib containing
	a configure.in file also contains an aclocal.m4 file. This file is
	generated by issuing: aclocal -I${relative_path_to_toplevel_newlib_dir}
	-I${relative_path_to_toplevel_src_dir}
	The first relative directory is to access acinclude.m4. The second relative
	directory is to access libtool information in the top-level src directory.

	For example, to regenerate aclocal.m4 in newlib/libc/machine/arm:

	aclocal -I ../../.. -I ../../../..

	Note that if the top level acinclude.m4 is altered, every aclocal.m4 file
	in newlib should be regenerated.

	If the aclocal.m4 file is regenerated due to a change in acinclude.m4 or
	if a configure.in file is modified, the corresponding configure file in the
	directory must be regenerated using autoconf. No parameters are necessary.
	In the previous example, we would issue:

	autoconf

	from the newlib/libc/machine/arm directory.

	If you have regenerated a configure file or if you have modified a Makefile.am
	file, you will need to regenerate the appropriate Makefile.in file(s).
	For newlib, automake is a bit trickier. First of all, all Makefile.in
	files in newlib (and libgloss) are generated using the --cygnus option
	of automake.

	Makefile.in files are generated from the nearest directory up the chain
	which contains a configure.in file. In most cases, this is the same
	directory containing configure.in, but there are exceptions.
	For example, the newlib/libc directory has a number of
	subdirectories that do not contain their own configure.in files (e.g. stdio).
	For these directories, you must issue the automake command from newlib/libc
	which is the nearest parent directory that contains a configure.in.
	When you issue the automake command, you specify the subdirectory for
	the Makefile.in you are regenerating. For example:

	automake --cygnus stdio/Makefile stdlib/Makefile

	Note how multiple Makefile.in files can be created in the same step. You
	would not specify machine/Makefile or sys/Makefile in the previous example
	because both of these subdirectories contain their own configure.in files.
	One would change to each of these subdirectories and in turn issue:

	automake --cygnus Makefile

	Let's say you create a new machine directory XXXX off of newlib/libc/machine.
	After creating a new configure.in and Makefile.am file, you would issue:

	aclocal -I ../../..
	autoconf
	automake --cygnus Makefile

	from newlib/libc/machine/XXXX

	It is strongly advised that you use an adequate version of autotools.
	For this latest release, the following were used: autoconf 2.69, aclocal 1.13.4, and
	automake 1.13.4.

	Reporting Bugs
	==============

	The correct address for reporting bugs found in NEWLIB is
	"newlib@sourceware.org". Please email all bug reports to that
	address. Please include the NEWLIB version number (e.g., newlib-2.1.0),
	and how you configured it (e.g., "sun4 host and m68k-aout target").
	Since NEWLIB supports many different configurations, it is important
	that you be precise about this.

	Archives of the newlib mailing list are on-line, see
	http://sourceware.org/ml/newlib/