| 1 |
1005 |
ivang |
README for newlib-1.10.0 release
|
| 2 |
|
|
(mostly cribbed from the README in the gdb-4.13 release)
|
| 3 |
|
|
|
| 4 |
|
|
This is `newlib', a simple ANSI C library, math library, and collection
|
| 5 |
|
|
of board support packages.
|
| 6 |
|
|
|
| 7 |
|
|
The newlib and libgloss subdirectories are a collection of software from
|
| 8 |
|
|
several sources, each with their own copyright. See the file COPYING.NEWLIB
|
| 9 |
|
|
for details. The rest of the release tree is under either the GNU GPL or
|
| 10 |
|
|
LPGL copyright.
|
| 11 |
|
|
|
| 12 |
|
|
THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
|
| 13 |
|
|
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
|
| 14 |
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
| 15 |
|
|
|
| 16 |
|
|
|
| 17 |
|
|
Unpacking and Installation -- quick overview
|
| 18 |
|
|
==========================
|
| 19 |
|
|
|
| 20 |
|
|
When you unpack the newlib-1.10.0.tar.gz file, you'll find a directory
|
| 21 |
|
|
called `newlib-1.10.0', which contains:
|
| 22 |
|
|
|
| 23 |
|
|
COPYING config/ install-sh* mpw-configure
|
| 24 |
|
|
COPYING.LIB config-ml.in libgloss/ mpw-install
|
| 25 |
|
|
COPYING.NEWLIB config.guess* mkinstalldirs* newlib/
|
| 26 |
|
|
CYGNUS config.sub* move-if-change* symlink-tree*
|
| 27 |
|
|
ChangeLog configure* mpw-README texinfo/
|
| 28 |
|
|
Makefile.in configure.in mpw-build.in
|
| 29 |
|
|
README etc/ mpw-config.in
|
| 30 |
|
|
|
| 31 |
|
|
To build NEWLIB, you must follow the instructions in the section entitled
|
| 32 |
|
|
"Compiling NEWLIB".
|
| 33 |
|
|
|
| 34 |
|
|
This will configure and build all the libraries and crt0 (if one exists).
|
| 35 |
|
|
If `configure' can't determine your host system type, specify one as its
|
| 36 |
|
|
argument, e.g., sun4 or sun4sol2. NEWLIB is most often used in cross
|
| 37 |
|
|
environments.
|
| 38 |
|
|
|
| 39 |
|
|
NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS.
|
| 40 |
|
|
|
| 41 |
|
|
|
| 42 |
|
|
More Documentation
|
| 43 |
|
|
==================
|
| 44 |
|
|
|
| 45 |
|
|
Newlib documentation is available on the net via:
|
| 46 |
|
|
http://www.cygnus.com/pubs/gnupro
|
| 47 |
|
|
|
| 48 |
|
|
All the documentation for NEWLIB comes as part of the machine-readable
|
| 49 |
|
|
distribution. The documentation is written in Texinfo format, which is
|
| 50 |
|
|
a documentation system that uses a single source file to produce both
|
| 51 |
|
|
on-line information and a printed manual. You can use one of the Info
|
| 52 |
|
|
formatting commands to create the on-line version of the documentation
|
| 53 |
|
|
and TeX (or `texi2roff') to typeset the printed version.
|
| 54 |
|
|
|
| 55 |
|
|
If you want to format these Info files yourself, you need one of the
|
| 56 |
|
|
Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
|
| 57 |
|
|
|
| 58 |
|
|
If you want to typeset and print copies of this manual, you need TeX,
|
| 59 |
|
|
a program to print its DVI output files, and `texinfo.tex', the Texinfo
|
| 60 |
|
|
definitions file.
|
| 61 |
|
|
|
| 62 |
|
|
TeX is a typesetting program; it does not print files directly, but
|
| 63 |
|
|
produces output files called DVI files. To print a typeset document,
|
| 64 |
|
|
you need a program to print DVI files. If your system has TeX
|
| 65 |
|
|
installed, chances are it has such a program. The precise command to
|
| 66 |
|
|
use depends on your system; `lpr -d' is common; another (for PostScript
|
| 67 |
|
|
devices) is `dvips'. The DVI print command may require a file name
|
| 68 |
|
|
without any extension or a `.dvi' extension.
|
| 69 |
|
|
|
| 70 |
|
|
TeX also requires a macro definitions file called `texinfo.tex'.
|
| 71 |
|
|
This file tells TeX how to typeset a document written in Texinfo
|
| 72 |
|
|
format. On its own, TeX cannot read, much less typeset a Texinfo file.
|
| 73 |
|
|
`texinfo.tex' is distributed with NEWLIB and is located in the
|
| 74 |
|
|
`newlib-VERSION-NUMBER/texinfo' directory.
|
| 75 |
|
|
|
| 76 |
|
|
|
| 77 |
|
|
|
| 78 |
|
|
Compiling NEWLIB
|
| 79 |
|
|
================
|
| 80 |
|
|
|
| 81 |
|
|
To compile NEWLIB, you must build it in a directory separate from
|
| 82 |
|
|
the source directory. If you want to run NEWLIB versions for several host
|
| 83 |
|
|
or target machines, you need a different `newlib' compiled for each combination
|
| 84 |
|
|
of host and target. `configure' is designed to make this easy by allowing
|
| 85 |
|
|
you to generate each configuration in a separate subdirectory.
|
| 86 |
|
|
If your `make' program handles the `VPATH' feature correctly (like GNU `make')
|
| 87 |
|
|
running `make' in each of these directories builds the `newlib' libraries
|
| 88 |
|
|
specified there.
|
| 89 |
|
|
|
| 90 |
|
|
To build `newlib' in a specific directory, run `configure' with the
|
| 91 |
|
|
`--srcdir' option to specify where to find the source. (You also need
|
| 92 |
|
|
to specify a path to find `configure' itself from your working
|
| 93 |
|
|
directory. If the path to `configure' would be the same as the
|
| 94 |
|
|
argument to `--srcdir', you can leave out the `--srcdir' option; it
|
| 95 |
|
|
will be assumed.)
|
| 96 |
|
|
|
| 97 |
|
|
For example, with version 1.10.0, you can build NEWLIB in a separate
|
| 98 |
|
|
directory for a Sun 4 cross m68k-aout environment like this:
|
| 99 |
|
|
|
| 100 |
|
|
cd newlib-1.10.0
|
| 101 |
|
|
mkdir ../newlib-m68k-aout
|
| 102 |
|
|
cd ../newlib-m68k-aout
|
| 103 |
|
|
../newlib-1.10.0/configure --host=sun4 --target=m68k-aout
|
| 104 |
|
|
make
|
| 105 |
|
|
|
| 106 |
|
|
When `configure' builds a configuration using a remote source
|
| 107 |
|
|
directory, it creates a tree for the binaries with the same structure
|
| 108 |
|
|
(and using the same names) as the tree under the source directory. In
|
| 109 |
|
|
the example, you'd find the Sun 4 library `libiberty.a' in the
|
| 110 |
|
|
directory `newlib-m68k-aout/libiberty', and NEWLIB itself in
|
| 111 |
|
|
`newlib-m68k-aout/newlib'.
|
| 112 |
|
|
|
| 113 |
|
|
When you run `make' to build a program or library, you must run it
|
| 114 |
|
|
in a configured directory--whatever directory you were in when you
|
| 115 |
|
|
called `configure' (or one of its subdirectories).
|
| 116 |
|
|
|
| 117 |
|
|
The `Makefile' that `configure' generates in each source directory
|
| 118 |
|
|
also runs recursively. If you type `make' in a source directory such
|
| 119 |
|
|
as `newlib-1.10.0' (or in a separate configured directory configured with
|
| 120 |
|
|
`--srcdir=PATH/newlib-1.10.0'), you will build all the required libraries.
|
| 121 |
|
|
|
| 122 |
|
|
When you have multiple hosts or targets configured in separate
|
| 123 |
|
|
directories, you can run `make' on them in parallel (for example, if
|
| 124 |
|
|
they are NFS-mounted on each of the hosts); they will not interfere
|
| 125 |
|
|
with each other.
|
| 126 |
|
|
|
| 127 |
|
|
|
| 128 |
|
|
Specifying names for hosts and targets
|
| 129 |
|
|
======================================
|
| 130 |
|
|
|
| 131 |
|
|
The specifications used for hosts and targets in the `configure'
|
| 132 |
|
|
script are based on a three-part naming scheme, but some short
|
| 133 |
|
|
predefined aliases are also supported. The full naming scheme encodes
|
| 134 |
|
|
three pieces of information in the following pattern:
|
| 135 |
|
|
|
| 136 |
|
|
ARCHITECTURE-VENDOR-OS
|
| 137 |
|
|
|
| 138 |
|
|
For example, you can use the alias `sun4' as a HOST argument or in a
|
| 139 |
|
|
`--target=TARGET' option. The equivalent full name is
|
| 140 |
|
|
`sparc-sun-sunos4'.
|
| 141 |
|
|
|
| 142 |
|
|
The `configure' script accompanying NEWLIB does not provide any query
|
| 143 |
|
|
facility to list all supported host and target names or aliases.
|
| 144 |
|
|
`configure' calls the Bourne shell script `config.sub' to map
|
| 145 |
|
|
abbreviations to full names; you can read the script, if you wish, or
|
| 146 |
|
|
you can use it to test your guesses on abbreviations--for example:
|
| 147 |
|
|
|
| 148 |
|
|
% sh config.sub sun4
|
| 149 |
|
|
sparc-sun-sunos4.1.1
|
| 150 |
|
|
% sh config.sub sun3
|
| 151 |
|
|
m68k-sun-sunos4.1.1
|
| 152 |
|
|
% sh config.sub decstation
|
| 153 |
|
|
mips-dec-ultrix4.2
|
| 154 |
|
|
% sh config.sub hp300bsd
|
| 155 |
|
|
m68k-hp-bsd
|
| 156 |
|
|
% sh config.sub i386v
|
| 157 |
|
|
i386-pc-sysv
|
| 158 |
|
|
% sh config.sub i786v
|
| 159 |
|
|
Invalid configuration `i786v': machine `i786v' not recognized
|
| 160 |
|
|
|
| 161 |
|
|
|
| 162 |
|
|
`configure' options
|
| 163 |
|
|
===================
|
| 164 |
|
|
|
| 165 |
|
|
Here is a summary of the `configure' options and arguments that are
|
| 166 |
|
|
most often useful for building NEWLIB. `configure' also has several other
|
| 167 |
|
|
options not listed here.
|
| 168 |
|
|
|
| 169 |
|
|
configure [--help]
|
| 170 |
|
|
[--prefix=DIR]
|
| 171 |
|
|
[--srcdir=PATH]
|
| 172 |
|
|
[--target=TARGET] HOST
|
| 173 |
|
|
|
| 174 |
|
|
You may introduce options with a single `-' rather than `--' if you
|
| 175 |
|
|
prefer; but you may abbreviate option names if you use `--'.
|
| 176 |
|
|
|
| 177 |
|
|
`--help'
|
| 178 |
|
|
Display a quick summary of how to invoke `configure'.
|
| 179 |
|
|
|
| 180 |
|
|
`--prefix=DIR'
|
| 181 |
|
|
Configure the source to install programs and files in directory
|
| 182 |
|
|
`DIR'.
|
| 183 |
|
|
|
| 184 |
|
|
`--exec-prefix=DIR'
|
| 185 |
|
|
Configure the source to install host-dependent files in directory
|
| 186 |
|
|
`DIR'.
|
| 187 |
|
|
|
| 188 |
|
|
`--srcdir=PATH'
|
| 189 |
|
|
*Warning: using this option requires GNU `make', or another `make'
|
| 190 |
|
|
that compatibly implements the `VPATH' feature.
|
| 191 |
|
|
Use this option to make configurations in directories separate
|
| 192 |
|
|
from the NEWLIB source directories. Among other things, you can use
|
| 193 |
|
|
this to build (or maintain) several configurations simultaneously,
|
| 194 |
|
|
in separate directories. `configure' writes configuration
|
| 195 |
|
|
specific files in the current directory, but arranges for them to
|
| 196 |
|
|
use the source in the directory PATH. `configure' will create
|
| 197 |
|
|
directories under the working directory in parallel to the source
|
| 198 |
|
|
directories below PATH.
|
| 199 |
|
|
|
| 200 |
|
|
`--norecursion'
|
| 201 |
|
|
Configure only the directory level where `configure' is executed;
|
| 202 |
|
|
do not propagate configuration to subdirectories.
|
| 203 |
|
|
|
| 204 |
|
|
`--target=TARGET'
|
| 205 |
|
|
Configure NEWLIB for running on the specified TARGET.
|
| 206 |
|
|
|
| 207 |
|
|
There is no convenient way to generate a list of all available
|
| 208 |
|
|
targets.
|
| 209 |
|
|
|
| 210 |
|
|
`HOST ...'
|
| 211 |
|
|
Configure NEWLIB to be built using a cross compiler running on
|
| 212 |
|
|
the specified HOST.
|
| 213 |
|
|
|
| 214 |
|
|
There is no convenient way to generate a list of all available
|
| 215 |
|
|
hosts.
|
| 216 |
|
|
|
| 217 |
|
|
Shared newlib
|
| 218 |
|
|
=============
|
| 219 |
|
|
|
| 220 |
|
|
newlib now uses libtool when it is being compiled natively (with
|
| 221 |
|
|
--target=i[3456]86-pc-linux-gnu) on an i[3456]86-pc-linux-gnu host. This
|
| 222 |
|
|
allows newlib to be compiled as a shared library.
|
| 223 |
|
|
|
| 224 |
|
|
To configure newlib, do the following from your build directory:
|
| 225 |
|
|
|
| 226 |
|
|
$(source_dir)/src/configure --with-newlib --prefix=$(install_dir)
|
| 227 |
|
|
|
| 228 |
|
|
configure will recognize that host == target ==
|
| 229 |
|
|
i[3456]86-pc-linux-gnu, so it will tell newlib to compile itself using
|
| 230 |
|
|
libtool. By default, libtool will build shared and static versions of
|
| 231 |
|
|
newlib.
|
| 232 |
|
|
|
| 233 |
|
|
To compile a program against shared newlib, do the following (where
|
| 234 |
|
|
target_install_dir = $(install_dir)/i[3456]86-pc-linux-gnu):
|
| 235 |
|
|
|
| 236 |
|
|
gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc
|
| 237 |
|
|
|
| 238 |
|
|
To run the program, make sure that $(target_install_dir)/lib is listed
|
| 239 |
|
|
in the LD_LIBRARY_PATH environment variable.
|
| 240 |
|
|
|
| 241 |
|
|
To create a static binary linked against newlib, do the following:
|
| 242 |
|
|
|
| 243 |
|
|
gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm
|
| 244 |
|
|
|
| 245 |
|
|
libtool can be instructed to produce only static libraries. To build
|
| 246 |
|
|
newlib as a static library only, do the following from your build
|
| 247 |
|
|
directory:
|
| 248 |
|
|
|
| 249 |
|
|
$(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared
|
| 250 |
|
|
|
| 251 |
|
|
Reporting Bugs
|
| 252 |
|
|
==============
|
| 253 |
|
|
|
| 254 |
|
|
The correct address for reporting bugs found in NEWLIB is
|
| 255 |
|
|
"newlib@sources.redhat.com". Please email all bug reports to that
|
| 256 |
|
|
address. Please include the NEWLIB version number (e.g., newlib-1.10.0),
|
| 257 |
|
|
and how you configured it (e.g., "sun4 host and m68k-aout target").
|
| 258 |
|
|
Since NEWLIB supports many different configurations, it is important
|
| 259 |
|
|
that you be precise about this.
|
| 260 |
|
|
|
| 261 |
|
|
Archives of the newlib mailing list are on-line, see
|
| 262 |
|
|
http://sources.redhat.com/ml/newlib/
|
