diff options
Diffstat (limited to 'newlib/README')
| -rw-r--r-- | newlib/README | 319 |
1 files changed, 0 insertions, 319 deletions
diff --git a/newlib/README b/newlib/README deleted file mode 100644 index f74c7af03..000000000 --- a/newlib/README +++ /dev/null @@ -1,319 +0,0 @@ - README for newlib-1.13.0 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 and license. See the file -COPYING.NEWLIB for details. The rest of the release tree is under either -the GNU GPL or LGPL licenses. - -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.13.0.tar.gz file, you'll find a directory -called `newlib-1.13.0', 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 must follow the instructions in the section entitled -"Compiling NEWLIB". - -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://sources.redhat.com/newlib/docs.html - - 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 -================ - - To compile NEWLIB, you must build it in a directory separate from -the source 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. -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 specific 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.13.0, you can build NEWLIB in a separate -directory for a Sun 4 cross m68k-aout environment like this: - - cd newlib-1.13.0 - mkdir ../newlib-m68k-aout - cd ../newlib-m68k-aout - ../newlib-1.13.0/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.13.0' (or in a separate configured directory configured with -`--srcdir=PATH/newlib-1.13.0'), 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 - -The Build, Host and Target Concepts in newlib -============================================= - -The build, host and target concepts are defined for gcc as follows: - -build: the platform on which gcc is built. -host: the platform on which gcc is run. -target: the platform for which gcc generates code. - -Since newlib is a library, the target concept does not apply to it, and the -build, host, and target options given to the top-level configure script must -be changed for newlib's use. - -The options are shifted according to these correspondences: - -gcc's build platform has no equivalent in newlib. -gcc's host platform is newlib's build platform. -gcc's target platform is newlib's host platform. -and as mentioned before, newlib has no concept of target. - -`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. - -Running the Testsuite -===================== - -To run newlib's testsuite, you'll need a site.exp in your home -directory which points dejagnu to the proper baseboards directory and -the proper exp file for your target. - -Before running make check-target-newlib, set the DEJAGNU environment -variable to point to ~/site.exp. - -Here is a sample site.exp: - -# Make sure we look in the right place for the board description files. -if ![info exists boards_dir] { - set boards_dir {} -} -lappend boards_dir "your dejagnu/baseboards here" - -verbose "Global Config File: target_triplet is $target_triplet" 2 - -global target_list -case "$target_triplet" in { - - { "mips-*elf*" } { - set target_list "mips-sim" - } - - default { - set target_list { "unix" } - } -} - -mips-sim refers to an exp file in the baseboards directory. You'll -need to add the other targets you're testing to the case statement. - -Now type make check-target-newlib in the top-level build directory to -run the testsuite. - -Shared newlib -============= - -newlib uses libtool when it is being compiled natively (with ---target=i[34567]86-pc-linux-gnu) on an i[34567]86-pc-linux-gnu -host. This allows newlib to be compiled as a shared library. - -To configure newlib, do the following from your build directory: - -$(source_dir)/src/configure --with-newlib --prefix=$(install_dir) - -configure will recognize that host == target == -i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using -libtool. By default, libtool will build shared and static versions of -newlib. - -To compile a program against shared newlib, do the following (where -target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu): - -gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc - -To run the program, make sure that $(target_install_dir)/lib is listed -in the LD_LIBRARY_PATH environment variable. - -To create a static binary linked against newlib, do the following: - -gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm - -libtool can be instructed to produce only static libraries. To build -newlib as a static library only, do the following from your build -directory: - -$(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared - -Reporting Bugs -============== - -The correct address for reporting bugs found in NEWLIB is -"newlib@sources.redhat.com". Please email all bug reports to that -address. Please include the NEWLIB version number (e.g., newlib-1.13.0), -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://sources.redhat.com/ml/newlib/ |