README for newlib-2.0.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.0.0.tar.gz file, you'll find a directory
|
called `newlib-2.0.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.0.0, you can build NEWLIB in a separate
|
directory for a Sun 4 cross m68k-aout environment like this:
|
|
cd newlib-2.0.0
|
mkdir ../newlib-m68k-aout
|
cd ../newlib-m68k-aout
|
../newlib-2.0.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.0.0' (or in a separate configured directory configured with
|
`--srcdir=PATH/newlib-2.0.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-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.68, aclocal 1.11.6, and
|
automake 1.11.6.
|
|
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.0.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/
|
