newlib/README

   1                         README for newlib-4.2.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 Prior to the 3.0.0 release, newlib supported both ANSI and K&R-style
   8 compilers.  As of 3.0.0, K&R is no longer supported.
   9
  10 The newlib and libgloss subdirectories are a collection of software from
  11 several sources, each with their own copyright and license.  See the file
  12 COPYING.NEWLIB for details.  The rest of the release tree is under either
  13 the GNU GPL or LGPL licenses.
  14
  15 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  16 IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  17 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  18
  19
  20 Unpacking and Installation -- quick overview
  21 ==========================
  22
  23 When you unpack the newlib-4.2.0.tar.gz file, you'll find a directory
  24 called `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
  32 To build NEWLIB, you must follow the instructions in the section entitled
  33 "Compiling NEWLIB".
  34
  35 This will configure and build all the libraries and crt0 (if one exists).
  36 If `configure' can't determine your host system type, specify one as its
  37 argument, e.g., sun4 or sun4sol2.  NEWLIB is most often used in cross
  38 environments.
  39
  40 NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS.
  41
  42
  43 More 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
  50 distribution.  The documentation is written in Texinfo format, which is
  51 a documentation system that uses a single source file to produce both
  52 on-line information and a printed manual.  You can use one of the Info
  53 formatting commands to create the on-line version of the documentation
  54 and TeX (or `texi2roff') to typeset the printed version.
  55
  56    If you want to format these Info files yourself, you need one of the
  57 Info 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,
  60 a program to print its DVI output files, and `texinfo.tex', the Texinfo
  61 definitions file.
  62
  63    TeX is a typesetting program; it does not print files directly, but
  64 produces output files called DVI files.  To print a typeset document,
  65 you need a program to print DVI files.  If your system has TeX
  66 installed, chances are it has such a program.  The precise command to
  67 use depends on your system; `lpr -d' is common; another (for PostScript
  68 devices) is `dvips'.  The DVI print command may require a file name
  69 without any extension or a `.dvi' extension.
  70
  71    TeX also requires a macro definitions file called `texinfo.tex'.
  72 This file tells TeX how to typeset a document written in Texinfo
  73 format.  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
  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 4.2.0, you can build NEWLIB in a separate
  98 directory 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
 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-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
 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    By default, the execution of build rules in `make' is less verbose.
 128 To disable, run `make V=1'; or use the `--disable-silent-rules’ option
 129 of `./configure'.
 130
 131 Specifying names for hosts and targets
 132 ======================================
 133
 134    The specifications used for hosts and targets in the `configure'
 135 script are based on a three-part naming scheme, but some short
 136 predefined aliases are also supported.  The full naming scheme encodes
 137 three 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
 146 facility to list all supported host and target names or aliases.
 147 `configure' calls the Bourne shell script `config.sub' to map
 148 abbreviations to full names; you can read the script, if you wish, or
 149 you 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
 164 The Build, Host and Target Concepts in newlib
 165 =============================================
 166
 167 The build, host and target concepts are defined for gcc as follows:
 168
 169 build: the platform on which gcc is built.
 170 host: the platform on which gcc is run.
 171 target: the platform for which gcc generates code.
 172
 173 Since newlib is a library, the target concept does not apply to it, and the
 174 build, host, and target options given to the top-level configure script must
 175 be changed for newlib's use.
 176
 177 The build system shifts the options according to these correspondences:
 178
 179 gcc's build platform has no equivalent in newlib.
 180 gcc's host platform is newlib's build platform.
 181 gcc's target platform is newlib's host platform.
 182 and as mentioned before, newlib has no concept of target.
 183
 184 In summary: the --target=TARGET switch to the top-level configure
 185 script configures newlib's host platform.
 186
 187 `configure' options
 188 ===================
 189
 190    Here is a summary of the `configure' options and arguments that are
 191 most often useful for building NEWLIB.  `configure' also has several other
 192 options not listed here.
 193
 194      configure [--help]
 195                [--prefix=DIR]
 196                [--srcdir=PATH]
 197                [--target=TARGET] HOST
 198
 199 You may introduce options with a single `-' rather than `--' if you
 200 prefer; 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
 242 To fit diverse usage models, NEWLIB supports a group of configuration
 243 options so that library features can be turned on/off according to
 244 target system's requirements.
 245
 246 One 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
 472 Running the Testsuite
 473 =====================
 474
 475 To run newlib's testsuite, you'll need a site.exp in your home
 476 directory which points dejagnu to the proper baseboards directory and
 477 the proper exp file for your target.
 478
 479 Before running make check-target-newlib, set the DEJAGNU environment
 480 variable to point to ~/site.exp.
 481
 482 Here is a sample site.exp:
 483
 484 # Make sure we look in the right place for the board description files.
 485 if ![info exists boards_dir] {
 486     set boards_dir {}
 487 }
 488 lappend boards_dir "your dejagnu/baseboards here"
 489
 490 verbose "Global Config File: target_triplet is $target_triplet" 2
 491
 492 global target_list
 493 case "$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
 504 mips-sim refers to an exp file in the baseboards directory.  You'll
 505 need to add the other targets you're testing to the case statement.
 506
 507 Now type make check-target-newlib in the top-level build directory to
 508 run the testsuite.
 509
 510 Regenerating Configuration Files
 511 ================================
 512
 513 At times you will need to make changes to configure.ac, Makefile.am and
 514 Makefile.inc files.  This will mean that configure and Makefile.in files will
 515 need to be regenerated.  The easiest way to do so is by using the autoreconf
 516 tool in the newlib directory.
 517
 518   autoreconf
 519
 520 This will run a number of autotool programs for you.  To see the individual
 521 steps, add the -v option.
 522
 523   autoreconf -v
 524
 525 It is strongly advised that you use an adequate version of autotools.  For this
 526 latest release, the following were used: autoconf 2.69 and automake 1.15.1.
 527
 528 Reporting Bugs
 529 ==============
 530
 531 The correct address for reporting bugs found in NEWLIB is
 532 "newlib@sourceware.org".  Please email all bug reports to that
 533 address.  Please include the NEWLIB version number (e.g., newlib-4.2.0),
 534 and how you configured it (e.g., "sun4 host and m68k-aout target").
 535 Since NEWLIB supports many different configurations, it is important
 536 that you be precise about this.
 537
 538 Archives of the newlib mailing list are on-line, see
 539         https://sourceware.org/ml/newlib/