Info file sparc-sun-solaris2/cygnus-sol2-1.0/src/INSTALL, produced by
Makeinfo, -*- Text -*- from input file
sparc-sun-solaris2/cygnus-sol2-1.0/src/install.texinfo.


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



Installing in Brief
....................

   *You can run the brief installation procedure if:*
   * You have a QIC-24 release tape (see tape label), and

   * Your Sun-4 has its own QIC-24 tape drive (`/dev/rmt/0n'), and

   * You're willing to use the installation directory `/usr/cygnus',
     and

   * You have at least 48 MB available in `/usr' (try `df /usr')
Otherwise, see *Note Installing the Developer's Kit: Installing.

   *Steps for Brief Install:*

  1. Make sure you can write in `/usr/cygnus', by typing:

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

  2. Load the Progressive--1.0 tape into your tape drive.

  3. Get the `Install' script from the tape:

          eg$ cd /tmp
          eg$ tar xfv /dev/rmt/0n Install

  4. Run the `Install' script:

          eg$ ./Install

        `Install' displays messages about its activity, ending with

          Done.

  5. Build symbolic links to make execution paths easy:

          eg$ cd /usr/cygnus
          eg$ ln -s progressive-1.0 progressive
          eg$ su root       (may need root access to put link in /usr)
          password:
          # ln -s /usr/cygnus/progressive/H-sparc-sun-solaris2 /usr/progressive
          # exit            (give up root access as soon as possible)

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

          eg$ /usr/progressive/bin/install_cid ID

  7. Remove public write access from `/usr/cygnus'.  See your System
     Administrator for the correct permissions at your site.

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


Release Contents
*****************

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

gcc
     C compiler

g++
     C++ compiler

gas
     assembler

gdb
     debugger

gprof
     Performance analyzer

byacc
     Parser generator

flex
     Fast lexical analyzer generator

ld
     linker

make
     compilation control program

libg++.a
     C++ class library

ar
     Manages object code archives

nm
     Lists object file symbol tables

objdump
     Displays object file information

ranlib
     Generates archive index

size
     Lists section and total sizes

strip
     Discards symbols

makeinfo
info
     Documentation tools

texinfo.tex
texindex
     Documentation printing tools

send_pr
     Script to send structured problem reports to Cygnus

diff
     Compares source files

patch
     Installs source fixes



Supported Platforms
====================

*Sun-4*
     All programs in your Developer's Kit run on Sun-4 computers; we
     ship binaries (configured to install and run under `/usr/cygnus')
     as well as all source code.

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

    *voice*
          +1 415 322 3811

    *hotline*
          +1 415 322 7836

    *fax*
          +1 415 322 3270

    *email*
          `info@cygnus.com'



System Requirements
********************

*OS Level*
     Progressive Release 1.0 for Sun-4 hosts requires SunOS 4.1.1 (or
     later).

*Tape Drive*
     You need access to a tape drive that can read the distribution
     tape.  The tape drive need not be on the Sun-4 where you want to
     run the software; but it is best if the machine with a tape drive
     and your Sun-4 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 Sun-4.

     Cygnus release tapes are labelled to identify the kind of tape
     used; either QIC-24 tapes, or Exabyte tapes.

*Disk Space*
     The total space required to extract and install binaries and
     source for all programs is 48 megabytes.

     The software is configured to go into `/usr/cygnus'.  If you have
     space available, but not in the same file system as `/usr', you
     can use `ln -s' to create `/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 *Note Not Enough Space: Limited Space.  The
     space required for installing the binaries on Sun-4 systems is 20
     megabytes.

*Write Access*
     You need to to sign on to an account with write access to `/usr',
     or at least to an existing `/usr/cygnus' directory.  If you can't
     write in `/usr' or `/usr/cygnus', see *Note No Access to
     `/usr/cygnus': No access.

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


Installing the Developer's Kit
*******************************

   In examples, we show the system prompt as `eg$'.

   The Cygnus Progressive--1.0 tape contains two separate `tar' files.
 The first file contains a script called `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 `Install' script off the tape.  Then you can use the
`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 Sun-4) 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 Sun-4.

   Both checklists give the procedure for installing the Developer's
