native_client_sdk/src/libraries/third_party/newlib-extras/README

   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@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/