540 lines
20 KiB
Plaintext
540 lines
20 KiB
Plaintext
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/
|