don't mention sanitization in ChangeLog

[platform/upstream/binutils.git] / install-texi.in

\input texinfo
@c
@c search for "UPDATE!" for items that will need examination on future
@c releases
@c
@c This file may require a nonstandard texinfo.tex to format; if you
@c need it, please contact Cygnus Support (email editor-in-chief@cygnus.com)
@setfilename README.info
@c FIXME: XCOMP stuff not ready to go.  For example,
@c FIXME: no mention of lack of -msoft-float support for XCOMP, yet.
@c
@c This file describes how to install a Cygnus Progressive Release.
@c
@c Copyright (C) 1991, 1992 Cygnus Support
@c This text may be freely distributed under the terms of the GNU
@c General Public License.
@c
@c $Id$
@c         CONFIG: One of these hosts should be set, the others clear:
@set HOSTsun4
@clear HOSTsun3
@clear HOSTdecstation
@clear HOSTrs6000
@clear HOSTiris
@c         CONFIG: In addition, XCOMP should be set for discussion of
@c                cross-compilation facilities 
@clear XCOMP
@c
@c
@iftex
@c The include file "texiplus.tex" is in the texinfo/cygnus dir, and
@c implements Cygnus modifications to the texinfo manual style.
@input texiplus
@c The include file "smpklug.texi" is a kluge to deal with local
@c document production issues at Cygnus; it's safe to comment out this
@c line if you don't have (or don't want) the file.
@input smpklug.texi
@smallbook
@cropmarks
@setchapternewpage on
@finalout
@end iftex
@settitle Progressive--||RELNO|| Installation
@tex
% override-override: the following \font lines are redundant if you're
% using an unmodified FSF texinfo.  
\globaldefs=1
\font\texttt=cmtt10 scaled \magstephalf\let\tentt=\texttt
\font\textsl=cmsl10 scaled \magstephalf\let\tensl=\textsl
\font\textsf=cmss10 scaled \magstephalf\let\tensf=\textsf
\globaldefs=0
%end override-override
% WARNING: NONSTANDARD USAGE we need \tensf for print, without
% upsetting info.  We weren't using @b in this note, so I redefine it:
%
\global\def\b#1{{\tensf #1}}
\global\parindent=0pt
@end tex
@titlepage
@title Installation Notes
@sp 3
@table @strong
@item Cygnus Support Developer's Kit
@item Progressive Release ||RELNO|| for ||HOST||
@item {}
@item Contents
@end table
@c TOGGLE XREF DISPLAY TO AVOID SQUARE BRACKETS OR QUOTES:
@c (Cygnus "texiplus.tex" hack.  If you want standard texinfo remove
@c or comment-out instances of @altref).
@altref
@format
@ref{Brief,,Installing in Brief}
@ref{Contents,,Release Contents}.
@ref{Platforms,,Supported Platforms}.

