path: root/newlib/README

                        README for newlib-4.2.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.

Prior to the 3.0.0 release, newlib supported both ANSI and K&R-style
compilers.  As of 3.0.0, K&R is no longer supported.

The newlib and libgloss subdirectories are a collection of software from
several sources, each with 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-4.2.0.tar.gz file, you'll find a directory
called `newlib-4.2.0', which contains many files.  Interesting ones:
  COPYING*  - License files for the sources
  README    - A common overview of all GNU development projects
  configure - The build script for configuring the source tree
  Makefile* - Inputs used by configure to generate the Makefile
  libgloss/ - The libgloss project
  newlib/   - The newlib project

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:
   https://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 4.2.0, you can build NEWLIB in a separate
directory for a Sun 4 cross m68k-aout environment like this:

     cd newlib-4.2.0
     mkdir ../newlib-m68k-aout
     cd ../newlib-m68k-aout
     ../newlib-4.2.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-4.2.0' (or in a separate configured directory configured with
`--srcdir=PATH/newlib-4.2.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.

   By default, the execution of build rules in `make' is less verbose.
To disable, run `make V=1'; or use the `--disable-silent-rules’ option
of `./configure'.

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 build system shifts the options 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.

In summary: the --target=TARGET switch to the top-level configure
script configures newlib's host platform.

`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-reent-small'
     Enable small reentrant struct support.
     Disabled by default.

`--enable-newlib-reent-binary-compat'
     Enable backward binary compatibility for struct _reent.  If enabled, then
     unused members in struct _reent are preserved to maintain the structure
     layout.
     Disabled by default.

`--enable-newlib-reent-thread-local'
     Enable thread-local storage objects as a replacement for struct _reent
     members.  If enabled, then struct _reent is not defined and dedicated
     thread-local storage objects are provided for each member of the default
     struct _reent.  For statically linked executables only the objects
     required by the application are linked in.
     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-newlib-long-time_t'
     Define time_t to long.  On platforms with a 32-bit long type, this gives
     raise to the year 2038 problem.  The default type for time_t is a signed
     64-bit integer on most systems.
     Disabled by default.

`--enable-newlib-use-gdtoa'
     Use gdtoa rather than legacy ldtoa.  gdtoa privides more accurate
     output and faster conversion than legacy ldtoa, while it requires
     more heap memory.  gdtoa sometimes requires 16KB heap memory, so
     if the platform does not have enough heap memory, consider disabling
     this option. Legacy ldtoa also use heap, however, only 1KB memory
     is malloc'ed.  In addition, if malloc fails, it still works, with
     less conversion accuracy.
     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.

`--enable-newlib-nano-formatted-io'
     This builds NEWLIB with a special implementation of formatted I/O
     functions, designed to lower the size of application on small systems
     with size constraint issues.  This option does not affect wide-char
     formatted I/O functions.  Some notes about the feature:
      1) The non-wide-char formatted I/O functions only support the C89
	 standard.  The only exception is the configuration option provides
	 limited support for long double.  Internally, the nano formatted I/O
	 functions use double so accuracy is only guaranteed to double
	 precision.
      2) Floating-point support is split out of the formatted I/O code into
	 weak functions which are not linked by default.  Programs that need
	 floating-point I/O support must explicitly request linking of one or
	 both of the floating-point functions: _printf_float or _scanf_float.
	 This can be done at link time using the -u option which can be passed
	 to either gcc or ld.  The -u option forces the link to resolve those
	 function references.  Floating-point format specifiers are recognized
	 by default, but if the floating-point functions are not explicitly
	 linked in, this may result in undefined behavior for programs that
	 need floating-point I/O support.
      3) Integer-only versions of the formatted I/O functions (the iprintf/
	 iscanf family) simply alias their regular counter-parts.
	 The affected functions are:

	  diprintf vdiprintf

	  siprintf fiprintf iprintf sniprintf asiprintf asniprintf

	  siscanf fiscanf iscanf

	  viprintf vfiprintf vsiprintf vsniprintf vasiprintf vasniprintf

	  viscanf vfiscanf vsiscanf

	  _diprintf_r _vdiprintf_r

	  _siprintf_r _fiprintf_r _iprintf_r _sniprintf_r _asiprintf_r
	  _asniprintf_r

	  _siscanf_r _fiscanf_r _iscanf_r

	  _viprintf_r _vfiprintf_r _vsiprintf_r _asniprintf_r _vasiprintf_r
	  _vasniprintf_r

	  _viscanf_r _vfiscanf_r _vsiscanf_r

      4) As mentioned, the option does not affect wide-char formatted I/O.
	 The following configuration options are ignored for non-wide-char
	 formatted I/O functions, and can be thought of as disabled.

	  enable-newlib-io-pos-args
	  enable-newlib-io-c99-formats
	  enable-newlib-io-long-long
	  enable-newlib-io-long-double
	  enable-newlib-mb

	 Additionally, "enable/disable-newlib-io-float" is supported in
	 this specific implementation, one can use "disable-newlib-io-float"
	 to further reduce code size.  In this case, the floating-point
	 specifiers will not be recognized or handled, and the -u option
	 will not work either.

      5) As a rule, no features from outside of C89 standard will be
	 considered in this implementation.

     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.

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

At times you will need to make changes to configure.ac, Makefile.am and
Makefile.inc files.  This will mean that configure and Makefile.in files will
need to be regenerated.  The easiest way to do so is by using the autoreconf
tool in the newlib directory.

  autoreconf

This will run a number of autotool programs for you.  To see the individual
steps, add the -v option.

  autoreconf -v

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

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-4.2.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
	https://sourceware.org/ml/newlib/