Document damage^H^H^H^H^H^Hwork done so far tonight.

[binutils.git] / sol-inst.texi

\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 [email protected])
@setfilename INSTALL-NOTES
@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 Solaris-2 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
@c set exactly ONE of the following to select what kind of install to doc:
@clear CDROMinst
@clear TAPEinst
@set FTPsingle
@clear FTPsplit
@c
@c shared properties:
@clear FTP
@clear FTPorCD
@ifset FTPsingle
@set FTP
@set FTPorCD
@end ifset
@ifset FTPsplit
@set FTP
@set FTPorCD
@end ifset
@ifset CDROMinst
@set FTPorCD
@end ifset
@c
@c set CUSTOMER to indicate install instructions are for a Cygnus customer
@c (clear for general public)
@set CUSTOMER
@c
@iftex
@c The include file "texiplus.tex" is in the src/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 Release ||RELNO|| for Solaris 2
@tex
% override-override: the following \font lines are redundant if you're
% using an unmodified FSF texinfo.  
% FIXME! check whether these are still needed, or whether Courier OK now
%       w/shorter paths
\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
\font\user=pcrb at 10pt
\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{{\user #1}}
\global\parindent=0pt
@end tex
@titlepage
@ifset CDROMinst
@title CD-ROM Installation Notes
@end ifset
@ifset TAPEinst
@title Tape Installation Notes
@end ifset
@ifset FTP
@title FTP Installation Notes
@end ifset
@sp 3
@subtitle Cygnus Support Developer's Kit
@subtitle Release ||RELNO|| for Solaris 2.0
@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 (Solaris 2 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{Release ||RELNO|| for Solaris 2}
@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
@top Cygnus Support Solaris-2 Developer's Kit, version ||RELNO||

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

@ifclear FTPorCD
@menu
* Brief::                       Installing in Brief
* Contents::                    Release Contents
* Installing::                  Installing the Developer's Kit
* Examples::                    Installation Examples
* Install-Options::             Installation Options
* Why-fixincludes::             Why Convert System Header Files?
* 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
@end menu
@end ifclear
@ifset FTPorCD
@menu
* Brief::                       Installation Procedure
* Contents::                    Release Contents
* Install-Options::             Installation Options
* Why-fixincludes::             Why Convert System Header Files?
* Running::                     Running the Programs
* Paths::                       Changing the Paths
* Trouble::                     Some Things that Might go Wrong
* Rebuilding::                  Rebuilding From Source
* Cygnus-FSF::                  Cygnus Releases and the FSF
* Cygnus-Support::              About Cygnus Support
@end menu
@end ifset

@end ifinfo

@ifclear FTPorCD
@node Brief
@chapter Installing in Brief
@end ifclear

@ifset FTPorCD
@node Brief
@chapter Installation Procedure
@end ifset

@ifset TAPEinst
@strong{You can run the brief installation procedure if:}
@itemize @bullet
@item
Your ||HOST|| has its own tape drive (@code{/dev/rmt/0ln}---those
last three characters are zero, el, en; see @samp{man st}), and
@item
You're willing to install in the directory @file{/opt}, and
@item
You have at least ||DF|| MB available (try @samp{df /opt}; @pxref{Disk space})
@item
The Solaris-2 OS packages @code{SUNWesu}, @code{SUNWhea},
@code{SUNWbtool}, @code{SUNWarc}, and @code{SUNWtoo} are installed (try
@samp{pkginfo @var{name}}; @pxref{Optional OS packages}).
@end itemize
Otherwise, see @ref{Installing,,Installing the Developer's Kit}.
@end ifset
@ifset FTPorCD
@strong{To install the Cygnus Solaris-2 Developer's Kit, you need:}

@end ifset
@ifset FTPsingle
@itemize @bullet
@item
the distribution file, @file{cygnus-sol2-||RELNO||.tar.Z}, in some directory
@var{dist} on your system
@item
The Solaris-2 OS packages @code{SUNWesu}, @code{SUNWhea},
@code{SUNWbtool}, @code{SUNWarc}, and @code{SUNWtoo} installed on your
system (try @samp{pkginfo @var{name}}).  See @ref{Optional OS packages}.
@item
at least ||DF|| MB of disk space available.  See @ref{Disk space}.
@end itemize
@end ifset
@ifset FTPsplit
@itemize @bullet
@item
the distribution files, @file{cygnus-sol2-||RELNO||.bin.tar.Z} (if you
want precompiled binaries) and @file{cygnus-sol2-||RELNO||.src.tar.Z}
(if you want the source code), in some directory @var{dist} on your
system
@item
The Solaris-2 OS packages @code{SUNWesu}, @code{SUNWhea},
@code{SUNWbtool}, @code{SUNWarc}, and @code{SUNWtoo} installed on your
system (try @samp{pkginfo @var{name}}).  See @ref{Optional OS packages}.
@item
at least ||BD|| MB of disk space available for the binaries.  See @ref{Disk space}.
@item
at least ||SD|| MB of disk space available for the source.  See @ref{Disk space}.
@end itemize
@end ifset
@ifset CDROMinst
@itemize @bullet
@item
A copy of the SunSoft Catalyst CDware disc.
@item
The Solaris-2 OS packages @code{SUNWesu}, @code{SUNWhea},
@code{SUNWbtool}, @code{SUNWarc}, and @code{SUNWtoo} installed on your
system (try @samp{pkginfo @var{name}}).  See @ref{Optional OS packages}.
@item
at least ||BD|| MB of disk space available for the binaries. See @ref{Disk space}.
@item
at least ||SD|| MB of disk space available for the source.  See @ref{Disk space}).
@end itemize
@end ifset

@ifset FTPorCD
We suggest installing the Developer's Kit under @file{/opt} (at least
via a symbolic link).  The precompiled tools are configured for this
location.  If you install elsewhere, and cannot establish a symbolic
link to @file{/opt/cygnus-sol2-||RELNO||}, see @ref{Paths,,Changing the
Paths}.
@end ifset

@enumerate
@ifclear FTPorCD
@item 
Make sure you can write in @file{/opt/cygnus-sol2-||RELNO||}, by typing:

@example
eg$ @b{su root}
password:           @i{(enter root password)}
# @b{mkdir /opt/cygnus-sol2-||RELNO||}    @i{(ignore error if any)}
# @b{chmod 777 /opt/cygnus-sol2-||RELNO||}
# @b{exit}              @i{(give up root access)}
@end example
@end ifclear

@ifset FTPorCD
@item
Make sure you can write in @file{/opt}, by typing:

@example
eg$ @b{touch /opt/cygnus-test; rm /opt/cygnus-test}
@end example

If you get an error, talk to your System Administrator about access to
@samp{/opt}.  If you can't get permission to write in @file{/opt}, see
@ref{No access,,No Access to @file{/opt}}.
@end ifset

@ifset FTPsingle
@item
Extract the Developer's Kit from the distribution file.

@example
@exdent @emph{If you can install directly in @file{/opt}:}
eg$ @b{cd /opt}
eg$ @b{zcat @var{dist}/cygnus-sol2-||RELNO||.tar.Z | tar xfov -}
@end example

@example
@exdent @emph{If you install in another directory @var{other}:}
eg$ @b{cd} @var{other}
eg$ @b{zcat @var{dist}/cygnus-sol2-||RELNO||.tar.Z | tar xfov -}
eg$ @b{ln -s cygnus-sol2-||RELNO|| /opt}
@end example
@end ifset

@ifset FTPsplit
@item
Extract the Developer's Kit binaries from the distribution file.

@example
@exdent @emph{If you can install directly in @file{/opt}:}
eg$ @b{cd /opt}
eg$ @b{zcat @var{dist}/cygnus-sol2-||RELNO||.bin.tar.Z | tar xfov -}
@end example

@example
@exdent @emph{If you install in another directory @var{other}:}
eg$ @b{cd} @var{other}
eg$ @b{zcat @var{dist}/cygnus-sol2-||RELNO||.bin.tar.Z | tar xfov -}
eg$ @b{ln -s cygnus-sol2-||RELNO|| /opt}
@end example

@item
If you also want the source, repeat the previous step, but with the file
@file{@var{dist}/cygnus-sol2-||RELNO||.src.tar.Z}.
@end ifset

@ifset CDROMinst
@item
Mount the @sc{cdware cd-rom}.  You may need to briefly become super-user:

@example
eg$ @b{su root}
password:           @i{(enter root password)}
# @b{mkdir} @b{/cdrom}             @i{(ignore any errors)}
# @b{mount} @b{-F} @b{hsfs} @b{-o} @b{ro} @b{/dev/dsk/c0t6d0s0} @b{/cdrom}
# @b{exit}              @i{(give up root access)}
@end example

@item
Start the @sc{cd-rom}'s presentation program (see the instructions
that came with your @sc{cd-rom}).

@item
Look for an icon showing the Cygnus logo, with the label ``GNU C''.  If
you can't find this icon, you may have the wrong category selected; in
the Category menu, select either ``All'' or ``Software Engineering''.

@item
Select the Cygnus icon by clicking once on it with the left mouse
button.

@item
Select ``Install'' from the Options menu.  A submenu appears, showing
these options:

@display
Install Everything
Install Binaries
Install Source Code
@end display

Select one of these options.  (Selecting ``Install Everything'' is
equivalent to selecting each of the other two options, to get both
binaries and source code for the Developer's Kit.) 
An interaction window appears.

@item
Answer the prompt @samp{Installation directory} with the name of the
directory where you want the Developer's Kit installed.  We recommend
@file{/opt} (which is the default), because the compiler and other tools
are configured for this location.  (If you use another directory,
see @ref{Paths,,Changing the Paths}.)

@item
Inspect the messages that appear in the interaction window.  The
installation script @code{Install} displays occasional messages to keep
you informed about the steps it executes.  Among them, these messages
mark completion of the major stages of installation:

@example
Cygnus Support software distribution extracted!

Fixed include files installed!

Cygnus Support software distribution tested!

@end example

@strong{If all these messages have appeared}, skip the next step.

@strong{If you see messages about missing parts of Solaris 2}, make sure
you have all the optional packages described in
@ref{Optional OS packages}.  Then proceed with the next
step.
@end ifset

@ifset TAPEinst
@item
Load the cygnus-sol2-||RELNO|| ||MEDIUM|| into your ||MEDIUM|| drive.

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

@example
eg$ @b{cd /tmp}
eg$ @b{tar xfov /dev/rmt/0ln Install}
@i{Ignore ``WARNING: @dots{} Sense Key: Unit Attention'' message.}
@i{For other errors, try reinserting the tape and rerunning.}
@end example

@item
Run the @code{Install} script:

@example
eg$ @b{./Install}
@i{@dots{} @code{Install} displays messages about its activity, ending with}
Done.
@end example
@end ifset

@ifset FTPorCD
@item
Fix up copies of the system header files for your ||HOST||, and test the
installation, with the @code{Install} script that was extracted from the
distribution.  @emph{@code{Install} makes its own copies of the header
files; your system's original header files are not changed.}  

@example
eg$ @b{cd cygnus-sol2-||RELNO||}
eg$ @b{./Install}
@exdent @code{Install} displays messages about its activity, ending with
Done.
@end example

For background information on this step, see @ref{Why-fixincludes,,Why
Convert System Header Files?}.
@end ifset

@ifset CUSTOMER
@item
Record your Cygnus customer-ID (see cover letter):

@example
eg$ @b{/opt/cygnus-sol2-||RELNO||/bin/install_cid @var{ID}}
@end example
@end ifset

@item
Make a symbolic link to simplify pathnames:
@example
eg$ @b{cd} @b{/opt}
eg$ @b{ln} @b{-s} @b{cygnus-sol2-||RELNO||} @b{cygnus}
@end example

@ifclear FTPorCD
@c Assume *WE* don't distribute cygnus-sol2-||RELNO|| w/permissions 777
@item
Remove public write access from @file{/opt/cygnus-sol2-||RELNO||}.  See your System
Administrator for the correct permissions at your site.
@end ifclear

@end enumerate

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

@node Contents
@chapter Release Contents

This Developer's Kit is a Cygnus Support 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?

@table @t
@item gcc
C compiler

@item libm.a
Mathematical subroutine library

@item gdb
Debugger

@item gprof
Performance analyzer

@item byacc
Parser generator

@item flex
Fast lexical analyzer generator

@item makeinfo
@itemx info
Online documentation tools

@item texinfo.tex
@itemx texindex
Documentation printing tools

@item send_pr
The Cygnus problem-reporting utility

@item patch
Source-code update utility
@end table

@menu
* Platforms::                   Supported Platforms
* Requirements::                System Requirements
@end menu

@node Platforms
@section Supported Platforms

@table @strong
@item ||HOST||s
All programs in your Developer's Kit are for ||HOST||s running
Solaris 2.0; we ship binaries (configured to install and run under
@file{/opt/cygnus-sol2-||RELNO||}) as well as all source code.

@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

@page
@node Requirements
@section System Requirements

@ifset FTPorCD
@menu
* OS level::
* Optional OS packages::
* Disk space::
* Write access::
@end menu
@end ifset

@ifset TAPEinst
@menu
* OS level::
* Optional OS packages::
* A tape drive::
* Disk space::
* Write access::
@end menu
@end ifset

@node OS level
@subsection OS level
Solaris 2.0 Beta or later.

@node Optional OS packages
@subsection Optional OS packages
Many components of Solaris 2.0 are part of the standard operating system
distribution, but are not installed by default.  To install the Cygnus
Solaris 2.0 Developer's Kit, you will need to make sure two of these
optional components (called @dfn{packages}) are installed on your system:
@samp{SUNWesu} and @samp{SUNWhea}.  Three more packages are needed to
run the Developer's Kit software after you've installed it:
@samp{SUNWbtool}, @samp{SUNWtoo}, and @samp{SUNWarc}.

To check whether an optional package is installed, you can run
@samp{pkginfo @var{name}}.  @code{pkginfo} is in @file{/usr/bin/}.  If
@var{name} is not installed, you will get an error, like this:

@example
eg$ @b{/usr/bin/pkginfo} @b{SUNWlibm}
ERROR: information for "SUNWlibm" was not found
@end example

@noindent
If @var{name} is installed, you will see a one-line summary of the
package, like this:

@example
eg$ @b{/usr/bin/pkginfo} @b{SUNWhea}
system      SUNWhea        Header Files
@end example

To install one of these optional parts of Solaris 2 (@var{name} in the
example), put the Solaris 2.0 distribution CD in the drive, mount it
(for example, as @file{/cdrom}), then do:

@example
/usr/sbin/pkgadd -d /cdrom/Solaris_2.0 @var{name} @dots{}
@end example

@noindent
You can specify several package names at once.

These are the Solaris 2 optional packages you'll need to run the
Developer's Kit:

@table @code
@item SUNWarc
@emph{Needed to link your programs:} Archive libraries for system
interfaces.

@item SUNWbtool
@emph{Needed to build your programs:} ``SPARCCompilers
2.0 Bundled tools''.  Most of the contents of @file{/usr/ccs/bin}
(most notably, the assembler) come from this package.

@item SUNWesu
@emph{Needed to install the Developer's Kit:} ``Extended System
Utilities''.  The decompression program (@code{compress},
@code{uncompress}, @code{zcat}) is in this package; it is used to
extract the contents of the Developer's Kit.

@item SUNWhea
@emph{Needed to complete installation and compile your programs:} Header
files (@file{/usr/include}).

@item SUNWtoo
@emph{Needed to link your programs:} ``Programming Tools'', notably the
linker, @code{/usr/ccs/bin/ld}.
@end table

@noindent
One additional optional package may be of interest:

@table @code
@item SUNWlibm
Sun's math subroutine library.  This is not required, however, as a free
@samp{libm.a} is part of the Developer's Kit.
@end table

@ifset TAPEinst
@node A tape drive
@subsection A tape drive
You need access to a tape drive that can read the distribution.
The 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||.
@end ifset

@node Disk space
@subsection 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{/opt/cygnus-sol2-||RELNO||}.  If you have
space available, but not in the same file system as @file{/opt}, you can
use @samp{ln -s} to create @file{/opt/cygnus-sol2-||RELNO||} as a symbolic link to the
file system where you do have the space available.

@ifclear FTPorCD
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.
@end ifclear

@node Write access
@subsection Write access
You need write access to @file{/opt}, or at least to an existing
@file{/opt/cygnus-sol2-||RELNO||} directory.  If you can't write in
@file{/opt} or @file{/opt/cygnus-sol2-||RELNO||}, see @ref{No access,,No
Access to @file{/opt}}.

@ifclear FTPorCD
Root access is @emph{not} necessary to run the installation itself;
but you might need it briefly 
@ifset CDROMinst
to mount the @sc{cd-rom} drive, and
@end ifset
to arrange for a writable @file{/opt/cygnus-sol2-||RELNO||} directory.  The detailed
installation instructions show when this may be necessary.  We recommend
you avoid @samp{su root} whenever possible.
@end ifclear

@ifclear FTPorCD
@node Installing
@chapter Installing the Developer's Kit

@iftex
This note shows the different parts of examples like this:
@table @asis
@item Computer output is shown in @code{typewriter font.}
@item Your input is indicated by @b{a bold typewriter font.}
@item Text to be replaced, rather than typed verbatim, is in @var{this font.}
@item Comments appear in @i{italic font}.
@end table
@end iftex
In examples, we show the system prompt as @samp{eg$}.

The Cygnus cygnus-sol2-||RELNO|| ||MEDIUM|| contains two separate
files.  The first file is a script called @code{Install};
the second file contains the Developer's Kit 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 ||MEDIUM||.
Then you can use the @code{Install} script to choose what else to
install.

Two checklists follow.  The first checklist shows what to do if you have
a ||MEDIUM|| drive on the ||HOST|| where you want to install the
Developer's Kit; the second shows how to use another networked machine
to read the ||MEDIUM||, then finish the installation on your ||HOST||.

Both checklists suggest installing the Developer's Kit under
@file{/opt} (if you like, via a symbolic link from another location).
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{/opt/cygnus-sol2-||RELNO||}, please see
@ref{Install-Options,,Installation Options}.  To use the software
conveniently after installing elsewhere, 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
||MEDIUM|| drives, for systems whose available disk space is not in
@code{/opt}, and for installing only portions of the Developer's Kit.

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

@node local-install
@section Installing in @file{/opt}, with a local ||MEDIUM|| drive

This procedure is for a ||HOST|| that has its own ||MEDIUM|| 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 ||MEDIUM||, 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,
see @ref{Examples,,Installation Examples}.

@enumerate
@item
Make sure that you have all the required Solaris 2 OS packages:
@code{SUNWesu}, @code{SUNWhea}, @code{SUNWbtool}, @code{SUNWarc}, and
@code{SUNWtoo}.  You can use @code{pkginfo} to check; see
@ref{Optional OS packages}.

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

@item
Check whether you can write in @file{/opt}:

@cartouche
@example
eg$ @b{touch /opt/cygnus-test; rm /opt/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 may need to use another group, or an account that has
permission to write in @file{/opt} or in an existing
@file{/opt/cygnus-sol2-||RELNO||} directory.  See @ref{No access,,No Access
to @file{/opt}}.  If only @code{root} has access, the simplest procedure
is to @code{su root} @emph{briefly}, to create a writable
@file{/opt/cygnus-sol2-||RELNO||}.  For instance:

@cartouche
@example
eg$ @b{su root}
password:           @i{enter root password}
# @b{mkdir /opt/cygnus-sol2-||RELNO||}        @i{ignore error if any}
# @b{chmod 777 /opt/cygnus-sol2-||RELNO||}
# @b{exit}              @i{give up root access}
eg$
@end example
@end cartouche

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

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

You will most likely use @file{/dev/rmt/0ln} (the last three characters
are zero, el, en) as the tape device, regardless of which of the two
kinds of tape you have; see @samp{man st} for details on how tape
devices are named on Solaris 2.

However, the correct device name depends on how your system's tape
drives were installed; ask your system administrator.  If the tape drive
you plan to use is your system's only tape drive, @file{/dev/rmt/0ln} is
very likely.  Otherwise it may be something like @file{/dev/rmt/1ln}.

Our examples show @file{/dev/rmt/0ln} for the tape device, as this is
the most common case.

@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{/opt/cygnus-sol2-||RELNO||}.

These commands will get @code{Install} into the @file{/tmp} directory
(remember, you may need something slightly different from
@file{/dev/rmt/0ln} as the device name for the appropriate tape drive on
your system):

@cartouche
@example
eg$ @b{cd /tmp}
eg$ @b{tar xfov /dev/rmt/0ln Install}
@end example
@end cartouche

A frightening five-line message beginning ``@code{WARNING}'' and ending
with ``@code{Sense Key: Unit Attention}'' is very common at this point.
It does not indicate anything is wrong; on the contrary, it's the
operating system's way of letting you know that it noticed you put in a
tape.

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 where we show @file{/dev/rmt/0ln}.  Some errors can be
corrected by reseating the tape in the tape drive and trying again.
@end ifset

@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, see @ref{Examples,,Installation Examples}.
@end quotation

@item
Now you can extract your Developer's Kit software by running
@code{Install}.  Use the @samp{-tape=} option to specify where
the software comes from:

@cartouche
@example
eg$ @b{/tmp/Install -tape=/dev/rmt/0ln}
@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{/opt/cygnus-sol2-||RELNO||/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{/opt/cygnus-sol2-||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 CUSTOMER
@item
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{/opt/cygnus-sol2-||RELNO||/bin/install_cid @var{ID}}
install_cid:`@var{ID}' is now the default customer ID for send_pr
@end example
@end cartouche
@end ifset

@item
Make a symbolic link to simplify pathnames (@pxref{Running,,Running the
Programs}):

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

@item
We recommended permissions @code{777} for the @file{/opt/cygnus-sol2-||RELNO||}
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 are found).

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

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

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

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 ||MEDIUM||, 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,
see @ref{Examples,,Installation Examples}.

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

@item
Make sure a decompression program is available.  The installation
procedure requires @code{compress} (used with the @samp{-d} option, in
the Cygnus @code{Install} script).  @code{compress} is present on most
Unix systems.  On Solaris 2 systems, it is part of the optionally
installed @code{SUNWesu} package.

@item
Choose a directory where you will install the Developer's Kit.  The
directory must be accessible from both machines (the one with the ||MEDIUM||
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{Disk space}) in
@var{shr}.  You can use @samp{df @var{shr}} to check.

@item
Check whether you can write in @var{shr}:

@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 may need to use another group, or an account that has
permission to write in @var{shr} or in an existing
@file{/@var{shr}/cygnus-sol2-||RELNO||} directory.  See @ref{No access,,No
Access to @file{/opt}}.  If only @code{root} has access, the simplest
procedure is to @code{su root} @emph{briefly}, to create a writable
@file{/@var{shr}/cygnus-sol2-||RELNO||}.  For instance:

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

@ifset TAPEinst
@item
Load the Cygnus Support release tape (labelled ``cygnus-sol2-||RELNO||'') into
the system's 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 QIC-24 or Exabyte.

On ||HOST|| (or compatible) systems running Solaris 2, you will most
likely use @file{/dev/rmt/0ln} (the last three characters are zero, el,
en) as the tape device, regardless of which of the two kinds of tape you
have; see @samp{man st} for details on how tape devices are named on
Solaris 2.

However, the correct device name depends on the kind of system, and on
how the system's tape drives were installed; ask your system
administrator.  On systems running Solaris or other Unix SVr4 variants,
if the tape drive you plan to use is your system's only tape drive,
@file{/dev/rmt/0ln} is very likely.  Otherwise it may be something like
@file{/dev/rmt/1ln}.

These examples show @file{/dev/@var{tape}} for the tape device; remember
to substitute the appropriate name.

@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-sol2-||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 to fill in the appropriate device for @file{/dev/@var{tape}}:

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

On Solaris-2 systems, a frightening five-line message beginning
``@code{WARNING}'' and ending with ``@code{Sense Key: Unit Attention}''
is very common at this point.  It does not indicate anything is wrong;
on the contrary, it's the operating system's way of letting you know
that it noticed you put in a tape.  Other systems may provide similar
amenities.

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}.  Some errors can be
corrected by reseating the tape in the tape drive and trying again.
@end ifset

@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, see @ref{Examples,,Installation Examples}.
@end quotation

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

@cartouche
@example
eg$ @b{cd} @b{/tmp}
eg$ @b{./Install} @b{extract} @b{-tape=||MEDvar||} @b{-installdir=@var{shr}}
@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-sol2-||RELNO||/tar.log}.

When @code{Install} is done extracting the software, 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
Make sure that your ||HOST|| has the required Solaris 2 OS packages:
@code{SUNWhea}, @code{SUNWbtool}, @code{SUNWarc}, and @code{SUNWtoo}
(@pxref{Optional OS packages}).  You can use @code{pkginfo}
to check.

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

@cartouche
@example
eg-sol2$ @b{su root}
password:
# @b{ln -s @var{shr}/cygnus-sol2-||RELNO|| /opt/cygnus-sol2-||RELNO||}
# exit              @i{root access not needed beyond this}
@end example
@end cartouche

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

@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-sol2-||RELNO||} (now accessible as @file{/opt/cygnus-sol2-||RELNO||} on your
machine):

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

@noindent
A log for the @code{fixincludes} step goes in
@file{/opt/cygnus-sol2-||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 CUSTOMER
@item
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-sol2$ @b{/opt/cygnus-sol2-||RELNO||/bin/install_cid @var{ID}}
install_cid:`@var{ID}' is now the default customer ID for send_pr
@end example
@end cartouche
@end ifset

@item
Make a symbolic link to simplify pathnames (@pxref{Running,,Running the
Programs}):

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

@item
We recommended permissions @code{777} for the @file{/opt/cygnus-sol2-||RELNO||} and
@file{@var{shr}/cygnus-sol2-||RELNO||} 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 are found).

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

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

@node Examples
@chapter Installation Examples

Once you've got the @code{Install} script from your ||MEDIUM||,
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, see @ref{Install-Options,,Installation
Options}.

The default ||MEDIUM|| drive for @code{Install} is @code{/dev/rmt/0ln}, which is
right for the most common cases on Solaris 2 systems.  If your
||MEDIUM|| drive is different, you need to use the
@samp{-tape=||MEDvar||} option; the examples show this option for
completeness.  
@ifset TAPEinst
Remember to specify a @emph{non-rewinding} tape device.
@end ifset

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

@node binaries
@section Installing binaries only

@cartouche
@example
eg$ @b{./Install -tape=||MEDvar|| 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
@section Reading ||MEDIUM|| on any SVr4 machine, finishing on ||HOST||

@cartouche
@example
@emph{On an SVr4 machine on your network with a ||MEDIUM|| drive:}
eg-tp$ @b{./Install -tape=/dev/rmt/0ln -installdir=@var{shr} extract}
@end example
@end cartouche

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

@noindent
If your ||HOST|| doesn't have a ||MEDIUM|| 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 ||MEDIUM|| 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 software.  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 @ref{Why-fixincludes,,Why Convert System Header Files?}, if you're
curious.

@node source-remove
@section 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 /opt/cygnus-sol2-||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.
@c following "end" matches ifclear FTPorCD several nodes back!
@end ifclear

@node Install-Options
@chapter Installation Options

The command-line arguments and options to @code{Install} allow you to
direct its operation in these ways:

@ifclear FTPorCD
@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 a ||HOST|| running Solaris 2.
@end itemize
@end ifclear

@itemize @bullet
@item
@emph{What installation actions} to carry out:
@enumerate
@ifclear FTPorCD
@item
extracting source from the ||MEDIUM|| (option
@code{extract})
@end ifclear
@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

@ifclear FTPorCD
The last two of these actions (@code{fixincludes} and
@code{test}) can only run on your ||HOST||.  If you read the
||MEDIUM|| 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||).

@item
@emph{Removing some of the release} after it's installed.

@item
@emph{Where to find the software distribution}, with the @samp{-tape} option.
@end ifclear

@item
@emph{Where you want to install}, with the @samp{-installdir} option.
@end itemize

Here is a summary of the @code{Install} command-line options,
followed by more detailed explanations:

@ifclear FTPorCD
@example
Install @r{[} -tape=||MEDvar|| @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
@end ifclear
@ifset FTPorCD
@example
Install @r{[} fixincludes @r{]} @r{[} test @r{]}
@end example
@end ifset

@ifset TAPEinst
@table @code
@item -tape=||MEDvar||
@itemx -tape=@var{tarfile}
Specify the @emph{non-rewinding} device name for your tape drive as
@file{rmt/0ln} (the last three characters are zero, el, en).

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

@item -installdir=@var{directory}
If you have no write access to @samp{/opt}, use this option to specify
an alternate @var{directory} for your software---but beware: the
software is configured to go in @samp{/opt/cygnus-sol2-||RELNO||}, and
you'll have to override or change that too.  See @ref{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

@item extract
@itemx fixincludes
@itemx test
A full installation includes up to three things: (1) extracting
software; (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 extract the software, @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.
See @ref{Why-fixincludes,,Why Convert System Header Files?}, for more
discussion of the @samp{fixincludes} step.  @code{Install} will only
attempt these 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{/opt/cygnus-sol2-||RELNO||}.  

When you run @samp{fixincludes}, @code{Install}
leaves a log file @file{fixincludes.log} in the @file{cygnus-sol2-||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}, together with
@samp{remove}.  @code{Install} will erase these parts of the
installation from your system.  See @ref{Removing,,Removing Parts of the
Developer's Kit}, for an example.
@end table
@end ifset

@ifset FTPorCD
@table @code
@item fixincludes
@itemx test
These steps are performed when you run @code{Install} without
arguments, but if you like you can select either of them explicitly.

After you extract the software, @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.
See @ref{Why-fixincludes,,Why Convert System Header Files?}, for more
discussion of the @samp{fixincludes} step.  @code{Install} will only
attempt these 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.  

When you run @samp{fixincludes}, @code{Install}
leaves a log file @file{fixincludes.log} in the @file{cygnus-sol2-||RELNO||}
subdirectory.
@end table
@end ifset


@node Why-fixincludes
@chapter Why Convert System Header Files?

It is very important to run the @samp{fixincludes} step of installation
(either explicitly, as @samp{Install fixincludes}, or by default when
you run @code{Install} with no arguments).  You must do this on
@emph{each installation}: if many ||HOST||s share the same binaries on a
shared filesystem, you need only do it once---but if you install
separate copies, you must run @code{Install fixincludes} on each.

The C header files supplied with SVr4 versions of Unix depend on a
questionable interpretation of the @sc{ansi} C standard: they test for a
non-@sc{ansi} environment by checking whether @code{__STDC__} is defined
as zero.  The @sc{ansi} standard actually only specifies that
@code{__STDC__} will be defined to 1; if it is defined to any other
value, the environment is not @sc{ansi} C compatible, and @sc{ansi} C
says nothing about what that value might be.

@sc{gcc} defines @code{__STDC__} to 1 when running with @samp{-ansi},
when it functions as an ``@sc{ansi} C superset'' compiler.  (It also sets
@code{__STRICT_ANSI__} when it runs with the @samp{-pedantic} option.)
However, @sc{gcc} leaves @code{__STDC__} undefined when it is not
running as an @sc{ansi} C compiler.

Unfortunately, the Solaris 2 header files follow the SVr4 choice.  Since
@sc{gcc} never defines @code{__STDC__} as 0, the distributed header
files can leave out some declarations.  (Look in @file{/usr/include/time.h},
for example.)

@samp{Install fixincludes} makes copies of the system include files,
which have these nonstandard features removed so that @sc{gcc} can
process them.  These copies are placed in a new, @sc{gcc}-specific
include directory---@emph{your system's original header files are not
affected.} Once these fixed header files are created, @sc{gcc} finds and
uses them automatically.

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 Running
@chapter Running the Programs
Anyone who wishes to run the Cygnus development tools will need to make
sure the @code{PATH} environment variable will find them.  The simplest
thing is to include @samp{/opt/cygnus-sol2-||RELNO||/bin} in the
@code{PATH} variable.  Since the directory name contains the release
number @samp{||RELNO||}, however, this approach will require changing
the paths explicitly for all users when you install a new release.

Our installation procedures recommended creating a symbolic link like
this, to plan ahead for future releases:

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

Then people can use settings like these in initialization files:

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

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

@noindent
You can also ensure that the @code{man} command can pick up the
manual pages, using the @code{MANPATH} environment variable.

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

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

@node Paths
@chapter Changing the Paths
The binaries shipped by Cygnus are configured for installation under the
directory @file{/opt/cygnus-sol2-||RELNO||}.  In particular, @code{gcc}
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
to tell the tools where to find pieces of the installation; or

@item
rebuild the tools from source, with your preferred paths built in.
See @ref{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{/opt/cygnus-sol2-||RELNO||}.

@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 distribution
under @file{/local} (instead of the default @file{/opt}), 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 in the space
available.)

@cartouche
@example
@b{GCC_EXEC_PREFIX=/local/cygnus-sol2-||RELNO||/lib/gcc-lib/}\
@b{||HOSTstr||/||GCCvn||/}
@b{export GCC_EXEC_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_EXEC_PREFIX /local/cygnus-sol2-||RELNO||/lib/gcc-lib/}\
@b{||HOSTstr||/||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 @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{/opt/cygnus-sol2-||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/cygnus-sol2-||RELNO||/info}
@b{export INFOPATH}
@end cartouche
@end example

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

@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{/opt/cygnus-sol2-||RELNO||}, @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{/opt/cygnus-sol2-||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
@chapter 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.

@ifclear FTPorCD
@menu
* No Drive::                    No local ||MEDIUM|| drive
* Limited Space::               Not Enough Space
* No access::                   No Access to @file{/opt}
* Install errors::              Error Messages from @code{Install}
@end menu
@end ifclear
@ifset FTPorCD
@menu
* No access::                   No Access to @file{/opt}
* Install errors::              Error Messages from @code{Install}
@end menu
@end ifset


@ifclear FTPorCD
@node No Drive
@section No local ||MEDIUM|| drive
If your ||HOST|| doesn't have an appropriate ||MEDIUM|| 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 drive
you can use.  If so:
@table @emph
@item If a shared filesystem is available
between the two machines, and it has enough space, go ahead and run
@samp{Install extract -installdir=@var{shr}} from the machine with a
||MEDIUM|| drive, where @var{shr} is a directory visible to both
machines.  Then create @samp{/opt/cygnus-sol2-||RELNO||} on your
||HOST|| (the one where you want to install this Solaris 2 Developer's
Kit) as a symbolic link to @file{@var{shr}/cygnus-sol2-||RELNO||}.
You'll have to run @samp{Install fixincludes} and @samp{Install test}
from your ||HOST|| afterwards; see @ref{cross-install,,Installing with
another machine's ||MEDIUM|| drive}.

@item If some form of filetransfer is available
(such as @code{uucp}), read the ||MEDIUM|| 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 ||MEDIUM||; the first is
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
||MEDIUM|| drive}, but use @samp{-tape=@var{tarfile}} to specify the name of
the installation file, instead of @samp{-tape=/dev/rmt/0ln} 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
@section Not Enough Space
If you don't have enough space to install all of the 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 with your release.
See @ref{Install-Options,,Installation Options}.
@end ifclear

@node No access
@section No Access to @file{/opt}

If you don't have write access to @file{/opt}, first check whether
you're in the right group.  The command @samp{ls -lLdg /opt} will show
you whether any group has write access to @file{/opt}, and the command
@code{groups} will show you what groups you're authorized to use.  If
you're authorized to use a group with the right access, use @samp{newgrp
@var{groupname}} to switch to that group.

Otherwise, you may be able to use @code{root} (if you have the password)
to give yourself temporary write access.  There's no need to run the whole
installation procedure as @code{root}; just use @code{root} access
briefly like this---

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

@noindent
If you do set write permissions to @code{777} to run the installation
procedure, remember to remove public write access when you're done, to
avoid potential security problems.

If none of these things help, and you can't get write access to
@file{/opt} or @file{/opt/cygnus-sol2-||RELNO||},
@ifset TAPEinst
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 -installdir=@var{mydir}}.
@end ifset
@ifset FTPorCD
use a different installation directory, where you @emph{can} write.
@end ifset
You will also have 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{/opt/cygnus-sol2-||RELNO||} (or link your installation directory
to that name), some of the defaults configured into the
cygnus-sol2-||RELNO|| distribution won't work.  See @ref{Paths,,Changing
the Paths}, for information on overriding or reconfiguring these
defaults.
@end quotation

@node Install errors
@section 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.  

@ifclear FTPorCD
Here is a list of a few messages where further information might be
useful:
@table @code
@item Cannot read from TAPE device @dots{}
The error message ends with the device or file @code{Install} was trying
to use.  Please check that it is the device or file you intended;
possible causes of trouble might include leaving off the @samp{/dev/}
prefix at the front of a device name.  A typo in the name might also
cause this problem.

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

@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.  
@end table
@end ifclear

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

@node Rebuilding
@chapter Rebuilding From Source

@ifclear FTPsplit
All Cygnus products are free software; your Developer's Kit includes
complete source code for all programs.
@end ifclear
@ifset FTPsplit
All Cygnus products are free software.  The source code for all programs
in your Developer's Kit is available from the same place as the precompiled
programs, in the file @file{@var{dist}/cygnus-sol2-||RELNO||.src.tar.Z}.
@end ifset

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 @var{installdir}/src}

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

eg$ @b{make clean all info install install-info}
@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
@section 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
@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{sun4sol2} as a @var{host} argument
or in a @samp{-target=@var{target}} option, but the equivalent full name
is @samp{sparc-sun-solaris2}.

@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
@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 in this release were configured using

@cartouche
@example
configure -prefix /opt/cygnus-sol2-||RELNO|| ||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=/opt/cygnus-sol2-||RELNO||} was used to build the binaries in this
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.

No @samp{-exec-prefix} was used to build the binaries in this 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}; for the binaries in this release,
@file{/opt/cygnus-sol2-||RELNO||}).

@item -srcdir=@var{path}
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.  (This
option requires a @code{make} program with the @samp{VPATH} feature,
such as the one included with Solaris 2.)

@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
@section 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}
@end example
@end cartouche

The @code{make} output is lengthy; consider redirecting it to a file.

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}
@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
@section 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

@ifclear FTPorCD
@node Removing
@chapter 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{/opt/cygnus-sol2-||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 release undisturbed, as follows:

@cartouche
@example
eg$ @b{cd /opt/cygnus-sol2-||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 Solaris 2 Release of the Developer's Kit from
your system (if, eventually, you no longer want it), delete the
directory @file{/opt/cygnus-sol2-||RELNO||} and all its contents.
@end ifclear

@node Cygnus-FSF
@chapter 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 releases add to FSF
software in the following ways:
@c UPDATE! more differences bet Cygnus/FSF releases?

@itemize @bullet
@item
All programs are ready to run.  We supply preconfigured and precompiled
binaries as well as the source code; you can start using the programs
right away.
@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 Cygnus 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

This particular Cygnus Progressive release differs from the nearest
corresponding FSF distributions in one important detail: Solaris 2 is
supported.  The FSF distributions will eventually include Solaris 2
support, as the Cygnus changes are merged into the FSF source, and the
FSF makes new releases.


@node Cygnus-Support
@chapter 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

@contents

@bye