@ref{Installing,,Installing the Developer's Kit}.
@ref{local-install,,Installing in @file{/usr/cygnus} with a local tape drive}.
@ref{cross-install,,Installing in @file{/usr/cygnus} with another machine's tape drive}.
@ref{Examples,,Installation Examples}.
@ref{Install-Options,,Installation Options}

@ref{Why-fixincludes,,Why Convert System Header Files?}
@ref{Links,,Links for Easy Access and Updating}
@ref{Paths,,Changing the Paths}
@ref{Trouble,,Some Things that Might go Wrong}
@ref{Rebuilding,,Rebuilding From Source}.
@ref{Removing,,Removing the Developer's Kit}.

@ref{Cygnus-FSF,,Cygnus Progressive Releases and the FSF}.
@ref{Cygnus-Support,,About Cygnus Support}.
@end format
@c TOGGLE XREF DISPLAY BACK, TO RESTORE MARKERS AROUND SECNAMES:

@altref
@author Cygnus Support @hfill hotline: +1 415 322 7836
@page

@tex
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
\xdef\Rmanvers{{\it Installation Notes (Progressive Developer's Kit)}, \$Revision$} % *NOT* for use in headers, footers
{\parskip=0pt \hfill Cygnus Support\par \hfill \Rmanvers\par \hfill
\TeX{}info \texinfoversion\par }
\global\def\manvers{Progressive ||RELNO|| for ||HOST||}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1991, 1992 Cygnus Support

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.

@end titlepage

@ifinfo
@node Top, Brief, (dir), (dir)

This file is about the Cygnus Developer's Kit: what's in it, how to
install it, and how to reconfigure it.

@menu
* Brief::                       Installing in Brief
* Contents::                    Release Contents
* Requirements::                System Requirements
* Installing::                  Installing the Developer's Kit
* Examples::                    Installation Examples
* Install-Options::             Installation Options
* Links::                       Links for Easy Access and Updating
* Running::                     Running the Programs
* Paths::                       Changing the Paths
* Trouble::                     Some Things that Might go Wrong
* Rebuilding::                  Rebuilding From Source
* Removing::                    Removing Parts of the Developer's Kit
* Cygnus-FSF::                  Cygnus Releases and the FSF
* Cygnus-Support::              About Cygnus Support

 --- The Detailed Node Listing ---

Release Contents

* Platforms::                   Supported Platforms

Supported Platforms

* Requirements::                System Requirements

Installing the Developer's Kit

* local-install::               Installing with a local tape drive
* cross-install::               Installing with another machine's tape drive

Installation Examples

* binaries::                    Installing binaries only
* ||HOSTstr||-remote::          Reading tape on any machine, finishing on ||HOST||
* source-remove::               Removing Source

Installation Options

* Why-fixincludes::             Why Convert System Header Files?

Links for Easy Access and Updating

* Running::                     Running the Programs

Some Things that Might go Wrong

* No Drive::                    No Local Tape Drive
* Limited Space::               Not Enough Space
* No access::                   No Access to @file{/usr/cygnus}
* Install errors::              Error Messages from @code{Install}

Rebuilding From Source

* Configuration::               Configuration
* Config Names::                Specifying Names for Hosts and Targets
* configure Options::           @code{configure} Options
* Compilation::                 Compilation
* Installation::                Installation
@end menu

@end ifinfo

@node Brief, Contents, Top, Top
@unnumberedsubsubsec Installing in Brief
@strong{You can run the brief installation procedure if:}
@itemize @bullet
@item 
You have a ||TAPdflt|| release tape (see tape label), and
@item
Your ||HOST|| has its own ||TAPdflt|| tape drive (@code{||DEVdflt||}), and
@item
You're willing to use the installation directory @file{/usr/cygnus}, and
@item
You have at least ||DF|| MB available in @code{/usr} (try @samp{df /usr})
@end itemize
Otherwise, see @ref{Installing,,Installing the
Developer's Kit}.

@strong{Steps for Brief Install:}

@enumerate
@item 
Make sure you can write in @samp{/usr/cygnus}, by typing:

@example
eg$ @b{su root}
password:           @i{(enter root password)}
# @b{mkdir /usr/cygnus}        @i{(ignore ``File exists'' error if any)}
# @b{chmod 777 /usr/cygnus}
# @b{exit}              @i{(root access not needed beyond this)}
@end example

@item
Load the Progressive--||RELNO|| tape into your tape drive.

@item
Get the @code{Install} script from the tape:

@example
eg$ @b{cd /tmp}
eg$ @b{tar xfv ||DEVdflt|| Install}
@end example

@item
Run the @code{Install} script:

@example
eg$ @b{./Install}
@end example

@code{Install} displays messages about its activity, ending with

@example
Done.
@end example

@item
Build symbolic links to make execution paths easy:

@example
eg$ @b{cd /usr/cygnus}
eg$ @b{ln -s progressive-||RELNO|| progressive}
eg$ @b{su root}       @i{(may need root access to put link in /usr)}
password:
# @b{ln -s /usr/cygnus/progressive/H-||HOSTstr|| /usr/progressive}
# @b{exit}            @i{(give up root access as soon as possible)}
@end example

@item
Use your Cygnus customer-ID (see cover letter) to tag your copy of our
problem-report form:

@example
eg$ @b{/usr/progressive/bin/install@t{_}cid @var{ID}}
@end example

@item
Remove public write access from @file{/usr/cygnus}.  See your System
Administrator for the correct permissions at your site.
@end enumerate

You're done!  Anyone who puts @samp{/usr/progressive/bin} in her or his
@code{PATH} can use the Developer's Kit.

@node Contents, Requirements, Brief, Top
@unnumbered Release Contents

This Developer's Kit is a Cygnus Support @dfn{Progressive Release}: the
programs in it are recent versions, which have been tested and certified
both individually and as a coordinated suite of tools.
The kit includes both source and binaries for:  

@c UPDATE! Anything new shoveled in?

@c ifclear doesn't seem to nest well.  For that reason, and due to lack
@c of "else" to ifclear, and due to lack of expressions in ifset/ifclear
@c arguments, "DoFullTable" used in this contorted fashion:

@set DoFullTable

@ifset HOSTrs6000
@clear DoFullTable
@end ifset

@ifset HOSTdecstation
@clear DoFullTable
@end ifset

@ifset HOSTiris
@clear DoFullTable
@end ifset

@table @t
@item gcc
C compiler

@item g++
C++ compiler

@ifset DoFullTable
@item gas
assembler
@end ifset

@item gdb
debugger

@item gprof
Performance analyzer

@item byacc
Parser generator

@item flex
Fast lexical analyzer generator

@ifset DoFullTable
@item ld
linker
@end ifset

@item make
compilation control program

@item libg++.a
C++ class library

@ifset DoFullTable
@item ar
Manages object code archives

@item nm
Lists object file symbol tables

@item objdump
Displays object file information

@item ranlib
Generates archive index

@item size
Lists section and total sizes

@item strip
Discards symbols
@end ifset

@item makeinfo
@itemx info
Documentation tools

@item texinfo.tex
@itemx texindex
Documentation printing tools

@item send_pr
Script to send structured problem reports to Cygnus

@item diff
Compares source files

@item patch
Installs source fixes
@end table

@menu
* Platforms::                   Supported Platforms
@end menu

@node Platforms,  , Contents, Contents
@unnumberedsec Supported Platforms

@table @strong
@item ||HOST||
All programs in your Developer's Kit run on ||HOST|| computers; we
ship binaries (configured to install and run under @file{/usr/cygnus})
as well as all source code.

@ignore
@ifset HOSTsun4
@item @sc{sparc} clones
Whenever this note refers to ``Sun-4'' computers, you can also use a
@sc{sparc} clone---that is, any computer system based on the @sc{sparc}
architecture, regardless of its manufacturer.
@end ifset
@end ignore

@ifset XCOMP
@item Cross-Compiling
@sc{gcc}, @sc{gas}, @sc{gdb}, and the binary
utilities are preconfigured to generate and manage code for ||TARGET||
architectures.
@end ifset

@item Other Platforms
For information on other platforms or other programs
that we may support, please contact Cygnus Support at:

@table @strong
@item voice
+1 415 322 3811
@item hotline
+1 415 322 7836
@item fax
+1 415 322 3270
@item email
@code{info@@cygnus.com}
@end table
@end table

@menu
* Requirements::                System Requirements
@end menu

@node Requirements, Installing, Contents, Top
@unnumbered System Requirements

@table @strong
@item OS Level
Progressive Release ||RELNO|| for ||HOST|| hosts requires
@ifset HOSTsun4
SunOS 4.1.1 (or later).
@end ifset
@ifset HOSTsun3
SunOS 4.1 (or later).
@end ifset
@ifset HOSTdecstation
ULTRIX 4.0.  For Ultrix 4.2, some workarounds are required even to run
the installation script; if you would like to try these workarounds,
please call the Cygnus hotline @w{+1 415 322 7836}.
@end ifset
@ifset HOSTrs6000
AIX 3.1.5 (or later).

@item IBM Software Patches
Debugging code compiled with @sc{gcc} on the RS/6000 requires that you
upgrade the AIX assembler @code{/bin/as} with a replacement that is available
from IBM.  Without the upgrade, you can still compile your code, but
@samp{gcc -g @dots{}} will not work.

Any IBM RS/6000 customer can order and get the replacement assembler,
and install it on one or more machines.  It is distributed both on
diskette and via VNET, for downloading via ftp.  VNET distribution may
be desirable if you have a friendly IBM representative nearby with a
networked VM machine.

In either case, to order the replacement assembler from IBM, first
execute @samp{lslpp -h bos.obj} to determine your release level.  (Look
on the @samp{ACTIVE} line for something like @samp{03.01.0005.0012}.)
Then (in North America) call IBM Support at 800--237--5511.  Ask for
emergency shipment of the RS/6000 AIX fix for APAR IX22829.  They may
ask you to verify that it's a fix for ``@code{.extern foo} conflicts
with defining @code{foo}''; say yes.  They may also ask you for your
customer number.  If you do not know it, you will still be able to get
the fix, but you will have to be persistent.

You will receive a tar or tar.Z file containing an assembler plus
installation instructions.

If you tell them you're running AIX version 3.2, you may be told that
no fix is available yet.  In fact the 3.1.5 fix works fine on version
3.2.  Request it anyway.

IBM is working on a second upgrade to replace IX22829 and fix two
more problems with debug information.  There's no scheduled availability
yet, but it's probably summer 1992.  Ask for the fix for APAR IX26107,
``Don't allow @code{.csect name[BS]} or @code{[UC]}''.  (Without the
second upgrade, debugging works, but there may be occasional
aberrations.)

IBM has corresponding support organizations outside of North America.
If you are not in North America, call your IBM branch office and ask
them to put you in touch with the department that handles emergency
fixes for AIX on the RS/6000.  If that doesn't work, ask for the
department that handles software defect support for AIX on the RS/6000.
Then ask for the emergency APAR fix.
@end ifset
@ifset HOSTiris
IRIX 4.0.1 (or later).
@end ifset
@c UPDATE! fill in OS for all supported platforms.

@item Tape Drive
You need access to a tape drive that can read the distribution tape.
The tape drive need not be on the ||HOST|| where you want to run
the software; but it is best if the machine with a tape drive and your ||HOST||
can mount a common file system.  At the very least, you need some sort
of file transfer capability between the machine with a tape drive and
your ||HOST||.

Cygnus release tapes are labelled to identify the kind of
tape used; either ||TAPdflt|| tapes, or Exabyte tapes.

@item Disk Space
The total space required to extract and install
binaries and source for all programs is
||DF|| megabytes.

The software is configured to go into @file{/usr/cygnus}.  If you have
space available, but not in the same file system as @file{/usr}, you can
use @samp{ln -s} to create @file{/usr/cygnus} as a symbolic link to the
file system where you do have the space available.

If you don't have enough space, you may be able to install binaries only;
see @ref{Limited Space,,Not Enough Space}.  The space required for
installing the binaries on ||HOST|| systems is ||BD|| megabytes.

@item Write Access
You need to to sign on to an account with write access to @file{/usr},
or at least to an existing @file{/usr/cygnus} directory.  If you can't
write in @file{/usr} or @file{/usr/cygnus}, see @ref{No access,,No
Access to @file{/usr/cygnus}}.

Root access is @emph{not} necessary to run the installation itself;
but you might need it briefly to arrange for a writable
@file{/usr/cygnus} directory, and to build a symbolic link in @file{/usr} after
the installation is complete.  The detailed installation instructions show
when this may be necessary.  We recommend you avoid @samp{su root} whenever
possible.
@end table

@node Installing, Examples, Requirements, Top
@unnumbered Installing the Developer's Kit

@iftex
This note shows the different parts of examples like this:
@table @asis
@item @code{Computer output is shown in typewriter font.}
@item @b{Your input is indicated by a sans-serif font.}
@item @i{Comments appear in italic font}.
@end table
@end iftex
In examples, we show the system prompt as @samp{eg$}.

The Cygnus Progressive--||RELNO|| tape contains two separate @code{tar}
files.  The first file contains a script called @code{Install};
the second file contains the Progressive software.  To get
the software onto your system, you need to make sure you have the space
you'll need for it, and get the @code{Install} script off the tape.
Then you can use the @code{Install} script to choose what else to
install.

Here is more detail about what to do.  Two checklists follow.  The first
checklist shows what to do if you have a tape drive on the same system
(a ||HOST||) where you want to install the Developer's Kit; the
second shows how to use another networked machine to read the tape, then
finish the installation on your ||HOST||.  

Both checklists give the procedure for installing the Developer's Kit
under @file{/usr/cygnus} (which can be a symbolic link from somewhere
else, if you like).  We recommend you use this location for the
software, because the precompiled, ready-to-run versions of the tools
are configured this way.  (If you want to use a different location, and
cannot establish a symbolic link from it to @file{/usr/cygnus}, please
see @ref{Install-Options,,Installation Options}.  To use the software
conveniently after installing elsewhere, you should reconfigure and
recompile from source; see @ref{Paths,,Changing the Paths}.)

Both checklists are very similar to @ref{Brief,,Installing in Brief},
but provide more discussion of each step, and offer alternatives for
tape drives, for systems whose available disk space is not in
@code{/usr}, and for installing only portions of the Developer's Kit.

@menu
* local-install::               Installing with a local tape drive
* cross-install::               Installing with another machine's tape drive
@end menu

@node local-install, cross-install, Installing, Installing
@unnumberedsubsec Installing in @file{/usr/cygnus}, with a local tape drive

This procedure is for a ||HOST|| that has its own tape drive.  

Installing this way will install all the source code, plus the binaries for
the ||HOST||.  If you don't want both source and binaries, stop after
extracting @code{Install} from the tape, and read about what options you
can use with @code{Install} in @ref{Install-Options,,Installation
Options}.  For examples of variations on what to install,
@xref{Examples,,Installation Examples}.

@enumerate
@item
find out the name of the @emph{non-rewinding} tape device on your
machine that can read the release tape.  Cygnus release tapes are
labelled to identify the kind of tape used---either ||TAPdflt|| or Exabyte.
@ifset HOSTiris
You must also be certain to use a @emph{non-byte-swapping} tape device.
See @samp{man tps} for details.
@end ifset
@ifset HOSTrs6000
On RS/6000 systems, you can find details on tape drives in
@samp{man rmt}.
@end ifset


You should use one of the following devices:
@table @emph
@item ||TAPdflt|| tapes
Use @file{||DEVdflt||} where the examples show @code{/dev/@var{tape}}.

@item Exabyte tapes
The device name depends on how your Exabyte tape drive was installed;
ask your system administrator.  
@ifset HOSTsun4
You will probably use one of
@file{/dev/nrst0} or @file{/dev/nrst1} where we show
@code{/dev/@var{tape}}.
@end ifset
@ifset HOSTsun3
You will probably use one of
@file{/dev/nrst0} or @file{/dev/nrst1} where we show
@code{/dev/@var{tape}}.
@end ifset
@end table

@item
Check that you have enough space available (@pxref{Requirements,,System
Requirements}) in @file{/usr}.  You can use @samp{df /usr} to check.

@item
Check whether there's already a @file{/usr/cygnus} directory, and
whether you can write in it.  Typing the following line checks both:

@cartouche
@example
eg$ @b{touch /usr/cygnus/test; rm /usr/cygnus/test}
@end example
@end cartouche

@noindent
@emph{If you get no errors from this line, skip the next step.}

@item
If you got ``No such file or directory'' or ``Permission denied''
errors, you need to sign on (or @code{su}) to an account that has
permission to write in @file{/usr} or in an existing @file{/usr/cygnus}
directory.  If only @code{root} has access, the best procedure is to
@code{su root} @emph{briefly}, to create a writable
@file{/usr/cygnus}---then return to your usual sign-on.  For instance:

@cartouche
@example
eg$ @b{su root}
password:           @i{enter root password}
# @b{mkdir /usr/cygnus}        @i{ignore ``File exists'' error if any}
# @b{chmod 777 /usr/cygnus}
# @b{exit}              @i{root access not needed beyond this}
eg$
@end example
@end cartouche

If you don't have access to @code{root} or to any account with
permission to write in @file{/usr} or @file{/usr/cygnus}, see @ref{No
access,,No Access to @file{/usr/cygnus}}.

@item
Load the Cygnus Support release tape (labelled ``Progressive--||RELNO||'') into
your system's tape drive.

@item
Extract the @code{Install} script (remember, @var{tape} stands for the
device name for the appropriate tape drive on your system):

@cartouche
@example
eg$ @b{cd /tmp}
eg$ @b{tar xfv /dev/@var{tape} Install}
@end example
@end cartouche

@c UPDATE! Check error messages from tar on non-Suns when supported
If you get any error messages beginning ``tar: can't open'', check that
the tape is correctly placed in your tape drive, and that you typed the
right name for @var{tape}.

It doesn't really matter where you put @code{Install}, though these
examples assume @file{/tmp}.  Don't worry about losing the script after
you've done the install; when you extract anything from the tape,
another copy of @code{Install} is saved (for future reference) in
@file{/usr/cygnus/progressive-||RELNO||}.

@quotation
@emph{If you don't want both source and binaries, stop now,} and read about
what options you can use with @code{Install} in
@ref{Install-Options,,Installation Options}.  For examples of variations
on what to install, @xref{Examples,,Installation Examples}.
@end quotation

@item
Now you can extract all the software by running @code{Install}.  Use
the @samp{-tape=} option to identify your tape drive:

@cartouche
@example
eg$ @b{/tmp/Install -tape=/dev/@var{tape}}
@end example
@end cartouche

This is a time-consuming step.  @code{Install} will begin by using
@code{tar} to extract software for your system, leaving a log in
@file{/usr/cygnus/tar.log}.  Then it prepares copies of your system
header files, converted to comply with @sc{ansi} C
(@pxref{Why-fixincludes,,Why Convert System Header Files?}); a log for
this step goes in
@file{/usr/cygnus/progressive-||RELNO||/fixincludes.log}.  @emph{Your
system's original header files are not changed;} @code{Install} writes
the converted copies in a separate, @sc{gcc}-specific directory.

As it executes, @code{Install} displays occasional messages to keep you
informed about which of these steps it's executing.  Among them, these
messages mark completion of the major stages of installation:

@cartouche
@example
Cygnus Support software distribution extracted!

Fixed include files installed!

Cygnus Support software distribution tested!

Done.
@end example
@end cartouche

@ifset HOSTrs6000
If the test step fails on a @samp{.s} file, you may not have the
correct assembler from IBM installed.  @xref{Requirements,,System
Requirements}.
@end ifset

@item
Now that the software is on your system, you need to arrange for users
to run it conveniently.  We recommend the following links; see
@ref{Links,,Links for Easy Access and Updating}, for a discussion.

@cartouche
@example
eg$ @b{cd /usr/cygnus}
eg$ @b{ln -s progressive-||RELNO|| progressive}

eg$ @b{su root}            @i{root privileges may be needed}
password:               @i{to put link in /usr}
# @b{ln -s /usr/cygnus/progressive/H-||HOSTstr|| /usr/progressive}
# exit                  @i{give up root privileges as soon as possible}
@end example
@end cartouche

@item
Finally, in case you need to send problem reports to Cygnus, we've
included a script @code{send_pr} (and a supporting online template) to
structure and transmit your reports.  Please use the
script @code{install_cid} to record your Cygnus customer ID in your copy
of the problem report form.  (You can find your customer ID in the cover
letter that came with this release; or call the Cygnus hotline, 
@w{+1 415 322 7836}.)  This will enable us to respond as quickly as
possible to any problem reports you send.

@cartouche
@example
eg$ @b{/usr/cygnus/progressive-||RELNO||/H-||HOSTstr||/bin/install@t{_}cid @var{ID}}
install_cid: `@var{ID}' is now the default customer ID
 for send_pr
@end example
@end cartouche

@item
We recommended permissions @code{777} for the @file{/usr/cygnus}
directory, to be sure you could run this procedure.  However, for the
long term, it is usually not a good idea to leave directories
world-writable (especially directories where executables come from).

For better security, remove public write access from @file{/usr/cygnus}.
See your System Administrator for the correct permissions at your site.
@end enumerate

You're done!  Anyone who puts @samp{/usr/progressive/bin} in her or his
@code{PATH} can use the Developer's Kit.

@node cross-install,  , local-install, Installing
@unnumberedsubsec Installing in @file{/usr/cygnus}, with another machine's tape drive 
This checklist is for a ||HOST|| that does not have its own tape drive,
but can share a file system with another machine that does have a tape
drive.  The other machine need not be a ||HOST||.  

Installing this way will install all the source, plus the binaries for
the ||HOST||.  If you don't want both source and binaries, stop after
extracting @code{Install} from the tape, and read about what options you
can use with @code{Install} in @ref{Install-Options,,Installation
Options}.  For examples of variations on what to install,
@xref{Examples,,Installation Examples}.

@enumerate
@item
find a machine with a suitable tape drive on the same network as your
||HOST||, and sign on to it.  If the only machine with a tape
drive isn't on the network, @pxref{No Drive,,No Local Tape Drive}.

@item
find out the name of the @emph{non-rewinding} tape device on the machine
that can read the release tape.  Cygnus release tapes are labelled to
identify the kind of tape used---either ||TAPdflt||, or Exabyte.

You should use one of the following devices on ||HOST|| (or
compatible) systems:
@table @emph
@item ||TAPdflt|| tapes
Use @file{||DEVdflt||} where the examples show @code{/dev/@var{tape}}.

@item Exabyte tapes
The device name depends on how your Exabyte tape drive was installed;
check with your system administrator.  
@ifset HOSTsun4
You will probably use one of
@file{/dev/nrst0} or @file{/dev/nrst1} where the example shows
@code{/dev/@var{tape}}.
@end ifset
@ifset HOSTsun3
You will probably use one of
@file{/dev/nrst0} or @file{/dev/nrst1} where the example shows
@code{/dev/@var{tape}}.
@end ifset
@end table

@item
Choose a directory where you will install the Developer's Kit.  The
directory must be accessible from both machines (the one with the tape
drive, and the ||HOST|| where you want to use the software)---for
example, over NFS.  Wherever this note uses @var{shr}, substitute the
name of the directory you chose.

The shared directory need not have the same name on both machines,
though we show it as @var{shr} on both, for simplicity.

@item
Check that you have enough space available (@pxref{Requirements,,System
Requirements}) in @var{shr}.  You can use @samp{df @var{shr}} to check.

@item
Check whether there's already a @file{@var{shr}/cygnus} directory,
and whether you can write in it.  Typing the following line checks both:

@cartouche
@example
eg$ @b{touch @var{shr}/cygnus/test; rm @var{shr}/cygnus/test}
@end example
@end cartouche

@noindent
@emph{If you get no errors from this line, skip the next step.}

@item
If you got ``No such file or directory'' or ``Permission denied''
errors, you need to sign on (or @code{su}) to an account that has
permission to write in @var{shr} or in an existing
@file{@var{shr}/cygnus} directory.  If only @code{root} has access,
the best procedure is to @code{su root} @emph{briefly}, and create a writable
@file{@var{shr}/cygnus}---then return to your usual sign-on.  For
instance:

@cartouche
@example
eg$ @b{su root}
password:           @i{(enter root password)}
# @b{mkdir @var{shr}/cygnus}      @i{(ignore ``File exists'' error if any)}
# @b{chmod 777 @var{shr}/cygnus}
# @b{exit}              @i{root access not needed beyond this}
eg$
@end example
@end cartouche

@item
Load the Cygnus Support release tape (labelled ``Progressive--||RELNO||'') into
the tape drive.  In these examples, @var{tape} stands for the
device name for the appropriate tape drive on your system.

@item
The first file on the tape is a script called @code{Install}.
That script automates most of the installation procedure---but first you
need to bootstrap the installation by getting @code{Install} itself from
the tape.  It doesn't really matter where you put this initial
copy of @code{Install}; it is only used to get things started---these
examples assume you put it in @file{/tmp}.  When you use this copy of
@code{Install} to extract software from the tape, another copy of
@code{Install} will be saved in
@file{@var{shr}/cygnus/progressive-||RELNO||}.  Later, you will use that
second copy to finish the installation on your ||HOST||.

These commands will get @code{Install} into the @file{/tmp} directory
(remember, @var{tape} stands for the device name for the appropriate
tape drive on your system):

@cartouche
@example
eg$ @b{cd /tmp}
eg$ @b{tar xfv /dev/@var{tape} Install}
@end example
@end cartouche

@noindent
@c UPDATE! tar error messages on other hosts?
If you get any error messages beginning with something like ``tar: can't
open'', check that the tape is correctly placed in your tape drive, and
that you typed the right name for @var{tape}.

@quotation
@emph{If you don't want both source and binaries, stop now,} and read about
what options you can use with @code{Install} in
@ref{Install-Options,,Installation Options}.  For examples of variations
on what to install, @xref{Examples,,Installation Examples}.
@end quotation

@item
Now you can extract all the software by running @samp{Install extract}.
Use the @samp{-tape=} option to identify your tape drive, and the
@w{@samp{-installdir=}} option to point to the @var{shr} directory.

@cartouche
@example
eg$ @b{cd /tmp}
eg$ @b{./Install extract -tape=/dev/@var{tape} -installdir=@var{shr}/cygnus}
@end example
@end cartouche

This is a time-consuming step.  @code{Install} will use @code{tar} to
extract software for your system, leaving a log in the file
@file{@var{shr}/cygnus/tar.log}.

When @code{Install} is done extracting the tape contents, it
displays the messages

@cartouche
@example
Cygnus Support software distribution extracted!
Done.
@end example
@end cartouche

@item
Log on to the ||HOST|| where you want to use the software.

@item
Create a symbolic link from @file{@var{shr}/cygnus/progressive-||RELNO||}
to @file{/usr/cygnus/progressive-||RELNO||} on your ||HOST||.  You may
need to become @code{root} @emph{briefly}, as in this example:

@iftex
@widen{1pc}
@end iftex
@cartouche
@example
eg-||HOSTstr||$ @b{su root}
password:
# @b{mkdir /usr/cygnus}        @i{(ignore ``File exists'' error if any)}
# @b{chmod 777 /usr/cygnus}
# @b{ln -s @var{shr}/cygnus/progressive-||RELNO|| /usr/cygnus/progressive-||RELNO||}
# exit              @i{root access not needed beyond this}
@end example
@end cartouche
@iftex
@widen{-1pc}
@end iftex

@noindent
If you don't have access to any account with permission to write in
@file{/usr}, @pxref{No access,,No Access to @file{/usr/cygnus}}.

@item
Fix up system header files on your ||HOST||, and test the installation, with
the copy of @code{Install} that was placed in
@file{@var{shr}/cygnus/progressive-||RELNO||}:

@cartouche
@example
eg-||HOSTstr||$ @b{cd /usr/cygnus/progressive-||RELNO||}
eg-||HOSTstr||$ @b{./Install @b{f}ixincludes test}
@end example
@end cartouche

@noindent
A log for the @code{fixincludes} step goes in
@file{/usr/cygnus/progressive-||RELNO||/fixincludes.log}.  @emph{Your
system's original header files are not changed;} @code{Install} writes
the converted copies in a separate, @sc{gcc}-specific directory.

When each stage of this work is complete, @code{Install} displays these
messages (the last, @samp{Done.}, simply indicates that @code{Install}
has finished executing).

@cartouche
@example
Fixed include files installed!

Cygnus Support software distribution tested!

Done.
@end example
@end cartouche

@ifset HOSTrs6000
If the test step fails on a @samp{.s} file, you may not have the
correct assembler from IBM installed.  @xref{Requirements,,System
Requirements}.
@end ifset

@item
Now that the software is on your system, you need to arrange for users
to run it conveniently.  We recommend the following links; see
@ref{Links,,Links for Easy Access and Updating}, for a discussion.

@cartouche
@example
eg-||HOSTstr||$ @b{cd /usr/cygnus}
eg-||HOSTstr||$ @b{ln -s progressive-||RELNO|| progressive}

eg-||HOSTstr||$ @b{su root}      @i{root privileges may be needed}
password:               @i{to put link in /usr}
# @b{ln -s /usr/cygnus/progressive/H-||HOSTstr|| /usr/progressive}
# exit                  @i{give up root privileges as soon as possible}
@end example
@end cartouche

@item
Finally, in case you need to send problem reports to Cygnus, we've
included a script @code{send_pr} (and a supporting online form) to
structure and transmit your reports.  Please use the
script @code{install_cid} to record your Cygnus customer ID in your copy
of the problem report form.  (You can find your customer ID in the cover
letter that came with this release; or call the Cygnus hotline, 
@w{+1 415 322 7836}.)  This will enable us to respond as quickly as
possible to any problem reports you send.

@cartouche
@example
eg$ @b{/usr/cygnus/progressive-||RELNO||/H-||HOSTstr||/bin/install@t{_}cid @var{ID}}
install_cid: `@var{ID}' is now the default customer ID
 for send_pr
@end example
@end cartouche

@item
We recommended permissions @code{777} for the @file{/usr/cygnus} and
@file{@var{shr}/cygnus} directories, to make sure you could run this
procedure.  However, for the long term, it is usually not a good idea to
leave directories world-writable (especially directories where
executables come from).

For better security, remove public write access from @file{/usr/cygnus}
and @file{@var{shr}/cygnus}.  See your System Administrator for the
correct permissions at your site.
@end enumerate

You're done!  Anyone who puts @samp{/usr/progressive/bin} in her or his
@code{PATH} can use the Developer's Kit.

@node Examples, Install-Options, Installing, Top
@unnumbered Installation Examples

Once you've extracted @code{Install} from your tape,
you can tell @code{Install} what software to install, what form of the
programs you need, and what installation steps to do.  Here are some
examples covering common situations.  For a full explanation of each
possible @code{Install} argument, @pxref{Install-Options,,Installation
Options}.

@code{Install}'s default tape drive is @code{||DEVdflt||}, which is
right for the most common cases (||TAPdflt|| tapes, read on ||HOST||
systems).  If your tape drive is different, you need to use the
@samp{-tape=/dev/@var{tape}} option; the examples show this option
for completeness.  Remember to specify a @emph{non-rewinding} tape
device.

@menu
* binaries::                    Installing binaries only
* ||HOSTstr||-remote::          Reading tape on any machine, finishing on ||HOST||
* source-remove::               Removing Source
@end menu

@node binaries, ||HOSTstr||-remote, Examples, Examples
@unnumberedsubsec Installing binaries only
@ignore
@c ignore til UPDATE fulfilled for all hosts.
For this example, we assume you've got the release on an Exabyte tape,
and that your ||HOST|| reads Exabytes with 
@samp{/dev/nrst1}.
@c UPDATE! exabyes on non-Sun hosts?
@end ignore

@cartouche
@example
@c eg$ @b{./Install -tape=/dev/nrst1 bin}
eg$ @b{./Install -tape=/dev/@var{tape} bin}
@end example
@end cartouche

If you don't want the source---for instance, to save space---you can use
the argument @samp{bin}.

@node ||HOSTstr||-remote, source-remove, binaries, Examples
@unnumberedsubsec Reading tape on any machine, finishing on ||HOST||

@cartouche
@example
@emph{On a machine on your network with a tape drive:}
eg-tp$ @b{./Install -tape=/dev/@var{tape} -installdir=@var{shr}/cygnus extract}

@emph{On your ||HOST||}
eg$ @b{ln -s @var{shr}/cygnus /usr/cygnus}
eg$ @b{cd /usr/cygnus/progressive-||RELNO||}
eg$ @b{./Install @b{f}ixincludes test}
@end example
@end cartouche

@noindent
If your ||HOST|| doesn't have a tape drive, but another machine that can
mount some shared directory @var{shr} does have one, you can carry out
the first step of the installation from the machine with a tape drive,
as shown.  Note that you have to say @samp{extract} on the
@code{Install} command line.  This alerts @code{Install} to stop the
install procedure after it reads the tape.  You still have to finish the
installation, but the last two steps have to run on your ||HOST||.  (If
you forget, there's no great harm done: @code{Install} will notice that
it can't carry out a full installation on the wrong machine, and will
stop with an error message---then you can go back and try again.  When
@code{Install} notices a problem like this, it doesn't carry out
@emph{any} action other than giving a helpful error message).

The @samp{fixincludes} part of the installation is essential.  Please
see the full explanation (@pxref{Why-fixincludes,,Why Convert System
Header Files?}), if you're curious.

@node source-remove,  , ||HOSTstr||-remote, Examples
@unnumberedsubsec Removing Source
The @code{Install} script can remove anything it can install.  For
example, if after installing the complete Developer's Kit on your
machine you decide to remove the source files:

@cartouche
@example
eg$ @b{cd /usr/cygnus/progressive-||RELNO||}
eg$ @b{./Install remove source}
@end example
@end cartouche

@noindent
In general, to remove a part of the Developer's Kit, use the same
@code{Install} command line that would extract that part, but add the
keyword @code{remove}.  The @code{-tape} option is not necessary for
removing.

@node Install-Options, Links, Examples, Top
@unnumbered Installation Options

There are two kinds of command-line arguments to @code{Install}, which
you can use to direct its operation:
@itemize @bullet
@item
@emph{What form of the programs} to install.  You can choose among ||HOST||
binaries (argument @code{bin}) and source code (@code{source}).
If you don't specify either of these, @code{Install} assumes you want
both source, and binaries for ||HOST||.

@item
@emph{What installation actions} to carry out.  A full installation
involves up to three steps, and @code{Install} has options to let you
choose them explicitly.  The steps are
@enumerate
@item
extracting source from the tape (option
@code{extract})
@item
writing @sc{ansi}-C conforming copies of your system include files (needed
for the compilation tools; option @code{fixincludes})
@item
running a simple test of the installed programs
(option @code{test})
@end enumerate

The last two of these actions (@code{fixincludes} and
@code{test}) can only run on your ||HOST||.  If you read the
tape on another machine, you must specify the @code{extract} option
explicitly, to indicate that you don't expect the other two actions to
run (and are aware of the need to run further installation steps on your
||HOST||).
@end itemize

@code{Install} also has two command line options: @samp{-tape}
and @w{@samp{-installdir}}.  You can use these to adapt the
installation to your system.

Here is a summary of all of @code{Install}'s command-line options,
followed by a more detailed explanation of each:

@example
Install @r{[} -tape=/dev/@var{tape} @r{]}
       @r{[} -installdir=@var{directory} @r{]}
       @r{[} bin @r{]} @r{[} source @r{]}
       @r{[} extract @r{]} @r{[} fixincludes @r{]} @r{[} test @r{]}
       @r{[} remove @r{]}
@end example

@table @code
@item -tape=/dev/@var{tape}
@itemx -tape=@var{tarfile}
Specify the @emph{non-rewinding} device name for your tape drive as
@var{tape}.

If you extract the installation script and tarfile on some other system,
and transfer them to your ||HOST|| for installation, use use the name of
the tarfile instead of a device name with @samp{-tape}.  @xref{No
Drive,,No Local Tape Drive}, for more discussion.

@item -installdir=@var{directory}
If you have no write access to @samp{/usr/cygnus} or @samp{/usr}, use
this option to specify an alternate @var{directory} for placing your
software---but beware: the software is configured to go in
@samp{/usr/cygnus}, and you'll have to override or change that too.
@xref{Paths,,Changing the Paths}.

@item bin
@itemx source
By default, @code{Install} extracts both source, and binaries for your
||HOST||.  Instead of relying on the default, you 
can use these options to say exactly what forms you
want.  You need to do this if
@itemize @bullet
@item 
you want only binaries, or
@item
you want only source.
@end itemize

@noindent
@code{Install} is designed to share files, wherever
possible, between installations for different hosts (of the same
release).  If you get Cygnus release tapes configured for different
hosts, there is no need to do a binary-only install of some of the
tapes to save space on a shared file system; @code{Install} arranges the
files so that all hosts will share the same source
files.  Documentation files are shared as well.
See @ref{Links,,Links for Easy Access and Updating}, for a
discussion of how to manage the directory structure used for this
purpose. 

@item extract
@item fixincludes
@item test
A full installation includes up to three things: (1) extracting
software from the tape; (2) creating @sc{ansi}-C conforming copies of your
system's standard header files; and (3) testing the installation.
You can execute these steps separately by specifying
@samp{extract}, @samp{fixincludes}, or @samp{test} on the
@code{Install} command line.  

After you run @samp{extract}, @samp{fixincludes} is essential if you're
using the compiler.  @samp{fixincludes} @emph{does not change your
system's original header files;} @code{Install} writes the converted
copies in a separate, @sc{gcc}-specific directory.
@xref{Why-fixincludes,,Why Convert System Header Files?}, for more
discussion of the @samp{fixincludes} step.  @code{Install} will only
attempt these last two steps if you run it on the ||HOST||.

@samp{test} is a confidence-building step, and doesn't
actually change the state of the installed software.  The
@samp{test} step may not make sense, depending on what
other options you've specified---if you install only source, there's
nothing to test.

If you specify a step that doesn't make sense, or if you run @code{Install}
on a different machine but try to run @code{fixincludes} or
@code{test}, @code{Install} will notice the error, and exit
(before doing anything at all) with an error message, so you can try
again.

When you run @samp{extract}, @code{Install} leaves a log file
@file{tar.log} in the installation directory---by default, in @file{/usr/cygnus}.  When you run @samp{fixincludes},
@code{Install} leaves a log file @file{fixincludes.log} in the
@file{progressive-||RELNO||} subdirectory.

@item remove
You can also use @code{Install} to remove parts of the release after
you've installed them.  Identify what to remove with either of the
command-line options @samp{source} or @samp{bin}; if you specify
@samp{remove} as well, @code{Install} will try to erase parts of the
installation from your system.  @xref{Removing,,Removing Parts of the Developer's
Kit}, for an example.
@end table

@menu
* Why-fixincludes::             Why Convert System Header Files?
@end menu

@node Why-fixincludes,  , Install-Options, Install-Options
@unnumberedsec Why Convert System Header Files?

@c UPDATE! Is this really needed on @emph{all} hosts?
It is very important to run @samp{Install fixincludes} (on @emph{each
host} where you install the compiler binaries).  

When the @sc{ansi x3j11} committee finished developing a standard for
the C language, a few things that had worked one way in many traditional
C compilers ended up working differently in @sc{ansi} C.  Most of these
changes are improvements.  But some Unix header files still rely on the
old C meanings, in cases where the Unix vendor has not yet converted to
using an @sc{ansi} C compiler for the operating system itself.
@samp{Install fixincludes} does a mechanical translation that writes
@sc{ansi} C versions of some system header files into a new,
@sc{gcc}-specific include directory---@emph{your system's original
header files are not affected.}

If you don't run @code{fixincludes}, the GNU C compiler can only use the
original system header files when you compile new C programs.  @emph{In
some cases, the resulting programs will fail at run-time}.

@node Links, Running, Install-Options, Top
@unnumbered Links for Easy Access and Updating
Once you've extracted them from the tape, the tools are installed under
a directory named @file{progressive-||RELNO||}.  We put the release
number in the directory name so that you can
keep several releases installed at the same time, if you wish.  In order
to simplify administrative procedures (such as upgrades to future Cygnus
Progressive releases), we recommend that you establish a symbolic link
@file{/usr/cygnus/progressive} to this directory.  For example, assuming
you've used the default installation path:

@cartouche
@example
eg$ @b{cd /usr/cygnus}
eg$ @b{ln -s progressive-||RELNO|| progressive}
@end example
@end cartouche

Directories of host-independent files (source and documentation) are
installed directly under @file{progressive-||RELNO||}.  However, to
accomodate binaries for multiple hosts in a single directory structure,
the binary files for your ||HOST|| are in a subdirectory
@file{H-||HOSTstr||}. 

This means that one more level of symbolic links is helpful, to allow
your users to keep the same execution path defined even if they
sometimes use ||HOST|| binaries and sometimes binaries for another
machine.  Even if this doesn't apply now, you might want it in the
future; establishing these links now can save your users the trouble of
changing all their paths later.  The idea is to build
@samp{/usr/progressive/bin} on each machine so that it points to the
appropriate binary subdirectory for each machine---for instance,
@samp{/usr/cygnus/progressive/H-||HOSTstr||}.

You may need to use @code{su} again briefly to establish these links:

@cartouche
@example
eg$ @b{ln -s /usr/cygnus/progressive/H-||HOSTstr|| /usr/progressive}
@end example
@end cartouche

We recommend building these links as the very last step in the
installation process.  That way, users at your site will only see
software in @file{/usr/progressive} when you're satisfied that the
installation is complete and successful.

@menu
* Running::                     Running the Programs
@end menu

@node Running, Paths, Links, Top
@unnumbered Running the Programs
Any users who wish to run the Cygnus development tools will need to make
sure the @code{PATH} environment variable will find them.  If you create
the symbolic links we recommend above, users who want to run the
Developer's Kit---regardless of whether they need binaries for ||HOST||,
or for some other platform---can use settings like one of the following
in their initialization files.

@example
@exdent For shells compatible with Bourne shell (@code{/bin/sh}, @code{bash}, or Korn shell):
@cartouche
@b{PATH=/usr/progressive/bin:$PATH}
@b{export PATH}
@end cartouche
@end example

@example
@exdent For C shell:
@cartouche
@b{set path=(/usr/progressive/bin $path)}
@end cartouche
@end example

@noindent
You should also ensure that your @code{man} command can pick up the
manual pages for these tools.  Some @code{man} programs recognize a
@code{MANPATH} environment variable.  If your @code{man} program is one
of these, users at your site can also include in their initialization
file lines like 

@example
@exdent For Bourne-compatible shells:
@cartouche
@b{MANPATH=/usr/cygnus/progressive/man:$MANPATH:/usr/man}
@b{export MANPATH}
@end cartouche
@end example

@example
@exdent For C shell:
@cartouche
@b{setenv MANPATH /usr/cygnus/progressive/man:$MANPATH:/usr/man}
@end cartouche
@end example

If your @code{man} program doesn't recognize @samp{MANPATH}, you may
want to copy or link the files from
@file{progressive/man/man1} into your system's
@file{man/man1}. @refill

@node Paths, Trouble, Running, Top
@unnumbered Changing the Paths
The binaries shipped by Cygnus are configured for installation under the
directory @file{/usr/cygnus}.  In particular, @code{gcc}, @code{g++},
and the documentation browser @code{info} need to know the location of
the distribution.  

If you wish to run the tools after installing them in another location,
you can either:
@itemize @bullet
@item
use environment variables (and, for @code{g++}, command-line options)
to tell the tools where to find pieces of the installation; or

@item
rebuild the tools from source, with your preferred paths built in.
@xref{Rebuilding,,Rebuilding from Source}, if you want to take this
approach.
@end itemize

In rare circumstances, the auxiliary installation script
@code{install_cid} will also require a workaround if you do not install
in @file{/usr/cygnus}.

@subheading GCC Paths
@c FIXME! Add something about specs file?
You can run the compiler @sc{gcc} without recompiling, even if you
install the distribution in an alternate location, by first setting the
environment variable @samp{GCC_EXEC_PREFIX}.  This variable specifies
where to find the executables, libraries, and data files used by the
compiler.  Its value will be different depending on which set of
binaries you need to run.  For example, if you install the tape
distribution under @file{/local} (instead of the default
@file{/usr/cygnus}), and you wish to run @sc{gcc} as a native ||HOST||
compiler, you could set @samp{GCC_EXEC_PREFIX} as follows.  (You can
type the first two lines as a single line, if you like; the example
is split using the line continuation character @samp{\} only
to make it fit on the printed page.)

@cartouche
@example
@b{GCC@t{_}EXEC@t{_}PREFIX=/local/progressive-||RELNO||/H-||HOSTstr||/@t{\}
lib/gcc-lib/||TARGET||/||GCCvn||/}
@b{export GCC@t{_}EXEC@t{_}PREFIX}
@end example
@end cartouche

@noindent
The example assumes you use a shell compatible with the Bourne shell; if
you run the C shell, use the following instead.  (Again, the line
continuation character @samp{\} is only used for convenience in the
example; feel free to use a single line.)

@cartouche
@example
@b{setenv GCC@t{_}EXEC@t{_}PREFIX /local/progressive-||RELNO||/H-||HOSTstr||/@t{\}
lib/gcc-lib/||TARGET||/||GCCvn||/}
@end example
@end cartouche

@quotation
@emph{Warning: The trailing slash @samp{/} is important}.  The @code{gcc}
program uses @samp{GCC_EXEC_PREFIX} simply as a prefix.  If you omit the
slash (or make any other mistakes in specifying the prefix), @code{gcc}
will fail with a message beginning @samp{installation problem, cannot
exec@dots{}}.
@end quotation

@subheading G++ Paths
To compile C++ programs (when you've installed the binaries for the
compiler somewhere other than @file{/usr/cygnus}), you need to set
@code{GCC_EXEC_PREFIX} as for C programs.  You @emph{also} need to include
a @samp{-L} option and a @samp{-I} option on the @code{g++} command
line, to locate the @sc{g++} specific header files and library.  For example,
assuming you installed the ||HOST|| binaries under @file{/local}, and
want to compile a C++ program @samp{program.cc}:

@enumerate
@item
Set @code{GCC_EXEC_PREFIX} in one of the ways shown above;

@item
Invoke the @code{g++} compiler with at least the following options:
@end enumerate
@cartouche
@example
eg$ @b{g++ -L/local/progressive-||RELNO||/H-||HOSTstr||/lib@t{\}
-I/local/progressive-||RELNO||/H-||HOSTstr||/lib/g++-include program.cc}
@end example
@end cartouche

@subheading @code{info} Paths
The standalone documentation browser @code{info} also needs to know the
location of its documentation files in the distribution.   The default
location, @file{/usr/cygnus/progressive-||RELNO||/info}, is compiled in.
If you install elsewhere, set the environment variable @code{INFOPATH}
to indicate the alternate location.

For example, again assuming you installed under @file{/local}:

@example
@exdent For shells compatible with Bourne shell (@code{/bin/sh}, @code{bash}, or Korn shell):
@cartouche
@b{INFOPATH=/local/progressive-||RELNO||/info}
@b{export INFOPATH}
@end cartouche
@end example

@example
@exdent For C shell:
@cartouche
@b{setenv INFOPATH /local/progressive-||RELNO||/info}
@end cartouche
@end example

@noindent
If you built @file{progressive} as a symbolic link to
@file{progressive-||RELNO||}, as recommended in @ref{Links,,Links for
Easy Access and Updating}, then you could simply use
@file{/local/progressive/info} as the value of @code{INFOPATH} in the
examples above.

@subheading @code{install_cid} Paths
The auxiliary script @code{install_cid} is provided as a convenience, to
fill in your site's customer ID as the default for your local version of
the Cygnus @code{send_pr} problem-reporting script.

If you don't install in @file{/usr/cygnus}, @samp{install_cid
@var{ID}} will still work correctly in most cases.  However,
there is one situation where @code{install_cid} fails:

@itemize @bullet
@item
@emph{if} your site already has a release tree for
@samp{/usr/cygnus/progressive-||RELNO||}, 
@item
@emph{and} you run @code{Install} with an alternative installation
directory.
@end itemize

@noindent
In this case, you must manually edit your customer ID into your site's
copy of @code{send_pr}.  Please call the Cygnus hotline, 
@w{+1 415 322 7836}, if you have any trouble with this.

@node Trouble, Rebuilding, Paths, Top
@unnumbered Some Things that Might go Wrong

We've tried to make the installation of your Developer's Kit as painless
as possible.  Still, some complications may arise.  Here are suggestions
for dealing with some of them.

@menu
* No Drive::                    No Local Tape Drive
* Limited Space::               Not Enough Space
* No access::                   No Access to @file{/usr/cygnus}
* Install errors::              Error Messages from @code{Install}
@end menu

@node No Drive, Limited Space, Trouble, Trouble
@unnumberedsec No Local Tape Drive
If your ||HOST|| doesn't have an appropriate tape drive, you may
still be able to install your software.  Check with your system
administrator to see if another machine at your site has a tape drive
you can use.  If so:
@table @emph
@item If a shared filesystem is available
between the two machines, and it has enough space, create
@samp{/usr/cygnus} on your ||HOST|| (the one where you want to install
this Progressive Release) as a symbolic link to a directory where the
other machine (the one with a tape drive) can write.  Then go ahead and
run @code{Install} from the machine with a tape drive.  You'll have to
run @samp{Install fixincludes} and @samp{Install test} from your
||HOST|| afterwards; @pxref{cross-install,,Installing with another
machine's tape drive}.

@item If some form of filetransfer is available 
(such as @code{uucp}), read the tape using a system utility (for
instance, @code{dd} on Unix systems; see the system documentation for
the machine with a tape drive).  There are two files on the
distribution tape; the first contains just the @code{Install} script,
and the second is a compressed @code{tar} format file containing the
rest of the release.  Read both of these files, and transfer them to
your own machine.  Then run @code{Install} as shown in
@ref{local-install,,Installing with a local tape drive}, but use
@samp{-tape=@var{tarfile}} to specify the name of the installation
file, instead of @samp{-tape=/dev/@var{tape}} as shown in the
examples.  In the simplest case, for example (starting after you've
transferred @code{Install} and the tar file to your system):

@cartouche
@example
eg$ @b{./Install -tape=@var{tarfile}}
@end example
@end cartouche

@end table

@node Limited Space, No access, No Drive, Trouble
@unnumberedsec Not Enough Space
If you don't have enough space to install all of the tape
distribution, you can instead extract only the compiled code, or only
the source.

The following table summarizes the approximate space (rounded up to the
next megabyte) needed for source and binaries.
There is a little overlap between the partial installations: the
documentation, and documentation tools, are always installed.

@table @r
@item ||BD|| MB
||HOST|| binaries

@item ||SD|| MB
source code for all programs

@item ||DF|| MB
||HOST|| total
@end table

You can easily extract these components independently of one another, by
using the @samp{source} or @samp{bin} arguments to the @code{Install}
script provided on your release tape.
@xref{Install-Options,,Installation Options}.

@node No access, Install errors, Limited Space, Trouble
@unnumberedsec No Access to @file{/usr/cygnus}

If you can't sign on to an account with access to write in @file{/usr}
or @file{/usr/cygnus}, use the @samp{-installdir=@var{directory}} option
to @code{Install} to specify a different installation directory, where
you @emph{can} write.  For example, if all the other installation
defaults are right, you can execute something like @samp{./Install
-tape=/dev/@var{tape} -installdir=@var{mydir}}.  You'll need to either
override default paths for the pre-compiled tools, or else recompile the
software.

@quotation
@emph{WARNING:} If you can't install in @file{/usr/cygnus} (or link your
installation directory to that name), some of the defaults configured
into the Progressive--||RELNO|| distribution won't work.
@xref{Paths,,Changing the Paths}, for information on overriding or
reconfiguring these defaults.
@end quotation

@node Install errors,  , No access, Trouble
@unnumberedsec Error Messages from @code{Install}
The @code{Install} script checks for many errors and inconsistencies in
the way its arguments are used.  The messages are meant to be
self-explanatory.  Here is a list of a few messages where further
information might be useful:
@table @code
@item Cannot read from TAPE device, @var{tape}
The error message ends with the tape device @code{Install} was trying to
use.  Please check that it is the device you intended; possible causes of
trouble might include leaving off the @samp{/dev/} prefix at the front
of the device name.  A typo in the device name might also cause this
problem.  

If the problem is neither of these things, perhaps your tape device can't
read our tape; @pxref{No Drive,,No Local Tape Drive}, for a discussion
of how to use another machine's tape drive.

@item @dots{} This is a problem.
@itemx Cannot cd to @var{installdir}
@itemx I do not know why I cannot create @var{installdir}
@itemx hello.c fails to run
@itemx test-ioctl.c fails to run
@itemx I do not know how to remove an arch called @dots{}
These errors (the first covers anything that ends in @samp{This is a
problem}) are from paranoia checks; they are issued for situations that
other checks should have covered, or for unlikely situations that
require further diagnosis.  

If you get one of these messages, please 
@itemize @bullet
@item
@strong{call the Cygnus hotline, +1 415 322 7836}, or 
@item
send electronic mail to @samp{help@@cygnus.com}. 
@end itemize
@end table

@node Rebuilding, Removing, Trouble, Top
@unnumbered Rebuilding From Source

All Cygnus products are free software; your Developer's Kit includes
complete source code for all programs.

Cygnus Support has implemented an automatic configuration scheme to
adapt the programs to different environments.

Rebuilding the programs from source requires these steps:
@enumerate
@item
configuration
@item
compilation
@item
installation
@end enumerate

For example, executing the following commands in sequence will rebuild
and install a ||HOST|| native version of all the tools in a nonstandard
directory:

@cartouche
@example
eg$ @b{cd progressive-||RELNO||/src}

eg$ @b{./configure ||HOSTstr|| -prefix=/local/gnu}
Created "Makefile" in @var{installdir}/progressive-||RELNO||/src

eg$ @b{make clean all info install install-info >make.log}
@dots{} @i{output for @code{make} steps follows}
@end example
@end cartouche

@noindent
We discuss each step in detail in the following sections.

@menu
* Configuration::               Configuration
* Config Names::                Specifying Names for Hosts and Targets
* configure Options::           @code{configure} Options
* Compilation::                 Compilation
* Installation::                Installation
@end menu

@node Configuration, Config Names, Rebuilding, Rebuilding
@unnumberedsec Configuration

You can configure the software in this release by using the shell
script called @code{configure}.  The shell script requires one argument:
the host type.  There are also several possible options, including a
@samp{-target=} option to configure for cross-system development.

@node Config Names, configure Options, Configuration, Rebuilding
@section Specifying Names for Hosts and Targets

The specifications used for hosts and targets in the @code{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:

@example
@var{architecture}-@var{vendor}-@var{os}
@end example

For example, you can use the alias @code{sun4} as a @var{host} argument
or in a @samp{-target=@var{target}} option, but the equivalent full name
is @samp{sparc-sun-sunos4}.

@quotation
@emph{Warning:} @code{configure} can represent a very large number of
combinations of architecture, vendor, and OS.  There is by no means
support for all possible combinations!
@end quotation

@node configure Options, Compilation, Config Names, Rebuilding
@section @code{configure} Options

This section summarizes the @code{configure} options and arguments.
Your Developer's Kit contains full online documentation for the Cygnus
configure system.  @inforef{Using Configure,,configure.info}, to read
about @code{configure} in more detail, including information on how the
@code{configure} options relate to @file{Makefile} variables.

@example
configure @r{[}-prefix=@var{dest}@r{]} 
          @r{[}-exec-prefix=@var{bindest}@r{]} 
          @r{[}-srcdir=@var{path}@r{]}
          @r{[}-norecursion@r{]} 
          @r{[}-target=@var{target}@r{]}
          @var{host}
@end example

@noindent
The binaries on your tape were configured using

@cartouche
@example
configure -prefix /usr/cygnus/progressive-||RELNO|| \
  -exec-prefix /usr/cygnus/progressive-||RELNO||/H-||HOSTstr|| \
  ||HOSTstr||
@end example
@end cartouche

@table @code
@item -prefix=@var{dest}
@var{dest} is an installation directory @emph{path prefix}, the root for
the directories where @code{make install} will place things.  After you
configure with this option, @samp{make install install-info} will
install info files in @file{@var{dest}/info}, man pages in
@file{@var{dest}/man}, and---unless you also use
@samp{-exec-prefix}---compiled programs in @file{@var{dest}/bin}, and
libraries in @file{@var{dest}/lib}.  If you specify
@samp{-prefix=/local}, for example, @code{make install} puts the
development tools in @file{/local/bin}.

@emph{WARNING:} the default @var{dest} path prefix in the source is not
the same as the prefix for the preconfigured binaries distributed by Cygnus.

@samp{-prefix=/usr/cygnus/progressive-||RELNO||} was used to build this
Cygnus Progressive Release.  If you do not use @code{-prefix}, the
installation directory is @file{/usr/local}.

@item -exec-prefix=@var{bindest}
@samp{-exec-prefix} serves the same purpose as @samp{-prefix}, but
affects only machine-dependent targets (compiled programs and
libraries).  Specifying both @samp{-prefix} and @samp{-exec-prefix}
allows you to segregate machine-dependent files, so that
machine-independent files can be shared.  

@emph{WARNING:} the default @var{bindest} path prefix in the source is not
the same as the prefix for the preconfigured binaries distributed by Cygnus.

@samp{-exec-prefix=/usr/cygnus/progressive-||RELNO||/H-||HOSTstr||} was
used to build this Cygnus Progressive Release.
If you do not use @samp{-exec-prefix}, the default directory for
machine-dependent targets is whatever was specified with @file{-prefix}
(by default, @file{/usr/local}).

@item -srcdir=@var{path}
@emph{Warning: This option is only supported if you use @sc{gnu}
@code{make}} (which is included in the Cygnus Progressive--||RELNO|| release).
Use this option to make configurations in directories separate from the
source directories. @code{configure} writes configuration specific files
in the current directory, but arranges for them to use the source in the
directory @var{path}.  @code{configure} will create directories under
the working directory in parallel to the source directories below
@var{path}.  Among other things, you can use this to build (or maintain)
several configurations simultaneously, in separate directories.

@item -norecursion
Configure only the directory level where @code{configure} is executed; do not
propagate configuration to subdirectories.

@item -target=@var{target}
Configure the development tools for cross-development (compiling,
debugging, or other processing) of programs running on the specified
@var{target}.  Without this option, programs are configured ``native'',
that is, for managing programs that run on the same machine (@var{host})
as the development tools themselves.

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

@item @var{host} @dots{}
Configure the development tools to run on the specified @var{host}.

There is no convenient way to generate a list of all available hosts.
@end table

The @samp{-prefix=@var{dest}} and @samp{-exec-prefix=@var{bindest}}
options are particularly important.  If you don't specify a @var{dest}
or @var{bindest} directory, the @file{Makefile} installs binaries in
subdirectories of @file{/usr/local}.  These options are important
because the @var{dest} and @var{bindest} directories are used for
several purposes:

@enumerate
@item
@var{bindest} is the directory where binaries are installed.

@item
@var{bindest} is built into the compiler itself for the
locations of @sc{gcc} specific include files, the locations of @sc{gcc}
subprograms, and the location of the @sc{gcc} specific library
@file{libgcc.a}.

@item
@var{dest} is compiled into @code{info} as the default directory
for the documentation.

@end enumerate

@node Compilation, Installation, configure Options, Rebuilding
@unnumberedsec Compilation

After you've run @code{configure} (which writes the final
@file{Makefile} in each directory), compilation is straightforward.
To compile all the programs in the Developer's Kit, run:

@cartouche
@example
@b{make all info >make.log}
@end example
@end cartouche

The examples suggest capturing the @code{make} output in a
@file{make.log} file, because the output is lengthy.  

The overall @file{Makefile} propagates the value of the @code{CC}
variable explicitly, so that you can easily control the compiler used in
this step.  @code{CFLAGS} is treated the same way.  For instance, to
build the compiler a second time, using @sc{gcc} to compile itself
(after building and installing it in the alternate directory
@file{/local/gnu}), you might use

@cartouche
@example
@b{make CC=/local/gnu/H-sun4/bin/gcc CFLAGS=-O all info  >make.log}
@end example
@end cartouche

The conventional targets @samp{all}, @samp{install}, and @samp{clean}
are supported at all levels of @file{Makefile}.  Other targets are
supported as well, as appropriate in each directory; please read the
individual @file{Makefile} for details.  Each @file{Makefile} in the
source directories includes ample comments to help you read it.  If you
are not familiar with @code{make}, refer to @ref{Overview,,Overview of
@code{make}, make.info, GNU Make: A Program for Directing
Recompilation}.

@node Installation,  , Compilation, Rebuilding
@unnumberedsec Installation

Whether you configure an alternative path using @code{-prefix}, or you
use the default installation path @file{/usr/local}, you can install the
software by executing:

@cartouche
@example
@b{make install install-info}
@end example
@end cartouche

@node Removing, Cygnus-FSF, Rebuilding, Top
@unnumbered Removing Parts of the Developer's Kit
You can use the same @code{Install} script that was used to install the
Developer's Kit on your system, to remove parts of the release.
(Remember that the @code{Install} script was automatically saved for you
as @file{/usr/cygnus/progressive-||RELNO||/Install}.)

To do this, decide what you want to remove; then call @code{Install}
with the option @samp{remove} on the command line, as well as all the
options that you would use to install that portion of the release
(@pxref{Install-Options,,Installation Options}).  For example, suppose
you never look at the source, and are running short of disk
space; you can remove the source, while leaving the rest of
the Progressive Release undisturbed, as follows:

@cartouche
@example
eg$ @b{cd /usr/cygnus/progressive-||RELNO||}
eg$ @b{./Install remove source}
@end example
@end cartouche

@noindent
You should see the following messages confirming the software was
removed:

@cartouche
@example
Cygnus Support software distribution removed!
Done.
@end example
@end cartouche

To remove the complete Progressive Release of the Developer's Kit from your system
(if, eventually, you no longer want it), delete the directory
@file{/usr/cygnus/progressive-||RELNO||} and all its contents.  

@node Cygnus-FSF, Cygnus-Support, Removing, Top
@unnumbered Cygnus Releases and the FSF

Most of the tools in this Developer's Kit are originally from the Free
Software Foundation (FSF).  You can get versions of all these tools
from the FSF as well as from Cygnus.  In general, Cygnus Progressive
Releases add to FSF software in the following ways:
@c UPDATE! more differences bet Cygnus/FSF releases?

@itemize @bullet
@item
Commercial support is available.  Cygnus adds value to FSF releases in
large measure by offering outstanding support services.
@item
Coordination.  The tools in your Developer's Kit are certified to work
together; you need not worry about tools being out of step with each other.
@item
Bug fixes.  A Progressive Release includes many fixes, already integrated
into the programs.  Cygnus repairs bugs discovered during testing, and
also tracks and includes bug fixes developed for other Cygnus customers
or distributed over the Internet.
@item
Bug reporting.  Cygnus releases include the tool @code{send_pr}, which
you can use to make sure your problem reports receive prompt attention,
and are also incorporated in our future tests.
@item
Documentation.  Cygnus revises and adds to available FSF
documentation to give you better descriptions of all the software tools.
@item
Stability.  Cygnus tests (and uses) all the programs it releases.
@end itemize

@c FIXME! If we can say something about this, remove @ignore/@end ignore
@c        and fill in below:
@ignore
This particular Cygnus Progressive release differs from the nearest
corresponding FSF distributions in these important details:

FILL IN HERE!

@end ignore

@node Cygnus-Support,  , Cygnus-FSF, Top
@unnumbered About Cygnus Support

Cygnus Support was founded in 1989 to provide commercial support for
free software.  Cygnus supplies products and services that benefit
advanced development groups by allowing them to use state-of-the-art
tools without having to maintain them.  With Cygnus Support, sites that
once were forced to do their own tool support can recover that valuable
staff time.  Former users of proprietary software now may choose
supported free software, combining the advantages of both worlds.

Free software is faster, more powerful, and more portable than its
proprietary counterparts.  It evolves faster because users who want to
make improvements are free to do so.  Cygnus tracks these
improvements and integrates them into tested, stable versions ready
for commercial use, then backs this software with comprehensive
support.

With Cygnus Support as your partner, you will have the software and
the support you need to meet your business objectives.  Cygnus
is intimately familiar with this software from extensive experience
using, debugging, and implementing it.  You get direct access to the
most qualified support people: the authors of the software.

We provide ``vintage'' releases---the most stable versions, which have
been though even more extensive use and testing---or up-to-the minute
``progressive'' releases, for those who need the very latest version.

Because all our improvements are also free software, you can
distribute them widely within your organization, or to your customers,
without extra cost.

@sp 4

@display
Cygnus Support
814 University Avenue
Palo Alto, CA 94301, USA

+1 415 322 3811
hotline: +1 415 322 7836
email: @code{info@@cygnus.com}
fax: +1 415 322 3270
@end display

@bye