README for newlib-1.8.2 release (mostly cribbed from the README in the gdb-4.13 release) This is `newlib', a simple ANSI C library, math library, and collection of board support packages. The newlib and libgloss subdirectories are a collection of software from several sources, each with their own copyright. See the file COPYING.NEWLIB for details. The rest of the release tree is under either the GNU GPL or LPGL copyright. THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Unpacking and Installation -- quick overview ========================== When you unpack the newlib-1.8.2.tar.gz file, you'll find a directory called `newlib-1.8.2', which contains: COPYING config/ install-sh* mpw-configure COPYING.LIB config-ml.in libgloss/ mpw-install COPYING.NEWLIB config.guess* mkinstalldirs* newlib/ CYGNUS config.sub* move-if-change* symlink-tree* ChangeLog configure* mpw-README texinfo/ Makefile.in configure.in mpw-build.in README etc/ mpw-config.in To build NEWLIB, you can just do: cd newlib-1.8.2 ./configure --target= make all install This will configure and build all the libraries and crt0 (if one exists). If `configure' can't determine your host system type, specify one as its argument, e.g., sun4 or sun4sol2. NEWLIB is most often used in cross environments. NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS. More Documentation ================== Newlib documentation is available on the net via: http://www.cygnus.com/pubs/gnupro All the documentation for NEWLIB comes as part of the machine-readable distribution. The documentation is written in Texinfo format, which is a documentation system that uses a single source file to produce both on-line information and a printed manual. You can use one of the Info formatting commands to create the on-line version of the documentation and TeX (or `texi2roff') to typeset the printed version. If you want to format these Info files yourself, you need one of the Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. If you want to typeset and print copies of this manual, you need TeX, a program to print its DVI output files, and `texinfo.tex', the Texinfo definitions file. TeX is a typesetting program; it does not print files directly, but produces output files called DVI files. To print a typeset document, you need a program to print DVI files. If your system has TeX installed, chances are it has such a program. The precise command to use depends on your system; `lpr -d' is common; another (for PostScript devices) is `dvips'. The DVI print command may require a file name without any extension or a `.dvi' extension. TeX also requires a macro definitions file called `texinfo.tex'. This file tells TeX how to typeset a document written in Texinfo format. On its own, TeX cannot read, much less typeset a Texinfo file. `texinfo.tex' is distributed with NEWLIB and is located in the `newlib-VERSION-NUMBER/texinfo' directory. Compiling NEWLIB in another directory ===================================== If you want to run NEWLIB versions for several host or target machines, you need a different `newlib' compiled for each combination of host and target. `configure' is designed to make this easy by allowing you to generate each configuration in a separate subdirectory, rather than in the source directory. If your `make' program handles the `VPATH' feature correctly (like GNU `make') running `make' in each of these directories builds the `newlib' libraries specified there. To build `newlib' in a separate directory, run `configure' with the `--srcdir' option to specify where to find the source. (You also need to specify a path to find `configure' itself from your working directory. If the path to `configure' would be the same as the argument to `--srcdir', you can leave out the `--srcdir' option; it will be assumed.) For example, with version 1.8.2, you can build NEWLIB in a separate directory for a Sun 4 cross m68k-aout environment like this: cd newlib-1.8.2 mkdir ../newlib-m68k-aout cd ../newlib-m68k-aout ../newlib-1.8.2/configure --host=sun4 --target=m68k-aout make When `configure' builds a configuration using a remote source directory, it creates a tree for the binaries with the same structure (and using the same names) as the tree under the source directory. In the example, you'd find the Sun 4 library `libiberty.a' in the directory `newlib-m68k-aout/libiberty', and NEWLIB itself in `newlib-m68k-aout/newlib'. When you run `make' to build a program or library, you must run it in a configured directory--whatever directory you were in when you called `configure' (or one of its subdirectories). The `Makefile' that `configure' generates in each source directory also runs recursively. If you type `make' in a source directory such as `newlib-1.8.2' (or in a separate configured directory configured with `--srcdir=PATH/newlib-1.8.2'), you will build all the required libraries. When you have multiple hosts or targets configured in separate directories, you can run `make' on them in parallel (for example, if they are NFS-mounted on each of the hosts); they will not interfere with each other. Specifying names for hosts and targets ====================================== The specifications used for hosts and targets in the `configure' script are based on a three-part naming scheme, but some short predefined aliases are also supported. The full naming scheme encodes three pieces of information in the following pattern: ARCHITECTURE-VENDOR-OS For example, you can use the alias `sun4' as a HOST argument or in a `--target=TARGET' option. The equivalent full name is `sparc-sun-sunos4'. The `configure' script accompanying NEWLIB does not provide any query facility to list all supported host and target names or aliases. `configure' calls the Bourne shell script `config.sub' to map abbreviations to full names; you can read the script, if you wish, or you can use it to test your guesses on abbreviations--for example: % sh config.sub sun4 sparc-sun-sunos4.1.1 % sh config.sub sun3 m68k-sun-sunos4.1.1 % sh config.sub decstation mips-dec-ultrix4.2 % sh config.sub hp300bsd m68k-hp-bsd % sh config.sub i386v i386-pc-sysv % sh config.sub i786v Invalid configuration `i786v': machine `i786v' not recognized `configure' options =================== Here is a summary of the `configure' options and arguments that are most often useful for building NEWLIB. `configure' also has several other options not listed here. configure [--help] [--prefix=DIR] [--srcdir=PATH] [--target=TARGET] HOST You may introduce options with a single `-' rather than `--' if you prefer; but you may abbreviate option names if you use `--'. `--help' Display a quick summary of how to invoke `configure'. `--prefix=DIR' Configure the source to install programs and files in directory `DIR'. `--exec-prefix=DIR' Configure the source to install host-dependent files in directory `DIR'. `--srcdir=PATH' *Warning: using this option requires GNU `make', or another `make' that compatibly implements the `VPATH' feature. Use this option to make configurations in directories separate from the NEWLIB source directories. Among other things, you can use this to build (or maintain) several configurations simultaneously, in separate directories. `configure' writes configuration specific files in the current directory, but arranges for them to use the source in the directory PATH. `configure' will create directories under the working directory in parallel to the source directories below PATH. `--norecursion' Configure only the directory level where `configure' is executed; do not propagate configuration to subdirectories. `--target=TARGET' Configure NEWLIB for running on the specified TARGET. There is no convenient way to generate a list of all available targets. `HOST ...' Configure NEWLIB to be built using a cross compiler running on the specified HOST. There is no convenient way to generate a list of all available hosts. Reporting Bugs ============== The correct address for reporting bugs found in NEWLIB is "newlib@sourceware.cygnus.com". Please email all bug reports to that address. Please include the NEWLIB version number (e.g., newlib-1.8.2), and how you configured it (e.g., "sun4 host and m68k-aout target"). Since NEWLIB supports many different configurations, it is important that you be precise about this. Archives of the newlib mailing list are on-line, see http://sourceware.cygnus.com/ml/newlib/