OpenCores
URL https://opencores.org/ocsvn/or1k_old/or1k_old/trunk

Subversion Repositories or1k_old

[/] [or1k_old/] [trunk/] [newlib-1.10.0/] [newlib/] [README] - Blame information for rev 1782

Details | Compare with Previous | View Log

Line No. Rev Author Line
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/

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.