Subversion Repositories openrisc_2011-10-31

                        README for newlib-1.17.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 wi6h 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.17.0.tar.gz file, you'll find a directory

called `newlib-1.17.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.17.0, you can build NEWLIB in a separate

directory for a Sun 4 cross m68k-aout environment like this:

     cd newlib-1.17.0

     mkdir ../newlib-m68k-aout

     cd ../newlib-m68k-aout

     ../newlib-1.17.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.17.0' (or in a separate configured directory configured with

`--srcdir=PATH/newlib-1.17.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

Regenerating Configuration Files

================================

At times you will need to make changes to configure.in and Makefile.am files.

This will mean that configure and Makefile.in files will need to be

regenerated.

At the top level of newlib is the file: acinclude.m4.  This file contains

the definition of the NEWLIB_CONFIGURE macro which is used by all configure.in

files in newlib.  You will notice that each directory in newlib containing

a configure.in file also contains an aclocal.m4 file.  This file is

generated by issuing: aclocal -I${relative_path_to_toplevel_newlib_dir}

-I${relative_path_to_toplevel_src_dir}

The first relative directory is to access acinclude.m4.  The second relative

directory is to access libtool information in the top-level src directory.

For example, to regenerate aclocal.m4 in newlib/libc/machine/arm:

  aclocal -I ../../.. -I ../../../..

Note that if the top level acinclude.m4 is altered, every aclocal.m4 file

in newlib should be regenerated.

If the aclocal.m4 file is regenerated due to a change in acinclude.m4 or

if a configure.in file is modified, the corresponding configure file in the

directory must be regenerated using autoconf.  No parameters are necessary.

In the previous example, we would issue:

  autoconf

from the newlib/libc/machine/arm directory.

If you have regenerated a configure file or if you have modified a Makefile.am

file, you will need to regenerate the appropriate Makefile.in file(s).

For newlib, automake is a bit trickier.  First of all, all Makefile.in

files in newlib (and libgloss) are generated using the --cygnus option

of automake.

Makefile.in files are generated from the nearest directory up the chain

which contains a configure.in file.  In most cases, this is the same

directory containing configure.in, but there are exceptions.

For example, the newlib/libc directory has a number of

subdirectories that do not contain their own configure.in files (e.g. stdio).

For these directories, you must issue the automake command from newlib/libc

which is the nearest parent directory that contains a configure.in.

When you issue the automake command, you specify the subdirectory for

the Makefile.in you are regenerating.  For example:

   automake --cygnus stdio/Makefile stdlib/Makefile

Note how multiple Makefile.in files can be created in the same step.  You

would not specify machine/Makefile or sys/Makefile in the previous example

because both of these subdirectories contain their own configure.in files.

One would change to each of these subdirectories and in turn issue:

   automake --cygnus Makefile

Let's say you create a new machine directory XXXX off of newlib/libc/machine.

After creating a new configure.in and Makefile.am file, you would issue:

   aclocal -I ../../..

   autoconf

   automake --cygnus Makefile

from newlib/libc/machine/XXXX

It is strongly advised that you use an adequate version of autotools.

For this latest release, this would be: autoconf 2.59, aclocal 1.9.6, and

automake 1.9.6.

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.17.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/