newlib/README

   1                         README for newlib-1.9.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 with their own copyright.  See the file COPYING.NEWLIB
   9 for details.  The rest of the release tree is under either the GNU GPL or
  10 LPGL copyright.
  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-1.9.0.tar.gz file, you'll find a directory
  21 called `newlib-1.9.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://www.cygnus.com/pubs/gnupro
  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 1.9.0, you can build NEWLIB in a separate
  98 directory for a Sun 4 cross m68k-aout environment like this:
  99
 100      cd newlib-1.9.0
 101      mkdir ../newlib-m68k-aout
 102      cd ../newlib-m68k-aout
 103      ../newlib-1.9.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-1.9.0' (or in a separate configured directory configured with
 120 `--srcdir=PATH/newlib-1.9.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
 162 `configure' options
 163 ===================
 164
 165    Here is a summary of the `configure' options and arguments that are
 166 most often useful for building NEWLIB.  `configure' also has several other
 167 options not listed here.
 168
 169      configure [--help]
 170                [--prefix=DIR]
 171                [--srcdir=PATH]
 172                [--target=TARGET] HOST
 173
 174 You may introduce options with a single `-' rather than `--' if you
 175 prefer; but you may abbreviate option names if you use `--'.
 176
 177 `--help'
 178      Display a quick summary of how to invoke `configure'.
 179
 180 `--prefix=DIR'
 181      Configure the source to install programs and files in directory
 182      `DIR'.
 183
 184 `--exec-prefix=DIR'
 185      Configure the source to install host-dependent files in directory
 186      `DIR'.
 187
 188 `--srcdir=PATH'
 189      *Warning: using this option requires GNU `make', or another `make'
 190      that compatibly implements the `VPATH' feature.
 191      Use this option to make configurations in directories separate
 192      from the NEWLIB source directories.  Among other things, you can use
 193      this to build (or maintain) several configurations simultaneously,
 194      in separate directories.  `configure' writes configuration
 195      specific files in the current directory, but arranges for them to
 196      use the source in the directory PATH.  `configure' will create
 197      directories under the working directory in parallel to the source
 198      directories below PATH.
 199
 200 `--norecursion'
 201      Configure only the directory level where `configure' is executed;
 202      do not propagate configuration to subdirectories.
 203
 204 `--target=TARGET'
 205      Configure NEWLIB for running on the specified TARGET.
 206
 207      There is no convenient way to generate a list of all available
 208      targets.
 209
 210 `HOST ...'
 211      Configure NEWLIB to be built using a cross compiler running on
 212      the specified HOST.
 213
 214      There is no convenient way to generate a list of all available
 215      hosts.
 216
 217
 218 Reporting Bugs
 219 ==============
 220
 221 The correct address for reporting bugs found in NEWLIB is
 222 "newlib@sources.redhat.com".  Please email all bug reports to that
 223 address.  Please include the NEWLIB version number (e.g., newlib-1.9.0),
 224 and how you configured it (e.g., "sun4 host and m68k-aout target").
 225 Since NEWLIB supports many different configurations, it is important
 226 that you be precise about this.
 227
 228 Archives of the newlib mailing list are on-line, see
 229         http://sources.redhat.com/ml/newlib/