Kit under `/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 `/usr/cygnus', please see
*Note Installation Options: Install-Options.  To use the software
conveniently after installing elsewhere, you should reconfigure and
recompile from source; see *Note Changing the Paths: Paths.)

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



Installing in `/usr/cygnus', with a local tape drive
-----------------------------------------------------

   This procedure is for a Sun-4 that has its own tape drive.

   Installing this way will install all the source code, plus the
binaries for the Sun-4.  If you don't want both source and binaries,
stop after extracting `Install' from the tape, and read about what
options you can use with `Install' in *Note Installation Options:
Install-Options.  For examples of variations on what to install, *Note
Installation Examples: Examples.

  1. find out the name of the *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 QIC-24 or
     Exabyte.

        You should use one of the following devices:
    *QIC-24 tapes*
          Use `/dev/rmt/0n' where the examples show `/dev/TAPE'.

    *Exabyte tapes*
          The device name depends on how your Exabyte tape drive was
          installed; ask your system administrator.  You will probably
          use one of `/dev/nrst0' or `/dev/nrst1' where we show
          `/dev/TAPE'.

  2. Check that you have enough space available (*note System
     Requirements: Requirements.) in `/usr'.  You can use `df /usr' to
     check.

  3. Check whether there's already a `/usr/cygnus' directory, and
     whether you can write in it.  Typing the following line checks
     both:

          eg$ touch /usr/cygnus/test; rm /usr/cygnus/test

     *If you get no errors from this line, skip the next step.*

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

          eg$ su root
          password:           enter root password
          # mkdir /usr/cygnus        ignore ``File exists'' error if any
          # chmod 777 /usr/cygnus
          # exit              root access not needed beyond this
          eg$

        If you don't have access to `root' or to any account with
     permission to write in `/usr' or `/usr/cygnus', see *Note No
     Access to `/usr/cygnus': No access.

  5. Load the Cygnus Support release tape (labelled
     "Progressive--1.0") into your system's tape drive.

  6. Extract the `Install' script (remember, TAPE stands for the
     device name for the appropriate tape drive on your system):

          eg$ cd /tmp
          eg$ tar xfv /dev/TAPE Install

        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 TAPE.

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

          *If you don't want both source and binaries, stop now,* and
          read about what options you can use with `Install' in *Note
          Installation Options: Install-Options.  For examples of
          variations on what to install, *Note Installation Examples:
          Examples.

  7. Now you can extract all the software by running `Install'.  Use
     the `-tape=' option to identify your tape drive:

          eg$ /tmp/Install -tape=/dev/TAPE

        This is a time-consuming step.  `Install' will begin by using
     `tar' to extract software for your system, leaving a log in
     `/usr/cygnus/tar.log'.  Then it prepares copies of your system
     header files, converted to comply with ANSI C (*note Why Convert
     System Header Files?: Why-fixincludes.); a log for this step goes
     in `/usr/cygnus/progressive-1.0/fixincludes.log'.  *Your system's
     original header files are not changed;* `Install' writes the
     converted copies in a separate, GCC-specific directory.

        As it executes, `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:

          Cygnus Support software distribution extracted!
          
          Fixed include files installed!
          
          Cygnus Support software distribution tested!
          
          Done.

  8. Now that the software is on your system, you need to arrange for
     users to run it conveniently.  We recommend the following links;
     see *Note Links for Easy Access and Updating: Links, for a
     discussion.

          eg$ cd /usr/cygnus
          eg$ ln -s progressive-1.0 progressive
          
          eg$ su root            root privileges may be needed
          password:               to put link in /usr
          # ln -s /usr/cygnus/progressive/H-sparc-sun-solaris2 /usr/progressive
          # exit                  give up root privileges as soon as possible

  9. Finally, in case you need to send problem reports to Cygnus, we've
     included a script `send_pr' (and a supporting online template) to
     structure and transmit your reports.  Please use the script
     `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, +1 415 322 7836.)  This will enable us to respond as
     quickly as possible to any problem reports you send.

          eg$ /usr/cygnus/progressive-1.0/H-sparc-sun-solaris2/bin/install_cid ID
          install_cid: `ID' is now the default customer ID
           for send_pr

 10. We recommended permissions `777' for the `/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
     `/usr/cygnus'.  See your System Administrator for the correct
     permissions at your site.

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


Installing in `/usr/cygnus', with another machine's tape drive
---------------------------------------------------------------

   This checklist is for a Sun-4 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 Sun-4.

   Installing this way will install all the source, plus the binaries
