1 README for newlib-2.0.0 release 2 (mostly cribbed from the README in the gdb-4.13 release) 3 4This is `newlib', a simple ANSI C library, math library, and collection 5of board support packages. 6 7The newlib and libgloss subdirectories are a collection of software from 8several sources, each wi6h their own copyright and license. See the file 9COPYING.NEWLIB for details. The rest of the release tree is under either 10the GNU GPL or LGPL licenses. 11 12THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 13IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 14WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 15 16 17Unpacking and Installation -- quick overview 18========================== 19 20When you unpack the newlib-2.0.0.tar.gz file, you'll find a directory 21called `newlib-2.0.0', which contains: 22 23COPYING config/ install-sh* mpw-configure 24COPYING.LIB config-ml.in libgloss/ mpw-install 25COPYING.NEWLIB config.guess* mkinstalldirs* newlib/ 26CYGNUS config.sub* move-if-change* symlink-tree* 27ChangeLog configure* mpw-README texinfo/ 28Makefile.in configure.in mpw-build.in 29README etc/ mpw-config.in 30 31To build NEWLIB, you must follow the instructions in the section entitled 32"Compiling NEWLIB". 33 34This will configure and build all the libraries and crt0 (if one exists). 35If `configure' can't determine your host system type, specify one as its 36argument, e.g., sun4 or sun4sol2. NEWLIB is most often used in cross 37environments. 38 39NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS. 40 41 42More 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 49distribution. The documentation is written in Texinfo format, which is 50a documentation system that uses a single source file to produce both 51on-line information and a printed manual. You can use one of the Info 52formatting commands to create the on-line version of the documentation 53and TeX (or `texi2roff') to typeset the printed version. 54 55 If you want to format these Info files yourself, you need one of the 56Info 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, 59a program to print its DVI output files, and `texinfo.tex', the Texinfo 60definitions file. 61 62 TeX is a typesetting program; it does not print files directly, but 63produces output files called DVI files. To print a typeset document, 64you need a program to print DVI files. If your system has TeX 65installed, chances are it has such a program. The precise command to 66use depends on your system; `lpr -d' is common; another (for PostScript 67devices) is `dvips'. The DVI print command may require a file name 68without any extension or a `.dvi' extension. 69 70 TeX also requires a macro definitions file called `texinfo.tex'. 71This file tells TeX how to typeset a document written in Texinfo 72format. 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 78Compiling NEWLIB 79================ 80 81 To compile NEWLIB, you must build it in a directory separate from 82the source directory. If you want to run NEWLIB versions for several host 83or target machines, you need a different `newlib' compiled for each combination 84of host and target. `configure' is designed to make this easy by allowing 85you to generate each configuration in a separate subdirectory. 86If your `make' program handles the `VPATH' feature correctly (like GNU `make') 87running `make' in each of these directories builds the `newlib' libraries 88specified 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 92to specify a path to find `configure' itself from your working 93directory. If the path to `configure' would be the same as the 94argument to `--srcdir', you can leave out the `--srcdir' option; it 95will be assumed.) 96 97 For example, with version 2.0.0, you can build NEWLIB in a separate 98directory 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 107directory, 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 109the example, you'd find the Sun 4 library `libiberty.a' in the 110directory `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 114in a configured directory--whatever directory you were in when you 115called `configure' (or one of its subdirectories). 116 117 The `Makefile' that `configure' generates in each source directory 118also runs recursively. If you type `make' in a source directory such 119as `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 123directories, you can run `make' on them in parallel (for example, if 124they are NFS-mounted on each of the hosts); they will not interfere 125with each other. 126 127 128Specifying names for hosts and targets 129====================================== 130 131 The specifications used for hosts and targets in the `configure' 132script are based on a three-part naming scheme, but some short 133predefined aliases are also supported. The full naming scheme encodes 134three 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 143facility to list all supported host and target names or aliases. 144`configure' calls the Bourne shell script `config.sub' to map 145abbreviations to full names; you can read the script, if you wish, or 146you 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 161The Build, Host and Target Concepts in newlib 162============================================= 163 164The build, host and target concepts are defined for gcc as follows: 165 166build: the platform on which gcc is built. 167host: the platform on which gcc is run. 168target: the platform for which gcc generates code. 169 170Since newlib is a library, the target concept does not apply to it, and the 171build, host, and target options given to the top-level configure script must 172be changed for newlib's use. 173 174The options are shifted according to these correspondences: 175 176gcc's build platform has no equivalent in newlib. 177gcc's host platform is newlib's build platform. 178gcc's target platform is newlib's host platform. 179and 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 185most often useful for building NEWLIB. `configure' also has several other 186options not listed here. 187 188 configure [--help] 189 [--prefix=DIR] 190 [--srcdir=PATH] 191 [--target=TARGET] HOST 192 193You may introduce options with a single `-' rather than `--' if you 194prefer; 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 236To fit diverse usage models, NEWLIB supports a group of configuration 237options so that library features can be turned on/off according to 238target system's requirements. 239 240One 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 369Running the Testsuite 370===================== 371 372To run newlib's testsuite, you'll need a site.exp in your home 373directory which points dejagnu to the proper baseboards directory and 374the proper exp file for your target. 375 376Before running make check-target-newlib, set the DEJAGNU environment 377variable to point to ~/site.exp. 378 379Here is a sample site.exp: 380 381# Make sure we look in the right place for the board description files. 382if ![info exists boards_dir] { 383 set boards_dir {} 384} 385lappend boards_dir "your dejagnu/baseboards here" 386 387verbose "Global Config File: target_triplet is $target_triplet" 2 388 389global target_list 390case "$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 401mips-sim refers to an exp file in the baseboards directory. You'll 402need to add the other targets you're testing to the case statement. 403 404Now type make check-target-newlib in the top-level build directory to 405run the testsuite. 406 407Shared newlib 408============= 409 410newlib 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 412host. This allows newlib to be compiled as a shared library. 413 414To configure newlib, do the following from your build directory: 415 416$(source_dir)/src/configure --with-newlib --prefix=$(install_dir) 417 418configure will recognize that host == target == 419i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using 420libtool. By default, libtool will build shared and static versions of 421newlib. 422 423To compile a program against shared newlib, do the following (where 424target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu): 425 426gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc 427 428To run the program, make sure that $(target_install_dir)/lib is listed 429in the LD_LIBRARY_PATH environment variable. 430 431To create a static binary linked against newlib, do the following: 432 433gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm 434 435libtool can be instructed to produce only static libraries. To build 436newlib as a static library only, do the following from your build 437directory: 438 439$(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared 440 441Regenerating Configuration Files 442================================ 443 444At times you will need to make changes to configure.in and Makefile.am files. 445This will mean that configure and Makefile.in files will need to be 446regenerated. 447 448At the top level of newlib is the file: acinclude.m4. This file contains 449the definition of the NEWLIB_CONFIGURE macro which is used by all configure.in 450files in newlib. You will notice that each directory in newlib containing 451a configure.in file also contains an aclocal.m4 file. This file is 452generated by issuing: aclocal -I${relative_path_to_toplevel_newlib_dir} 453-I${relative_path_to_toplevel_src_dir} 454The first relative directory is to access acinclude.m4. The second relative 455directory is to access libtool information in the top-level src directory. 456 457For example, to regenerate aclocal.m4 in newlib/libc/machine/arm: 458 459 aclocal -I ../../.. -I ../../../.. 460 461Note that if the top level acinclude.m4 is altered, every aclocal.m4 file 462in newlib should be regenerated. 463 464If the aclocal.m4 file is regenerated due to a change in acinclude.m4 or 465if a configure.in file is modified, the corresponding configure file in the 466directory must be regenerated using autoconf. No parameters are necessary. 467In the previous example, we would issue: 468 469 autoconf 470 471from the newlib/libc/machine/arm directory. 472 473If you have regenerated a configure file or if you have modified a Makefile.am 474file, you will need to regenerate the appropriate Makefile.in file(s). 475For newlib, automake is a bit trickier. First of all, all Makefile.in 476files in newlib (and libgloss) are generated using the --cygnus option 477of automake. 478 479Makefile.in files are generated from the nearest directory up the chain 480which contains a configure.in file. In most cases, this is the same 481directory containing configure.in, but there are exceptions. 482For example, the newlib/libc directory has a number of 483subdirectories that do not contain their own configure.in files (e.g. stdio). 484For these directories, you must issue the automake command from newlib/libc 485which is the nearest parent directory that contains a configure.in. 486When you issue the automake command, you specify the subdirectory for 487the Makefile.in you are regenerating. For example: 488 489 automake --cygnus stdio/Makefile stdlib/Makefile 490 491Note how multiple Makefile.in files can be created in the same step. You 492would not specify machine/Makefile or sys/Makefile in the previous example 493because both of these subdirectories contain their own configure.in files. 494One would change to each of these subdirectories and in turn issue: 495 496 automake --cygnus Makefile 497 498Let's say you create a new machine directory XXXX off of newlib/libc/machine. 499After creating a new configure.in and Makefile.am file, you would issue: 500 501 aclocal -I ../../.. 502 autoconf 503 automake --cygnus Makefile 504 505from newlib/libc/machine/XXXX 506 507It is strongly advised that you use an adequate version of autotools. 508For this latest release, the following were used: autoconf 2.68, aclocal 1.11.6, and 509automake 1.11.6. 510 511Reporting Bugs 512============== 513 514The correct address for reporting bugs found in NEWLIB is 515"newlib@sourceware.org". Please email all bug reports to that 516address. Please include the NEWLIB version number (e.g., newlib-2.0.0), 517and how you configured it (e.g., "sun4 host and m68k-aout target"). 518Since NEWLIB supports many different configurations, it is important 519that you be precise about this. 520 521Archives of the newlib mailing list are on-line, see 522 http://sourceware.org/ml/newlib/ 523