             README for Cygnus Board Support Package
               Updated 12 May 1999 by Mark Salter

Unpacking and Installation -- quick overview
==========================

In this release, the BSP sources, the generic GNU include files, and
other things all have directories of their own underneath the bsp
directory.  The idea is that a variety of GNU tools can share a common
copy of these things. Configuration scripts and makefiles exist to
cruise up and down this directory tree and automatically build all
the pieces in the right order.

When you unpack the bsp.tar.gz file, you'll find a directory called
`bsp', which contains:

  COPYING          config-ml.in     install-sh*      mpw-build.in
  COPYING.LIB      config.guess*    ltconfig*        mpw-config.in
  ChangeLog        config.if        ltmain.sh        mpw-configure
  Makefile.in      config.sub*      missing*         mpw-install
  README           configure*       mkinstalldirs*   symlink-tree*
  bsp/             configure.in     move-if-change*  texinfo/
  config/          etc/             mpw-README       ylwrap*

To configure and build the BSP, you must specify a target.

	cd bsp
	./configure --target=TARGET
	make

This will configure and build all of the BSP parts for the given
TARGET. If `configure' can't determine your system type, specify
one as its argument, e.g., --host=sun4.

If you get compiler warnings during this stage, see the `Reporting Bugs'
section below; there are a few known problems.

The BSP requires an installed GNU C cross-compiler for the desired TARGET.
If you do not have a GNU C cross-compiler for your system, you will need
to download and install one.  It is available via anonymous FTP from ftp.gnu.org,
in /pub/gnu/gcc (as a URL, that's ftp://ftp.gnu.org/pub/gnu/gcc).

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 the BSP 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


More Documentation
******************

   All the documentation for the BSP 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.

   The BSP includes an already formatted copy of the on-line Info version of
this manual in the `bsp/doc' subdirectory.  The main Info file is
`bsp/bsp/doc/bsp.info', and it may refer to subordinate files matching
`bsp.info*' in the same directory.  If necessary, you can print out
these files, or read them with any editor; but they are easier to read
using the `info' subsystem in GNU Emacs or the standalone `info' program,
available as part of the GNU Texinfo distribution.

   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 have `makeinfo' installed, and are in the top level BSP
source directory, you can make the Info file by typing:

     cd bsp/doc
     make info

   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.  This file is included in the BSP distribution,
in the directory `bsp/texinfo'.

   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 the BSP and is located in the
`bsp/texinfo' directory.

   If you have TeX and a DVI printer program installed, you can typeset
and print this manual.  First switch to the the `bsp/doc' subdirectory
of the main source directory and then type:

     make

Installing the BSP
******************

   The BSP comes with a `configure' script that automates the process of
preparing for installation; you can then use `make' to build the BSP.

   The distribution includes all the source code you need for the BSP in
a single directory, whose name is usually composed by appending the
version number to `bsp'.

   For example, the BSP version 1.00 distribution is in the `bsp-1.00'
directory.  That directory contains:

`bsp-1.00/{COPYING,COPYING.LIB}'
     Standard GNU license files.  Please read them.

`bsp-1.00/config*'
     script for configuring the BSP, along with other support files

`bsp-1.00/bsp'
     the source specific to the BSP itself

`bsp-1.00/include'
     GNU include files

`bsp-1.00/texinfo'
     The `texinfo.tex' file, which you need in order to make a printed
     manual using TeX.

`bsp-1.00/etc'
     Coding standards and other miscellanea.

   `configure' is a Bourne-shell (`/bin/sh') script; if your system
does not recognize this automatically when you run a different shell,
you may need to run `sh' on it explicitly:

     sh configure

   If you run `configure' from a directory that contains source
directories for multiple libraries or programs, such as the `bsp-1.00'
source directory for version 1.00, `configure' creates configuration
files for every directory level underneath (unless you tell it not to,
with the `--norecursion' option).

   You should install the BSP in the same place as the GNU C compiler
so that gcc can find certain elements of the BSP when building BSP
based applications.


Compiling the BSP in another directory
======================================

   If you want to build BSP versions for several target architectures,
you need a different BSP compiled for each 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 (GNU `make' and SunOS 'make' are two that should),
running `make' in each of these directories builds the BSP specified
there.

   To build 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.00, you can build in a separate
directory for powerpc-eabi like this:

     cd bsp-1.00
     mkdir ../bsp-ppc
     cd ../bsp-ppc
     ../bsp-1.00/configure --target=powerpc-eabi
     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.

   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 `bsp-1.00' (or in a separate configured directory configured with
`--srcdir=PATH/bsp-1.00'), you will build all the required libraries,
and then build the BSP.

`configure' options
===================

   Here is a summary of the `configure' options and arguments that are
most often useful for building the BSP.  `configure' also has several
other options not listed here.  *note : (configure.info)What Configure
Does, for a full explanation of `configure'.

     configure [--help]
               [--prefix=DIR]
               [--srcdir=PATH]
               [--norecursion] [--rm]
	       [--enable-build-warnings]
               [--target=TARGET]
	       [--host=HOST]
	       [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 under 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 BSP 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.

`--rm'
     Remove the configuration that the other arguments specify.

`--enable-build-warnings'
     When building the BSP sources, ask the compiler to warn about any
     code which looks even vaguely suspicious.  You should only using
     this feature if you're compiling with GNU CC.  It passes the
     following flags:
	-Wall
	-Wpointer-arith
	-Wstrict-prototypes
	-Wmissing-prototypes
	-Wmissing-declarations

`--target=TARGET'
     Configure BSP for the specified TARGET.

     There is no convenient way to generate a list of all available
     targets.

`configure' accepts other options, for compatibility with configuring
other GNU tools recursively; but these are the only options that affect
the BSP or its supporting libraries.


Reporting Bugs
===============

[!!Need something here!!]



(this is for editing this file with GNU emacs)
Local Variables:
mode: text
End:
