fixed more binutils issues (newer gcc/libc)
[zpugcc/jano.git] / toolchain / gcc / newlib / README
blob61fda77be9f6537c375f61256d244b86044d61b3
1                         README for newlib-1.12.0 release
2            (mostly cribbed from the README in the gdb-4.13 release)
4 This is `newlib', a simple ANSI C library, math library, and collection
5 of board support packages.
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.
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.
17 Unpacking and Installation -- quick overview
18 ==========================
20 When you unpack the newlib-1.12.0.tar.gz file, you'll find a directory
21 called `newlib-1.12.0', which contains:
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
31 To build NEWLIB, you must follow the instructions in the section entitled
32 "Compiling NEWLIB".
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.
39 NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS.
42 More Documentation
43 ==================
45    Newlib documentation is available on the net via:
46    http://sources.redhat.com/newlib/docs.html
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.
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'.
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.
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.
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.
78 Compiling NEWLIB
79 ================
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.
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.)
97    For example, with version 1.12.0, you can build NEWLIB in a separate
98 directory for a Sun 4 cross m68k-aout environment like this:
100      cd newlib-1.12.0
101      mkdir ../newlib-m68k-aout
102      cd ../newlib-m68k-aout
103      ../newlib-1.12.0/configure --host=sun4 --target=m68k-aout
104      make
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'.
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).
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.12.0' (or in a separate configured directory configured with
120 `--srcdir=PATH/newlib-1.12.0'), you will build all the required libraries.
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.
128 Specifying names for hosts and targets
129 ======================================
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:
136      ARCHITECTURE-VENDOR-OS
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'.
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:
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
161 The Build, Host and Target Concepts in newlib
162 =============================================
164 The build, host and target concepts are defined for gcc as follows:
166 build: the platform on which gcc is built.
167 host: the platform on which gcc is run.
168 target: the platform for which gcc generates code.
170 Since newlib is a library, the target concept does not apply to it, and the
171 build, host, and target options given to the top-level configure script must
172 be changed for newlib's use.
174 The options are shifted according to these correspondences:
176 gcc's build platform has no equivalent in newlib.
177 gcc's host platform is newlib's build platform.
178 gcc's target platform is newlib's host platform.
179 and as mentioned before, newlib has no concept of target.
181 `configure' options
182 ===================
184    Here is a summary of the `configure' options and arguments that are
185 most often useful for building NEWLIB.  `configure' also has several other
186 options not listed here.
188      configure [--help]
189                [--prefix=DIR]
190                [--srcdir=PATH]
191                [--target=TARGET] HOST
193 You may introduce options with a single `-' rather than `--' if you
194 prefer; but you may abbreviate option names if you use `--'.
196 `--help'
197      Display a quick summary of how to invoke `configure'.
199 `--prefix=DIR'
200      Configure the source to install programs and files in directory
201      `DIR'.
203 `--exec-prefix=DIR'
204      Configure the source to install host-dependent files in directory
205      `DIR'.
207 `--srcdir=PATH'
208      *Warning: using this option requires GNU `make', or another `make'
209      that compatibly implements the `VPATH' feature.
210      Use this option to make configurations in directories separate
211      from the NEWLIB source directories.  Among other things, you can use
212      this to build (or maintain) several configurations simultaneously,
213      in separate directories.  `configure' writes configuration
214      specific files in the current directory, but arranges for them to
215      use the source in the directory PATH.  `configure' will create
216      directories under the working directory in parallel to the source
217      directories below PATH.
219 `--norecursion'
220      Configure only the directory level where `configure' is executed;
221      do not propagate configuration to subdirectories.
223 `--target=TARGET'
224      Configure NEWLIB for running on the specified TARGET.
226      There is no convenient way to generate a list of all available
227      targets.
229 `HOST ...'
230      Configure NEWLIB to be built using a cross compiler running on
231      the specified HOST.
233      There is no convenient way to generate a list of all available
234      hosts.
236 Running the Testsuite
237 =====================
239 To run newlib's testsuite, you'll need a site.exp in your home
240 directory which points dejagnu to the proper baseboards directory and
241 the proper exp file for your target.
243 Before running make check-target-newlib, set the DEJAGNU environment
244 variable to point to ~/site.exp.
246 Here is a sample site.exp:
248 # Make sure we look in the right place for the board description files.
249 if ![info exists boards_dir] {
250     set boards_dir {}
252 lappend boards_dir "your dejagnu/baseboards here"
254 verbose "Global Config File: target_triplet is $target_triplet" 2
256 global target_list
257 case "$target_triplet" in {
259     { "mips-*elf*" } {
260         set target_list "mips-sim"
261     }
263     default {
264         set target_list { "unix" }
265     }
268 mips-sim refers to an exp file in the baseboards directory.  You'll
269 need to add the other targets you're testing to the case statement.
271 Now type make check-target-newlib in the top-level build directory to
272 run the testsuite.
274 Shared newlib
275 =============
277 newlib uses libtool when it is being compiled natively (with
278 --target=i[34567]86-pc-linux-gnu) on an i[34567]86-pc-linux-gnu
279 host. This allows newlib to be compiled as a shared library.
281 To configure newlib, do the following from your build directory:
283 $(source_dir)/src/configure --with-newlib --prefix=$(install_dir)
285 configure will recognize that host == target ==
286 i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using
287 libtool. By default, libtool will build shared and static versions of
288 newlib.
290 To compile a program against shared newlib, do the following (where
291 target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu):
293 gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc
295 To run the program, make sure that $(target_install_dir)/lib is listed
296 in the LD_LIBRARY_PATH environment variable.
298 To create a static binary linked against newlib, do the following:
300 gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm
302 libtool can be instructed to produce only static libraries. To build
303 newlib as a static library only, do the following from your build
304 directory:
306 $(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared
308 Reporting Bugs
309 ==============
311 The correct address for reporting bugs found in NEWLIB is
312 "newlib@sources.redhat.com".  Please email all bug reports to that
313 address.  Please include the NEWLIB version number (e.g., newlib-1.12.0),
314 and how you configured it (e.g., "sun4 host and m68k-aout target").
315 Since NEWLIB supports many different configurations, it is important
316 that you be precise about this.
318 Archives of the newlib mailing list are on-line, see
319         http://sources.redhat.com/ml/newlib/