for the Sun-4.  If you don't want both source and binaries, stop after
extracting `Install' from the tape, and read about what options you
can use with `Install' in *Note Installation Options: Install-Options.
 For examples of variations on what to install, *Note Installation
Examples: Examples.

  1. find a machine with a suitable tape drive on the same network as
     your Sun-4, and sign on to it.  If the only machine with a tape
     drive isn't on the network, *note No Local Tape Drive: No Drive..

  2. find out the name of the *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.

        You should use one of the following devices on Sun-4 (or
     compatible) systems:
    *QIC-24 tapes*
          Use `/dev/rmt/0n' where the examples show `/dev/TAPE'.

    *Exabyte tapes*
          The device name depends on how your Exabyte tape drive was
          installed; check with your system administrator.  You will
          probably use one of `/dev/nrst0' or `/dev/nrst1' where the
          example shows `/dev/TAPE'.

  3. 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 Sun-4 where you want to use the
     software)--for example, over NFS.  Wherever this note uses 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 SHR on both, for simplicity.

  4. Check that you have enough space available (*note System
     Requirements: Requirements.) in SHR.  You can use `df SHR' to
     check.

  5. Check whether there's already a `SHR/cygnus' directory, and
     whether you can write in it.  Typing the following line checks
     both:

          eg$ touch SHR/cygnus/test; rm SHR/cygnus/test

     *If you get no errors from this line, skip the next step.*

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

          eg$ su root
          password:           (enter root password)
          # mkdir SHR/cygnus      (ignore ``File exists'' error if any)
          # chmod 777 SHR/cygnus
          # exit              root access not needed beyond this
          eg$

  7. Load the Cygnus Support release tape (labelled
     "Progressive--1.0") into the tape drive.  In these examples, TAPE
     stands for the device name for the appropriate tape drive on your
     system.

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

        These commands will get `Install' into the `/tmp' directory
     (remember, TAPE stands for the device name for the appropriate
     tape drive on your system):

          eg$ cd /tmp
          eg$ tar xfv /dev/TAPE Install

     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 TAPE.

          *If you don't want both source and binaries, stop now,* and
          read about what options you can use with `Install' in *Note
          Installation Options: Install-Options.  For examples of
          variations on what to install, *Note Installation Examples:
          Examples.

  9. Now you can extract all the software by running `Install extract'. 
     Use the `-tape=' option to identify your tape drive, and the
     `-installdir=' option to point to the SHR directory.

          eg$ cd /tmp
          eg$ ./Install extract -tape=/dev/TAPE -installdir=SHR/cygnus

        This is a time-consuming step.  `Install' will use `tar' to
     extract software for your system, leaving a log in the file
     `SHR/cygnus/tar.log'.

        When `Install' is done extracting the tape contents, it
     displays the messages

          Cygnus Support software distribution extracted!
          Done.

 10. Log on to the Sun-4 where you want to use the software.

 11. Create a symbolic link from `SHR/cygnus/progressive-1.0' to
     `/usr/cygnus/progressive-1.0' on your Sun-4.  You may need to
     become `root' *briefly*, as in this example:

          eg-sparc-sun-solaris2$ su root
          password:
          # mkdir /usr/cygnus        (ignore ``File exists'' error if any)
          # chmod 777 /usr/cygnus
          # ln -s SHR/cygnus/progressive-1.0 /usr/cygnus/progressive-1.0
          # exit              root access not needed beyond this

     If you don't have access to any account with permission to write
     in `/usr', *note No Access to `/usr/cygnus': No access..

 12. Fix up system header files on your Sun-4, and test the
     installation, with the copy of `Install' that was placed in
     `SHR/cygnus/progressive-1.0':

          eg-sparc-sun-solaris2$ cd /usr/cygnus/progressive-1.0
          eg-sparc-sun-solaris2$ ./Install fixincludes test

     A log for the `fixincludes' step goes in
     `/usr/cygnus/progressive-1.0/fixincludes.log'.  *Your system's
     original header files are not changed;* `Install' writes the
     converted copies in a separate, GCC-specific directory.

        When each stage of this work is complete, `Install' displays
     these messages (the last, `Done.', simply indicates that `Install'
     has finished executing).

          Fixed include files installed!
          
          Cygnus Support software distribution tested!
          
          Done.

 13. Now that the software is on your system, you need to arrange for
     users to run it conveniently.  We recommend the following links;
     see *Note Links for Easy Access and Updating: Links, for a
     discussion.

          eg-sparc-sun-solaris2$ cd /usr/cygnus
          eg-sparc-sun-solaris2$ ln -s progressive-1.0 progressive
          
          eg-sparc-sun-solaris2$ su root      root privileges may be needed
          password:               to put link in /usr
          # ln -s /usr/cygnus/progressive/H-sparc-sun-solaris2 /usr/progressive
          # exit                  give up root privileges as soon as possible

 14. Finally, in case you need to send problem reports to Cygnus, we've
     included a script `send_pr' (and a supporting online form) to
     structure and transmit your reports.  Please use the script
     `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, +1 415 322 7836.)  This will enable us to respond as
     quickly as possible to any problem reports you send.

          eg$ /usr/cygnus/progressive-1.0/H-sparc-sun-solaris2/bin/install_cid ID
          install_cid: `ID' is now the default customer ID
           for send_pr

 15. We recommended permissions `777' for the `/usr/cygnus' and
     `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
     `/usr/cygnus' and `SHR/cygnus'.  See your System Administrator
     for the correct permissions at your site.

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


