1 README for newlib-2.0.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 wi6h their own copyright and license. See the file
9 COPYING.NEWLIB for details. The rest of the release tree is under either
10 the GNU GPL or LGPL licenses.
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-2.0.0.tar.gz file, you'll find a directory
21 called `newlib-2.0.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://sourceware.org/newlib/docs.html
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 2.0.0, you can build NEWLIB in a separate
98 directory for a Sun 4 cross m68k-aout environment like this:
99
100 cd newlib-2.0.0
101 mkdir ../newlib-m68k-aout
102 cd ../newlib-m68k-aout
103 ../newlib-2.0.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-2.0.0' (or in a separate configured directory configured with
120 `--srcdir=PATH/newlib-2.0.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 The Build, Host and Target Concepts in newlib
162 =============================================
163
164 The build, host and target concepts are defined for gcc as follows:
165
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.
169
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.
173
174 The options are shifted according to these correspondences:
175
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.
180
181 `configure' options
182 ===================
183
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.
187
188 configure [--help]
189 [--prefix=DIR]
190 [--srcdir=PATH]
191 [--target=TARGET] HOST
192
193 You may introduce options with a single `-' rather than `--' if you
194 prefer; but you may abbreviate option names if you use `--'.
195
196 `--help'
197 Display a quick summary of how to invoke `configure'.
198
199 `--prefix=DIR'
200 Configure the source to install programs and files in directory
201 `DIR'.
202
203 `--exec-prefix=DIR'
204 Configure the source to install host-dependent files in directory
205 `DIR'.
206
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.
218
219 `--norecursion'
220 Configure only the directory level where `configure' is executed;
221 do not propagate configuration to subdirectories.
222
223 `--target=TARGET'
224 Configure NEWLIB for running on the specified TARGET.
225
226 There is no convenient way to generate a list of all available
227 targets.
228
229 `HOST ...'
230 Configure NEWLIB to be built using a cross compiler running on
231 the specified HOST.
232
233 There is no convenient way to generate a list of all available
234 hosts.
235
236 To fit diverse usage models, NEWLIB supports a group of configuration
237 options so that library features can be turned on/off according to
238 target system's requirements.
239
240 One feature can be enabled by specifying `--enable-FEATURE=yes' or
241 `--enable-FEATURE'. Or it can be disable by `--enable-FEATURE=no' or
242 `--disable-FEATURE'.
243
244 `--enable-newlib-io-pos-args'
245 Enable printf-family positional arg support.
246 Disabled by default, but some hosts enable it in configure.host.
247
248 `--enable-newlib-io-c99-formats'
249 Enable C99 support in IO functions like printf/scanf.
250 Disabled by default, but some hosts enable it in configure.host.
251
252 `--enable-newlib-register-fini'
253 Enable finalization function registration using atexit.
254 Disabled by default.
255
256 `--enable-newlib-io-long-long'
257 Enable long long type support in IO functions like printf/scanf.
258 Disabled by default, but many hosts enable it in configure.host.
259
260 `--enable-newlib-io-long-double'
261 Enable long double type support in IO functions printf/scanf.
262 Disabled by default, but some hosts enable it in configure.host.
263
264 `--enable-newlib-mb'
265 Enable multibyte support.
266 Disabled by default.
267
268 `--enable-newlib-iconv-encodings'
269 Enable specific comma-separated list of bidirectional iconv
270 encodings to be built-in.
271 Disabled by default.
272
273 `--enable-newlib-iconv-from-encodings'
274 Enable specific comma-separated list of \"from\" iconv encodings
275 to be built-in.
276 Disabled by default.
277
278 `--enable-newlib-iconv-to-encodings'
279 Enable specific comma-separated list of \"to\" iconv encodings
280 to be built-in.
281 Disabled by default.
282
283 `--enable-newlib-iconv-external-ccs'
284 Enable capabilities to load external CCS files for iconv.
285 Disabled by default.
286
287 `--disable-newlib-atexit-dynamic-alloc'
288 Disable dynamic allocation of atexit entries.
289 Most hosts and targets have it enabled in configure.host.
290
291 `--enable-newlib-reent-small'
292 Enable small reentrant struct support.
293 Disabled by default.
294
295 `--disable-newlib-fvwrite-in-streamio'
296 NEWLIB implements the vector buffer mechanism to support stream IO
297 buffering required by C standard. This feature is possibly
298 unnecessary for embedded systems which won't change file buffering
299 with functions like `setbuf' or `setvbuf'. The buffering mechanism
300 still acts as default for STDIN/STDOUT/STDERR even if this option
301 is specified.
302 Enabled by default.
303
304 `--disable-newlib-fseek-optimization'
305 Disable fseek optimization. It can decrease code size of application
306 calling `fseek`.
307 Enabled by default.
308
309 `--disable-newlib-wide-orient'
310 C99 states that each stream has an orientation, wide or byte. This
311 feature is possibly unnecessary for embedded systems which only do
312 byte input/output operations on stream. It can decrease code size
313 by disable the feature.
314 Enabled by default.
315
316 `--enable-newlib-nano-malloc'
317 NEWLIB has two implementations of malloc family's functions, one in
318 `mallocr.c' and the other one in `nano-mallocr.c'. This options
319 enables the nano-malloc implementation, which is for small systems
320 with very limited memory. Note that this implementation does not
321 support `--enable-malloc-debugging' any more.
322 Disabled by default.
323
324 `--disable-newlib-unbuf-stream-opt'
325 NEWLIB does optimization when `fprintf to write only unbuffered unix
326 file'. It creates a temorary buffer to do the optimization that
327 increases stack consumption by about `BUFSIZ' bytes. This option
328 disables the optimization and saves size of text and stack.
329 Enabled by default.
330
331 `--enable-multilib'
332 Build many library versions.
333 Enabled by default.
334
335 `--enable-target-optspace'
336 Optimize for space.
337 Disabled by default.
338
339 `--enable-malloc-debugging'
340 Indicate malloc debugging requested.
341 Disabled by default.
342
343 `--enable-newlib-multithread'
344 Enable support for multiple threads.
345 Enabled by default.
346
347 `--enable-newlib-iconv'
348 Enable iconv library support.
349 Disabled by default.
350
351 `--enable-newlib-elix-level'
352 Supply desired elix library level (1-4). Please refer to HOWTO for
353 more information about this option.
354 Set to level 0 by default.
355
356 `--disable-newlib-io-float'
357 Disable printf/scanf family float support.
358 Enabled by default.
359
360 `--disable-newlib-supplied-syscalls'
361 Disable newlib from supplying syscalls.
362 Enabled by default.
363
364 `--enable-lite-exit'
365 Enable lite exit, a size-reduced implementation of exit that doesn't
366 invoke clean-up functions such as _fini or global destructors.
367 Disabled by default.
368
369 Running the Testsuite
370 =====================
371
372 To run newlib's testsuite, you'll need a site.exp in your home
373 directory which points dejagnu to the proper baseboards directory and
374 the proper exp file for your target.
375
376 Before running make check-target-newlib, set the DEJAGNU environment
377 variable to point to ~/site.exp.
378
379 Here is a sample site.exp:
380
381 # Make sure we look in the right place for the board description files.
382 if ![info exists boards_dir] {
383 set boards_dir {}
384 }
385 lappend boards_dir "your dejagnu/baseboards here"
386
387 verbose "Global Config File: target_triplet is $target_triplet" 2
388
389 global target_list
390 case "$target_triplet" in {
391
392 { "mips-*elf*" } {
393 set target_list "mips-sim"
394 }
395
396 default {
397 set target_list { "unix" }
398 }
399 }
400
401 mips-sim refers to an exp file in the baseboards directory. You'll
402 need to add the other targets you're testing to the case statement.
403
404 Now type make check-target-newlib in the top-level build directory to
405 run the testsuite.
406
407 Shared newlib
408 =============
409
410 newlib uses libtool when it is being compiled natively (with
411 --target=i[34567]86-pc-linux-gnu) on an i[34567]86-pc-linux-gnu
412 host. This allows newlib to be compiled as a shared library.
413
414 To configure newlib, do the following from your build directory:
415
416 $(source_dir)/src/configure --with-newlib --prefix=$(install_dir)
417
418 configure will recognize that host == target ==
419 i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using
420 libtool. By default, libtool will build shared and static versions of
421 newlib.
422
423 To compile a program against shared newlib, do the following (where
424 target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu):
425
426 gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc
427
428 To run the program, make sure that $(target_install_dir)/lib is listed
429 in the LD_LIBRARY_PATH environment variable.
430
431 To create a static binary linked against newlib, do the following:
432
433 gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm
434
435 libtool can be instructed to produce only static libraries. To build
436 newlib as a static library only, do the following from your build
437 directory:
438
439 $(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared
440
441 Regenerating Configuration Files
442 ================================
443
444 At times you will need to make changes to configure.in and Makefile.am files.
445 This will mean that configure and Makefile.in files will need to be
446 regenerated.
447
448 At the top level of newlib is the file: acinclude.m4. This file contains
449 the definition of the NEWLIB_CONFIGURE macro which is used by all configure.in
450 files in newlib. You will notice that each directory in newlib containing
451 a configure.in file also contains an aclocal.m4 file. This file is
452 generated by issuing: aclocal -I${relative_path_to_toplevel_newlib_dir}
453 -I${relative_path_to_toplevel_src_dir}
454 The first relative directory is to access acinclude.m4. The second relative
455 directory is to access libtool information in the top-level src directory.
456
457 For example, to regenerate aclocal.m4 in newlib/libc/machine/arm:
458
459 aclocal -I ../../.. -I ../../../..
460
461 Note that if the top level acinclude.m4 is altered, every aclocal.m4 file
462 in newlib should be regenerated.
463
464 If the aclocal.m4 file is regenerated due to a change in acinclude.m4 or
465 if a configure.in file is modified, the corresponding configure file in the
466 directory must be regenerated using autoconf. No parameters are necessary.
467 In the previous example, we would issue:
468
469 autoconf
470
471 from the newlib/libc/machine/arm directory.
472
473 If you have regenerated a configure file or if you have modified a Makefile.am
474 file, you will need to regenerate the appropriate Makefile.in file(s).
475 For newlib, automake is a bit trickier. First of all, all Makefile.in
476 files in newlib (and libgloss) are generated using the --cygnus option
477 of automake.
478
479 Makefile.in files are generated from the nearest directory up the chain
480 which contains a configure.in file. In most cases, this is the same
481 directory containing configure.in, but there are exceptions.
482 For example, the newlib/libc directory has a number of
483 subdirectories that do not contain their own configure.in files (e.g. stdio).
484 For these directories, you must issue the automake command from newlib/libc
485 which is the nearest parent directory that contains a configure.in.
486 When you issue the automake command, you specify the subdirectory for
487 the Makefile.in you are regenerating. For example:
488
489 automake --cygnus stdio/Makefile stdlib/Makefile
490
491 Note how multiple Makefile.in files can be created in the same step. You
492 would not specify machine/Makefile or sys/Makefile in the previous example
493 because both of these subdirectories contain their own configure.in files.
494 One would change to each of these subdirectories and in turn issue:
495
496 automake --cygnus Makefile
497
498 Let's say you create a new machine directory XXXX off of newlib/libc/machine.
499 After creating a new configure.in and Makefile.am file, you would issue:
500
501 aclocal -I ../../..
502 autoconf
503 automake --cygnus Makefile
504
505 from newlib/libc/machine/XXXX
506
507 It is strongly advised that you use an adequate version of autotools.
508 For this latest release, the following were used: autoconf 2.68, aclocal 1.11.6, and
509 automake 1.11.6.
510
511 Reporting Bugs
512 ==============
513
514 The correct address for reporting bugs found in NEWLIB is
515 "newlib (a] sourceware.org". Please email all bug reports to that
516 address. Please include the NEWLIB version number (e.g., newlib-2.0.0),
517 and how you configured it (e.g., "sun4 host and m68k-aout target").
518 Since NEWLIB supports many different configurations, it is important
519 that you be precise about this.
520
521 Archives of the newlib mailing list are on-line, see
522 http://sourceware.org/ml/newlib/
523