1 README for newlib-4.2.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 7Prior to the 3.0.0 release, newlib supported both ANSI and K&R-style 8compilers. As of 3.0.0, K&R is no longer supported. 9 10The newlib and libgloss subdirectories are a collection of software from 11several sources, each with their own copyright and license. See the file 12COPYING.NEWLIB for details. The rest of the release tree is under either 13the GNU GPL or LGPL licenses. 14 15THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 16IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 17WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 18 19 20Unpacking and Installation -- quick overview 21========================== 22 23When you unpack the newlib-4.2.0.tar.gz file, you'll find a directory 24called `newlib-4.2.0', which contains many files. Interesting ones: 25 COPYING* - License files for the sources 26 README - A common overview of all GNU development projects 27 configure - The build script for configuring the source tree 28 Makefile* - Inputs used by configure to generate the Makefile 29 libgloss/ - The libgloss project 30 newlib/ - The newlib project 31 32To build NEWLIB, you must follow the instructions in the section entitled 33"Compiling NEWLIB". 34 35This will configure and build all the libraries and crt0 (if one exists). 36If `configure' can't determine your host system type, specify one as its 37argument, e.g., sun4 or sun4sol2. NEWLIB is most often used in cross 38environments. 39 40NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS. 41 42 43More Documentation 44================== 45 46 Newlib documentation is available on the net via: 47 https://sourceware.org/newlib/docs.html 48 49 All the documentation for NEWLIB comes as part of the machine-readable 50distribution. The documentation is written in Texinfo format, which is 51a documentation system that uses a single source file to produce both 52on-line information and a printed manual. You can use one of the Info 53formatting commands to create the on-line version of the documentation 54and TeX (or `texi2roff') to typeset the printed version. 55 56 If you want to format these Info files yourself, you need one of the 57Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. 58 59 If you want to typeset and print copies of this manual, you need TeX, 60a program to print its DVI output files, and `texinfo.tex', the Texinfo 61definitions file. 62 63 TeX is a typesetting program; it does not print files directly, but 64produces output files called DVI files. To print a typeset document, 65you need a program to print DVI files. If your system has TeX 66installed, chances are it has such a program. The precise command to 67use depends on your system; `lpr -d' is common; another (for PostScript 68devices) is `dvips'. The DVI print command may require a file name 69without any extension or a `.dvi' extension. 70 71 TeX also requires a macro definitions file called `texinfo.tex'. 72This file tells TeX how to typeset a document written in Texinfo 73format. On its own, TeX cannot read, much less typeset a Texinfo file. 74`texinfo.tex' is distributed with NEWLIB and is located in the 75`newlib-VERSION-NUMBER/texinfo' directory. 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 4.2.0, you can build NEWLIB in a separate 98directory for a Sun 4 cross m68k-aout environment like this: 99 100 cd newlib-4.2.0 101 mkdir ../newlib-m68k-aout 102 cd ../newlib-m68k-aout 103 ../newlib-4.2.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-4.2.0' (or in a separate configured directory configured with 120`--srcdir=PATH/newlib-4.2.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 By default, the execution of build rules in `make' is less verbose. 128To disable, run `make V=1'; or use the `--disable-silent-rules’ option 129of `./configure'. 130 131Specifying names for hosts and targets 132====================================== 133 134 The specifications used for hosts and targets in the `configure' 135script are based on a three-part naming scheme, but some short 136predefined aliases are also supported. The full naming scheme encodes 137three pieces of information in the following pattern: 138 139 ARCHITECTURE-VENDOR-OS 140 141 For example, you can use the alias `sun4' as a HOST argument or in a 142`--target=TARGET' option. The equivalent full name is 143`sparc-sun-sunos4'. 144 145 The `configure' script accompanying NEWLIB does not provide any query 146facility to list all supported host and target names or aliases. 147`configure' calls the Bourne shell script `config.sub' to map 148abbreviations to full names; you can read the script, if you wish, or 149you can use it to test your guesses on abbreviations--for example: 150 151 % sh config.sub sun4 152 sparc-sun-sunos4.1.1 153 % sh config.sub sun3 154 m68k-sun-sunos4.1.1 155 % sh config.sub decstation 156 mips-dec-ultrix4.2 157 % sh config.sub hp300bsd 158 m68k-hp-bsd 159 % sh config.sub i386v 160 i386-pc-sysv 161 % sh config.sub i786v 162 Invalid configuration `i786v': machine `i786v' not recognized 163 164The Build, Host and Target Concepts in newlib 165============================================= 166 167The build, host and target concepts are defined for gcc as follows: 168 169build: the platform on which gcc is built. 170host: the platform on which gcc is run. 171target: the platform for which gcc generates code. 172 173Since newlib is a library, the target concept does not apply to it, and the 174build, host, and target options given to the top-level configure script must 175be changed for newlib's use. 176 177The build system shifts the options according to these correspondences: 178 179gcc's build platform has no equivalent in newlib. 180gcc's host platform is newlib's build platform. 181gcc's target platform is newlib's host platform. 182and as mentioned before, newlib has no concept of target. 183 184In summary: the --target=TARGET switch to the top-level configure 185script configures newlib's host platform. 186 187`configure' options 188=================== 189 190 Here is a summary of the `configure' options and arguments that are 191most often useful for building NEWLIB. `configure' also has several other 192options not listed here. 193 194 configure [--help] 195 [--prefix=DIR] 196 [--srcdir=PATH] 197 [--target=TARGET] HOST 198 199You may introduce options with a single `-' rather than `--' if you 200prefer; but you may abbreviate option names if you use `--'. 201 202`--help' 203 Display a quick summary of how to invoke `configure'. 204 205`--prefix=DIR' 206 Configure the source to install programs and files in directory 207 `DIR'. 208 209`--exec-prefix=DIR' 210 Configure the source to install host-dependent files in directory 211 `DIR'. 212 213`--srcdir=PATH' 214 *Warning: using this option requires GNU `make', or another `make' 215 that compatibly implements the `VPATH' feature. 216 Use this option to make configurations in directories separate 217 from the NEWLIB source directories. Among other things, you can use 218 this to build (or maintain) several configurations simultaneously, 219 in separate directories. `configure' writes configuration 220 specific files in the current directory, but arranges for them to 221 use the source in the directory PATH. `configure' will create 222 directories under the working directory in parallel to the source 223 directories below PATH. 224 225`--norecursion' 226 Configure only the directory level where `configure' is executed; 227 do not propagate configuration to subdirectories. 228 229`--target=TARGET' 230 Configure NEWLIB for running on the specified TARGET. 231 232 There is no convenient way to generate a list of all available 233 targets. 234 235`HOST ...' 236 Configure NEWLIB to be built using a cross compiler running on 237 the specified HOST. 238 239 There is no convenient way to generate a list of all available 240 hosts. 241 242To fit diverse usage models, NEWLIB supports a group of configuration 243options so that library features can be turned on/off according to 244target system's requirements. 245 246One feature can be enabled by specifying `--enable-FEATURE=yes' or 247`--enable-FEATURE'. Or it can be disable by `--enable-FEATURE=no' or 248`--disable-FEATURE'. 249 250`--enable-newlib-io-pos-args' 251 Enable printf-family positional arg support. 252 Disabled by default, but some hosts enable it in configure.host. 253 254`--enable-newlib-io-c99-formats' 255 Enable C99 support in IO functions like printf/scanf. 256 Disabled by default, but some hosts enable it in configure.host. 257 258`--enable-newlib-register-fini' 259 Enable finalization function registration using atexit. 260 Disabled by default. 261 262`--enable-newlib-io-long-long' 263 Enable long long type support in IO functions like printf/scanf. 264 Disabled by default, but many hosts enable it in configure.host. 265 266`--enable-newlib-io-long-double' 267 Enable long double type support in IO functions printf/scanf. 268 Disabled by default, but some hosts enable it in configure.host. 269 270`--enable-newlib-mb' 271 Enable multibyte support. 272 Disabled by default. 273 274`--enable-newlib-iconv-encodings' 275 Enable specific comma-separated list of bidirectional iconv 276 encodings to be built-in. 277 Disabled by default. 278 279`--enable-newlib-iconv-from-encodings' 280 Enable specific comma-separated list of \"from\" iconv encodings 281 to be built-in. 282 Disabled by default. 283 284`--enable-newlib-iconv-to-encodings' 285 Enable specific comma-separated list of \"to\" iconv encodings 286 to be built-in. 287 Disabled by default. 288 289`--enable-newlib-iconv-external-ccs' 290 Enable capabilities to load external CCS files for iconv. 291 Disabled by default. 292 293`--disable-newlib-atexit-dynamic-alloc' 294 Disable dynamic allocation of atexit entries. 295 Most hosts and targets have it enabled in configure.host. 296 297`--enable-newlib-reent-small' 298 Enable small reentrant struct support. 299 Disabled by default. 300 301`--enable-newlib-reent-binary-compat' 302 Enable backward binary compatibility for struct _reent. If enabled, then 303 unused members in struct _reent are preserved to maintain the structure 304 layout. 305 Disabled by default. 306 307`--enable-newlib-reent-thread-local' 308 Enable thread-local storage objects as a replacement for struct _reent 309 members. If enabled, then struct _reent is not defined and dedicated 310 thread-local storage objects are provided for each member of the default 311 struct _reent. For statically linked executables only the objects 312 required by the application are linked in. 313 Disabled by default. 314 315`--disable-newlib-fvwrite-in-streamio' 316 NEWLIB implements the vector buffer mechanism to support stream IO 317 buffering required by C standard. This feature is possibly 318 unnecessary for embedded systems which won't change file buffering 319 with functions like `setbuf' or `setvbuf'. The buffering mechanism 320 still acts as default for STDIN/STDOUT/STDERR even if this option 321 is specified. 322 Enabled by default. 323 324`--disable-newlib-fseek-optimization' 325 Disable fseek optimization. It can decrease code size of application 326 calling `fseek`. 327 Enabled by default. 328 329`--disable-newlib-wide-orient' 330 C99 states that each stream has an orientation, wide or byte. This 331 feature is possibly unnecessary for embedded systems which only do 332 byte input/output operations on stream. It can decrease code size 333 by disable the feature. 334 Enabled by default. 335 336`--enable-newlib-nano-malloc' 337 NEWLIB has two implementations of malloc family's functions, one in 338 `mallocr.c' and the other one in `nano-mallocr.c'. This options 339 enables the nano-malloc implementation, which is for small systems 340 with very limited memory. Note that this implementation does not 341 support `--enable-malloc-debugging' any more. 342 Disabled by default. 343 344`--disable-newlib-unbuf-stream-opt' 345 NEWLIB does optimization when `fprintf to write only unbuffered unix 346 file'. It creates a temorary buffer to do the optimization that 347 increases stack consumption by about `BUFSIZ' bytes. This option 348 disables the optimization and saves size of text and stack. 349 Enabled by default. 350 351`--enable-newlib-long-time_t' 352 Define time_t to long. On platforms with a 32-bit long type, this gives 353 raise to the year 2038 problem. The default type for time_t is a signed 354 64-bit integer on most systems. 355 Disabled by default. 356 357`--enable-newlib-use-gdtoa' 358 Use gdtoa rather than legacy ldtoa. gdtoa privides more accurate 359 output and faster conversion than legacy ldtoa, while it requires 360 more heap memory. gdtoa sometimes requires 16KB heap memory, so 361 if the platform does not have enough heap memory, consider disabling 362 this option. Legacy ldtoa also use heap, however, only 1KB memory 363 is malloc'ed. In addition, if malloc fails, it still works, with 364 less conversion accuracy. 365 Enabled by default. 366 367`--enable-multilib' 368 Build many library versions. 369 Enabled by default. 370 371`--enable-target-optspace' 372 Optimize for space. 373 Disabled by default. 374 375`--enable-malloc-debugging' 376 Indicate malloc debugging requested. 377 Disabled by default. 378 379`--enable-newlib-multithread' 380 Enable support for multiple threads. 381 Enabled by default. 382 383`--enable-newlib-iconv' 384 Enable iconv library support. 385 Disabled by default. 386 387`--enable-newlib-elix-level' 388 Supply desired elix library level (1-4). Please refer to HOWTO for 389 more information about this option. 390 Set to level 0 by default. 391 392`--disable-newlib-io-float' 393 Disable printf/scanf family float support. 394 Enabled by default. 395 396`--disable-newlib-supplied-syscalls' 397 Disable newlib from supplying syscalls. 398 Enabled by default. 399 400`--enable-lite-exit' 401 Enable lite exit, a size-reduced implementation of exit that doesn't 402 invoke clean-up functions such as _fini or global destructors. 403 Disabled by default. 404 405`--enable-newlib-nano-formatted-io' 406 This builds NEWLIB with a special implementation of formatted I/O 407 functions, designed to lower the size of application on small systems 408 with size constraint issues. This option does not affect wide-char 409 formatted I/O functions. Some notes about the feature: 410 1) The non-wide-char formatted I/O functions only support the C89 411 standard. The only exception is the configuration option provides 412 limited support for long double. Internally, the nano formatted I/O 413 functions use double so accuracy is only guaranteed to double 414 precision. 415 2) Floating-point support is split out of the formatted I/O code into 416 weak functions which are not linked by default. Programs that need 417 floating-point I/O support must explicitly request linking of one or 418 both of the floating-point functions: _printf_float or _scanf_float. 419 This can be done at link time using the -u option which can be passed 420 to either gcc or ld. The -u option forces the link to resolve those 421 function references. Floating-point format specifiers are recognized 422 by default, but if the floating-point functions are not explicitly 423 linked in, this may result in undefined behavior for programs that 424 need floating-point I/O support. 425 3) Integer-only versions of the formatted I/O functions (the iprintf/ 426 iscanf family) simply alias their regular counter-parts. 427 The affected functions are: 428 429 diprintf vdiprintf 430 431 siprintf fiprintf iprintf sniprintf asiprintf asniprintf 432 433 siscanf fiscanf iscanf 434 435 viprintf vfiprintf vsiprintf vsniprintf vasiprintf vasniprintf 436 437 viscanf vfiscanf vsiscanf 438 439 _diprintf_r _vdiprintf_r 440 441 _siprintf_r _fiprintf_r _iprintf_r _sniprintf_r _asiprintf_r 442 _asniprintf_r 443 444 _siscanf_r _fiscanf_r _iscanf_r 445 446 _viprintf_r _vfiprintf_r _vsiprintf_r _asniprintf_r _vasiprintf_r 447 _vasniprintf_r 448 449 _viscanf_r _vfiscanf_r _vsiscanf_r 450 451 4) As mentioned, the option does not affect wide-char formatted I/O. 452 The following configuration options are ignored for non-wide-char 453 formatted I/O functions, and can be thought of as disabled. 454 455 enable-newlib-io-pos-args 456 enable-newlib-io-c99-formats 457 enable-newlib-io-long-long 458 enable-newlib-io-long-double 459 enable-newlib-mb 460 461 Additionally, "enable/disable-newlib-io-float" is supported in 462 this specific implementation, one can use "disable-newlib-io-float" 463 to further reduce code size. In this case, the floating-point 464 specifiers will not be recognized or handled, and the -u option 465 will not work either. 466 467 5) As a rule, no features from outside of C89 standard will be 468 considered in this implementation. 469 470 Disabled by default. 471 472Running the Testsuite 473===================== 474 475To run newlib's testsuite, you'll need a site.exp in your home 476directory which points dejagnu to the proper baseboards directory and 477the proper exp file for your target. 478 479Before running make check-target-newlib, set the DEJAGNU environment 480variable to point to ~/site.exp. 481 482Here is a sample site.exp: 483 484# Make sure we look in the right place for the board description files. 485if ![info exists boards_dir] { 486 set boards_dir {} 487} 488lappend boards_dir "your dejagnu/baseboards here" 489 490verbose "Global Config File: target_triplet is $target_triplet" 2 491 492global target_list 493case "$target_triplet" in { 494 495 { "mips-*elf*" } { 496 set target_list "mips-sim" 497 } 498 499 default { 500 set target_list { "unix" } 501 } 502} 503 504mips-sim refers to an exp file in the baseboards directory. You'll 505need to add the other targets you're testing to the case statement. 506 507Now type make check-target-newlib in the top-level build directory to 508run the testsuite. 509 510Regenerating Configuration Files 511================================ 512 513At times you will need to make changes to configure.ac, Makefile.am and 514Makefile.inc files. This will mean that configure and Makefile.in files will 515need to be regenerated. The easiest way to do so is by using the autoreconf 516tool in the newlib directory. 517 518 autoreconf 519 520This will run a number of autotool programs for you. To see the individual 521steps, add the -v option. 522 523 autoreconf -v 524 525It is strongly advised that you use an adequate version of autotools. For this 526latest release, the following were used: autoconf 2.69 and automake 1.15.1. 527 528Reporting Bugs 529============== 530 531The correct address for reporting bugs found in NEWLIB is 532"newlib@sourceware.org". Please email all bug reports to that 533address. Please include the NEWLIB version number (e.g., newlib-4.2.0), 534and how you configured it (e.g., "sun4 host and m68k-aout target"). 535Since NEWLIB supports many different configurations, it is important 536that you be precise about this. 537 538Archives of the newlib mailing list are on-line, see 539 https://sourceware.org/ml/newlib/ 540