Installation Examples
**********************

   Once you've extracted `Install' from your tape, you can tell
`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
`Install' argument, *note Installation Options: Install-Options..

   `Install''s default tape drive is `/dev/rmt/0n', which is right for
the most common cases (QIC-24 tapes, read on Sun-4 systems).  If your
tape drive is different, you need to use the `-tape=/dev/TAPE' option;
the examples show this option for completeness.  Remember to specify a
*non-rewinding* tape device.



Installing binaries only
-------------------------

     eg$ ./Install -tape=/dev/TAPE bin

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


Reading tape on any machine, finishing on Sun-4
------------------------------------------------

     *On a machine on your network with a tape drive:*
     eg-tp$ ./Install -tape=/dev/TAPE -installdir=SHR/cygnus extract
     
     *On your Sun-4*
     eg$ ln -s SHR/cygnus /usr/cygnus
     eg$ cd /usr/cygnus/progressive-1.0
     eg$ ./Install fixincludes test

If your Sun-4 doesn't have a tape drive, but another machine that can
mount some shared directory 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 `extract' on the `Install' command
line.  This alerts `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 Sun-4.  (If you forget, there's no
great harm done: `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 `Install' notices a
problem like this, it doesn't carry out *any* action other than giving
a helpful error message).

   The `fixincludes' part of the installation is essential.  Please
see the full explanation (*note Why Convert System Header Files?:
Why-fixincludes.), if you're curious.


Removing Source
----------------

   The `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:

     eg$ cd /usr/cygnus/progressive-1.0
     eg$ ./Install remove source

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


Installation Options
*********************

   There are two kinds of command-line arguments to `Install', which
