diff options
Diffstat (limited to 'newlib/README')
| -rw-r--r-- | newlib/README | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/newlib/README b/newlib/README new file mode 100644 index 00000000000..fdda052d3dd --- /dev/null +++ b/newlib/README @@ -0,0 +1,231 @@ + 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=<your 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/ |