you can use to direct its operation:
   * *What form of the programs* to install.  You can choose among
     Sun-4 binaries (argument `bin') and source code (`source').  If
     you don't specify either of these, `Install' assumes you want
     both source, and binaries for Sun-4.

   * *What installation actions* to carry out.  A full installation
     involves up to three steps, and `Install' has options to let you
     choose them explicitly.  The steps are
       1. extracting source from the tape (option `extract')

       2. writing ANSI-C conforming copies of your system include
          files (needed for the compilation tools; option
          `fixincludes')

       3. running a simple test of the installed programs (option
          `test')

     The last two of these actions (`fixincludes' and `test') can only
     run on your Sun-4.  If you read the tape on another machine, you
     must specify the `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 Sun-4).

   `Install' also has two command line options: `-tape' and
`-installdir'.  You can use these to adapt the installation to your
system.

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

     Install [ -tape=/dev/TAPE ]
            [ -installdir=DIRECTORY ]
            [ bin ] [ source ]
            [ extract ] [ fixincludes ] [ test ]
            [ remove ]

`-tape=/dev/TAPE'
`-tape=TARFILE'
     Specify the *non-rewinding* device name for your tape drive as
     TAPE.

     If you extract the installation script and tarfile on some other
     system, and transfer them to your Sun-4 for installation, use use
     the name of the tarfile instead of a device name with `-tape'. 
     *Note No Local Tape Drive: No Drive, for more discussion.

`-installdir=DIRECTORY'
     If you have no write access to `/usr/cygnus' or `/usr', use this
     option to specify an alternate DIRECTORY for placing your
     software--but beware: the software is configured to go in
     `/usr/cygnus', and you'll have to override or change that too. 
     *Note Changing the Paths: Paths.

`bin'
`source'
     By default, `Install' extracts both source, and binaries for your
     Sun-4.  Instead of relying on the default, you can use these
     options to say exactly what forms you want.  You need to do this
     if
        * you want only binaries, or

        * you want only source.

     `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; `Install' arranges the files so
     that all hosts will share the same source files.  Documentation
     files are shared as well.  See *Note Links for Easy Access and
     Updating: Links, for a discussion of how to manage the directory
     structure used for this purpose.

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

     After you run `extract', `fixincludes' is essential if you're
     using the compiler.  `fixincludes' *does not change your system's
     original header files;* `Install' writes the converted copies in
     a separate, GCC-specific directory.  *Note Why Convert System
     Header Files?: Why-fixincludes, for more discussion of the
     `fixincludes' step.  `Install' will only attempt these last two
     steps if you run it on the Sun-4.

     `test' is a confidence-building step, and doesn't actually change
     the state of the installed software.  The `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
     `Install' on a different machine but try to run `fixincludes' or
     `test', `Install' will notice the error, and exit (before doing
     anything at all) with an error message, so you can try again.

     When you run `extract', `Install' leaves a log file `tar.log' in
     the installation directory--by default, in `/usr/cygnus'.  When
     you run `fixincludes', `Install' leaves a log file
     `fixincludes.log' in the `progressive-1.0' subdirectory.

`remove'
     You can also use `Install' to remove parts of the release after
     you've installed them.  Identify what to remove with either of the
     command-line options `source' or `bin'; if you specify `remove'
     as well, `Install' will try to erase parts of the installation
     from your system.  *Note Removing Parts of the Developer's Kit:
     Removing, for an example.



Why Convert System Header Files?
=================================

   It is very important to run `Install fixincludes' (on *each host*
where you install the compiler binaries).

   When the 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 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 ANSI C compiler for the operating system itself. 
`Install fixincludes' does a mechanical translation that writes ANSI C
versions of some system header files into a new, GCC-specific include
directory--*your system's original header files are not affected.*

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


Links for Easy Access and Updating
***********************************

   Once you've extracted them from the tape, the tools are installed
under a directory named `progressive-1.0'.  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
`/usr/cygnus/progressive' to this directory.  For example, assuming
you've used the default installation path:

     eg$ cd /usr/cygnus
     eg$ ln -s progressive-1.0 progressive

   Directories of host-independent files (source and documentation) are
installed directly under `progressive-1.0'.  However, to accomodate
binaries for multiple hosts in a single directory structure, the
binary files for your Sun-4 are in a subdirectory
`H-sparc-sun-solaris2'.

   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 Sun-4 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
`/usr/progressive/bin' on each machine so that it points to the
appropriate binary subdirectory for each machine--for instance,
`/usr/cygnus/progressive/H-sparc-sun-solaris2'.

   You may need to use `su' again briefly to establish these links:

     eg$ ln -s /usr/cygnus/progressive/H-sparc-sun-solaris2 /usr/progressive

   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 `/usr/progressive' when you're satisfied that the
installation is complete and successful.



Running the Programs
*********************

   Any users who wish to run the Cygnus development tools will need to
make sure the `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 Sun-4,
or for some other platform--can use settings like one of the following
in their initialization files.

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

For C shell:
     set path=(/usr/progressive/bin $path)

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

For Bourne-compatible shells:
     MANPATH=/usr/cygnus/progressive/man:$MANPATH:/usr/man
     export MANPATH

For C shell:
     setenv MANPATH /usr/cygnus/progressive/man:$MANPATH:/usr/man

   If your `man' program doesn't recognize `MANPATH', you may want to
copy or link the files from `progressive/man/man1' into your system's
`man/man1'.


Changing the Paths
*******************

   The binaries shipped by Cygnus are configured for installation
under the directory `/usr/cygnus'.  In particular, `gcc', `g++', and
the documentation browser `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:
   * use environment variables (and, for `g++', command-line options)
     to tell the tools where to find pieces of the installation; or

   * rebuild the tools from source, with your preferred paths built in. 
     *Note Rebuilding from Source: Rebuilding, if you want to take this
     approach.

   In rare circumstances, the auxiliary installation script
`install_cid' will also require a workaround if you do not install in
`/usr/cygnus'.

GCC Paths
---------

   You can run the compiler GCC without recompiling, even if you
install the distribution in an alternate location, by first setting the
environment variable `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 `/local' (instead of the default `/usr/cygnus'),
and you wish to run GCC as a native Sun-4 compiler, you could set
`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 `\' only to make it fit on the printed page.)

     GCC_EXEC_PREFIX=/local/progressive-1.0/H-sparc-sun-solaris2/\
     lib/gcc-lib/sparc-sun-solaris2/cygnus-2.0.2/
     export GCC_EXEC_PREFIX

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 `\' is only used for convenience in the
example; feel free to use a single line.)

     setenv GCC_EXEC_PREFIX /local/progressive-1.0/H-sparc-sun-solaris2/\
     lib/gcc-lib/sparc-sun-solaris2/cygnus-2.0.2/

     *Warning: The trailing slash `/' is important*.  The `gcc'
     program uses `GCC_EXEC_PREFIX' simply as a prefix.  If you omit
     the slash (or make any other mistakes in specifying the prefix),
     `gcc' will fail with a message beginning `installation problem,
     cannot exec...'.

G++ Paths
---------

   To compile C++ programs (when you've installed the binaries for the
compiler somewhere other than `/usr/cygnus'), you need to set
`GCC_EXEC_PREFIX' as for C programs.  You *also* need to include a
`-L' option and a `-I' option on the `g++' command line, to locate the
G++ specific header files and library.  For example, assuming you
installed the Sun-4 binaries under `/local', and want to compile a C++
program `program.cc':

  1. Set `GCC_EXEC_PREFIX' in one of the ways shown above;

  2. Invoke the `g++' compiler with at least the following options:

     eg$ g++ -L/local/progressive-1.0/H-sparc-sun-solaris2/lib\
     -I/local/progressive-1.0/H-sparc-sun-solaris2/lib/g++-include program.cc

`info' Paths
------------

   The standalone documentation browser `info' also needs to know the
location of its documentation files in the distribution.   The default
location, `/usr/cygnus/progressive-1.0/info', is compiled in.  If you
install elsewhere, set the environment variable `INFOPATH' to indicate
the alternate location.

   For example, again assuming you installed under `/local':

For shells compatible with Bourne shell (@code{/bin/sh}, @code{bash}, or Korn shell):
     INFOPATH=/local/progressive-1.0/info
     export INFOPATH

For C shell:
     setenv INFOPATH /local/progressive-1.0/info

If you built `progressive' as a symbolic link to `progressive-1.0', as
recommended in *Note Links for Easy Access and Updating: Links, then
you could simply use `/local/progressive/info' as the value of
`INFOPATH' in the examples above.

`install_cid' Paths
-------------------

   The auxiliary script `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 `send_pr' problem-reporting script.

   If you don't install in `/usr/cygnus', `install_cid ID' will still
work correctly in most cases.  However, there is one situation where
`install_cid' fails:

   * *if* your site already has a release tree for
     `/usr/cygnus/progressive-1.0',

   * *and* you run `Install' with an alternative installation
     directory.

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


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.



No Local Tape Drive
====================

   If your Sun-4 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:
*If a shared filesystem is available*
     between the two machines, and it has enough space, create
     `/usr/cygnus' on your Sun-4 (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 `Install' from the machine with a tape drive. 
     You'll have to run `Install fixincludes' and `Install test' from
     your Sun-4 afterwards; *note Installing with another machine's
     tape drive: cross-install..

*If some form of filetransfer is available*
     (such as `uucp'), read the tape using a system utility (for
     instance, `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 `Install' script,
     and the second is a compressed `tar' format file containing the
     rest of the release.  Read both of these files, and transfer them
     to your own machine.  Then run `Install' as shown in *Note
     Installing with a local tape drive: local-install, but use
     `-tape=TARFILE' to specify the name of the installation file,
     instead of `-tape=/dev/TAPE' as shown in the examples.  In the
     simplest case, for example (starting after you've transferred
     `Install' and the tar file to your system):

          eg$ ./Install -tape=TARFILE


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.

20 MB
     Sun-4 binaries

28 MB
     source code for all programs

48 MB
     Sun-4 total

   You can easily extract these components independently of one
another, by using the `source' or `bin' arguments to the `Install'
script provided on your release tape.  *Note Installation Options:
Install-Options.


No Access to `/usr/cygnus'
===========================

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

     *WARNING:* If you can't install in `/usr/cygnus' (or link your
     installation directory to that name), some of the defaults
     configured into the Progressive--1.0 distribution won't work. 
     *Note Changing the Paths: Paths, for information on overriding or
     reconfiguring these defaults.


Error Messages from `Install'
==============================

   The `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:
`Cannot read from TAPE device, TAPE'
     The error message ends with the tape device `Install' was trying
     to use.  Please check that it is the device you intended;
     possible causes of trouble might include leaving off the `/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; *note No Local Tape Drive: No Drive.,
     for a discussion of how to use another machine's tape drive.

`... This is a problem.'
`Cannot cd to INSTALLDIR'
`I do not know why I cannot create INSTALLDIR'
`hello.c fails to run'
`test-ioctl.c fails to run'
`I do not know how to remove an arch called ...'
     These errors (the first covers anything that ends in `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
        * *call the Cygnus hotline, +1 415 322 7836*, or

        * send electronic mail to `help@cygnus.com'.


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:
  1. configuration

  2. compilation

  3. installation

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

     eg$ cd progressive-1.0/src
     
     eg$ ./configure sparc-sun-solaris2 -prefix=/local/gnu
     Created "Makefile" in INSTALLDIR/progressive-1.0/src
     
     eg$ make clean all info install install-info >make.log
     ... output for `make' steps follows

We discuss each step in detail in the following sections.



Configuration
==============

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


Specifying Names for Hosts and Targets
=======================================

   The specifications used for hosts and targets in the `configure'
script are based on a three-part naming scheme, but some short
predefined aliases are also supported.  The full naming scheme encodes
three pieces of information in the following pattern:

     ARCHITECTURE-VENDOR-OS

   For example, you can use the alias `sun4' as a HOST argument or in
a `-target=TARGET' option, but the equivalent full name is
`sparc-sun-sunos4'.

     *Warning:* `configure' can represent a very large number of
     combinations of architecture, vendor, and OS.  There is by no
     means support for all possible combinations!


`configure' Options
====================

   This section summarizes the `configure' options and arguments. 
Your Developer's Kit contains full online documentation for the Cygnus
configure system.  *note : (configure.info)Using Configure, to read
about `configure' in more detail, including information on how the
`configure' options relate to `Makefile' variables.

     configure [-prefix=DEST]
               [-exec-prefix=BINDEST]
               [-srcdir=PATH]
               [-norecursion]
               [-target=TARGET]
               HOST

The binaries on your tape were configured using

     configure -prefix /usr/cygnus/progressive-1.0 \
       -exec-prefix /usr/cygnus/progressive-1.0/H-sparc-sun-solaris2 \
       sparc-sun-solaris2

`-prefix=DEST'
     DEST is an installation directory *path prefix*, the root for the
     directories where `make install' will place things.  After you
     configure with this option, `make install install-info' will
     install info files in `DEST/info', man pages in `DEST/man',
     and--unless you also use `-exec-prefix'--compiled programs in
     `DEST/bin', and libraries in `DEST/lib'.  If you specify
     `-prefix=/local', for example, `make install' puts the
     development tools in `/local/bin'.

     *WARNING:* the default DEST path prefix in the source is not the
     same as the prefix for the preconfigured binaries distributed by
     Cygnus.

     `-prefix=/usr/cygnus/progressive-1.0' was used to build this
     Cygnus Progressive Release.  If you do not use `-prefix', the
     installation directory is `/usr/local'.

`-exec-prefix=BINDEST'
     `-exec-prefix' serves the same purpose as `-prefix', but affects
     only machine-dependent targets (compiled programs and libraries).
      Specifying both `-prefix' and `-exec-prefix' allows you to
     segregate machine-dependent files, so that machine-independent
     files can be shared.

     *WARNING:* the default BINDEST path prefix in the source is not
     the same as the prefix for the preconfigured binaries distributed
     by Cygnus.

     `-exec-prefix=/usr/cygnus/progressive-1.0/H-sparc-sun-solaris2'
     was used to build this Cygnus Progressive Release.  If you do not
     use `-exec-prefix', the default directory for machine-dependent
     targets is whatever was specified with `-prefix' (by default,
     `/usr/local').

`-srcdir=PATH'
     *Warning: This option is only supported if you use GNU `make'*
     (which is included in the Cygnus Progressive--1.0 release).  Use
     this option to make configurations in directories separate from
     the source directories. `configure' writes configuration specific
     files in the current directory, but arranges for them to use the
     source in the directory PATH.  `configure' will create
     directories under the working directory in parallel to the source
     directories below PATH.  Among other things, you can use this to
     build (or maintain) several configurations simultaneously, in
     separate directories.

`-norecursion'
     Configure only the directory level where `configure' is executed;
     do not propagate configuration to subdirectories.

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

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

`HOST ...'
     Configure the development tools to run on the specified HOST.

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

   The `-prefix=DEST' and `-exec-prefix=BINDEST' options are
particularly important.  If you don't specify a DEST or BINDEST
directory, the `Makefile' installs binaries in subdirectories of
`/usr/local'.  These options are important because the DEST and
BINDEST directories are used for several purposes:

  1. BINDEST is the directory where binaries are installed.

  2. BINDEST is built into the compiler itself for the locations of
     GCC specific include files, the locations of GCC subprograms, and
     the location of the GCC specific library `libgcc.a'.

  3. DEST is compiled into `info' as the default directory for the
     documentation.



Compilation
============

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

     make all info >make.log

   The examples suggest capturing the `make' output in a `make.log'
file, because the output is lengthy.

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

     make CC=/local/gnu/H-sun4/bin/gcc CFLAGS=-O all info  >make.log

   The conventional targets `all', `install', and `clean' are
supported at all levels of `Makefile'.  Other targets are supported as
well, as appropriate in each directory; please read the individual
`Makefile' for details.  Each `Makefile' in the source directories
includes ample comments to help you read it.  If you are not familiar
with `make', refer to *Note Overview of `make': (make.info)Overview.


Installation
=============

   Whether you configure an alternative path using `-prefix', or you
use the default installation path `/usr/local', you can install the
software by executing:

     make install install-info


Removing Parts of the Developer's Kit
**************************************

   You can use the same `Install' script that was used to install the
Developer's Kit on your system, to remove parts of the release. 
(Remember that the `Install' script was automatically saved for you as
`/usr/cygnus/progressive-1.0/Install'.)

   To do this, decide what you want to remove; then call `Install'
with the option `remove' on the command line, as well as all the
options that you would use to install that portion of the release
(*note Installation Options: Install-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:

     eg$ cd /usr/cygnus/progressive-1.0
     eg$ ./Install remove source

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

     Cygnus Support software distribution removed!
     Done.

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


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:

   * Commercial support is available.  Cygnus adds value to FSF
     releases in large measure by offering outstanding support
     services.

   * 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.

   * 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.

   * Bug reporting.  Cygnus releases include the tool `send_pr', which
     you can use to make sure your problem reports receive prompt
     attention, and are also incorporated in our future tests.

   * Documentation.  Cygnus revises and adds to available FSF
     documentation to give you better descriptions of all the software
     tools.

   * Stability.  Cygnus tests (and uses) all the programs it releases.


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.

     Cygnus Support
     814 University Avenue
     Palo Alto, CA 94301, USA
     
     +1 415 322 3811
     hotline: +1 415 322 7836
     email: `info@cygnus.com'
     fax: +1 415 322 3270
