Cygnus Support Solaris-2 Developer's Kit, version 1.0
******************************************************

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


Installation Procedure
***********************

   *To install the Cygnus Solaris-2 Developer's Kit, you need:*

   * the distribution files, `cygnus-sol2-1.0.bin.tar.Z' (if you want
     precompiled binaries) and `cygnus-sol2-1.0.src.tar.Z' (if you want
     the source code), in some directory DIST on your system

   * The Solaris-2 OS packages `SUNWesu', `SUNWhea', `SUNWbtool',
     `SUNWarc', and `SUNWtoo' installed on your system (try `pkginfo
     NAME').  See *Note Optional OS packages::.

   * at least 20 MB of disk space available for the binaries.  See
     *Note Disk space::.

   * at least 28 MB of disk space available for the source.  See *Note
     Disk space::.

   We suggest installing the Developer's Kit under `/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 `/opt/cygnus-sol2-1.0', see *Note Changing the Paths: Paths.

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

          eg$ touch /opt/cygnus-test; rm /opt/cygnus-test

     If you get an error, talk to your System Administrator about
     access to `/opt'.  If you can't get permission to write in `/opt',
     see *Note No Access to `/opt': No access.

  2. Extract the Developer's Kit binaries from the distribution file.

     *If you can install directly in `/opt':*
          eg$ cd /opt
          eg$ zcat DIST/cygnus-sol2-1.0.bin.tar.Z | tar xfov -

     *If you install in another directory OTHER:*
          eg$ cd OTHER
          eg$ zcat DIST/cygnus-sol2-1.0.bin.tar.Z | tar xfov -
          eg$ ln -s cygnus-sol2-1.0 /opt

  3. If you also want the source, repeat the previous step, but with
     the file `DIST/cygnus-sol2-1.0.src.tar.Z'.

  4. Fix up copies of the system header files for your SPARC computer,
     and test the installation, with the `Install' script that was
     extracted from the distribution.  *`Install' makes its own copies
     of the header files; your system's original header files are not
     changed.*

          eg$ cd cygnus-sol2-1.0
          eg$ ./Install
     `Install' displays messages about its activity, ending with
          Done.

     For background information on this step, see *Note Why Convert
     System Header Files?: Why-fixincludes.

  5. Make a symbolic link to simplify pathnames:
          eg$ cd /opt
          eg$ ln -s cygnus-sol2-1.0 cygnus


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


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:

gcc
     C compiler

libm.a
     Mathematical subroutine library

gdb
     Debugger

gprof
     Performance analyzer

byacc
     Parser generator

flex
     Fast lexical analyzer generator

makeinfo
info
     Online documentation tools

texinfo.tex
texindex
     Documentation printing tools

send_pr
     The Cygnus problem-reporting utility

patch
     Source-code update utility


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

*SPARC computers*
     All programs in your Developer's Kit are for SPARC computers
     running Solaris 2.0; we ship binaries (configured to install and
     run under `/opt/cygnus-sol2-1.0') 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
---------

   Solaris 2.0 Beta or later.


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 "packages") are installed on your
system: `SUNWesu' and `SUNWhea'.  Three more packages are needed to run
the Developer's Kit software after you've installed it: `SUNWbtool',
`SUNWtoo', and `SUNWarc'.

   To check whether an optional package is installed, you can run
`pkginfo NAME'.  `pkginfo' is in `/usr/bin/'.  If NAME is not
installed, you will get an error, like this:

     eg$ /usr/bin/pkginfo SUNWlibm
     ERROR: information for "SUNWlibm" was not found

If NAME is installed, you will see a one-line summary of the package,
like this:

     eg$ /usr/bin/pkginfo SUNWhea
     system      SUNWhea        Header Files

   To install one of these optional parts of Solaris 2 (NAME in the
example), put the Solaris 2.0 distribution CD in the drive, mount it
(for example, as `/cdrom'), then do:

     /usr/sbin/pkgadd -d /cdrom/Solaris_2.0 NAME ...

You can specify several package names at once.

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

`SUNWarc'
     *Needed to link your programs:* Archive libraries for system
     interfaces.

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

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

`SUNWhea'
     *Needed to complete installation and compile your programs:* Header
     files (`/usr/include').

`SUNWtoo'
     *Needed to link your programs:* "Programming Tools", notably the
     linker, `/usr/ccs/bin/ld'.

One additional optional package may be of interest:

`SUNWlibm'
     Sun's math subroutine library.  This is not required, however, as
     a free `libm.a' is part of the Developer's Kit.


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 `/opt/cygnus-sol2-1.0'.  If
you have space available, but not in the same file system as `/opt',
you can use `ln -s' to create `/opt/cygnus-sol2-1.0' as a symbolic link
to the file system where you do have the space available.


Write access
-------------

   You need write access to `/opt', or at least to an existing
`/opt/cygnus-sol2-1.0' directory.  If you can't write in `/opt' or
`/opt/cygnus-sol2-1.0', see *Note No Access to `/opt': No access.


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

   The command-line arguments and options to `Install' allow you to
direct its operation in these ways:

   * *What installation actions* to carry out:
       1. writing ANSI-C conforming copies of your system include files
          (needed for the compilation tools; option `fixincludes')

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

   * *Where you want to install*, with the `-installdir' option.

   Here is a summary of the `Install' command-line options, followed by
more detailed explanations:

     Install [ fixincludes ] [ test ]

`fixincludes'
`test'
     These steps are performed when you run `Install' without
     arguments, but if you like you can select either of them
     explicitly.

     After you extract the software, `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. See *Note Why
     Convert System Header Files?: Why-fixincludes, for more discussion
     of the `fixincludes' step.  `Install' will only attempt these two
     steps if you run it on the SPARC computer.

     `test' is a confidence-building step, and doesn't actually change
     the state of the installed software.

     When you run `fixincludes', `Install' leaves a log file
     `fixincludes.log' in the `cygnus-sol2-1.0' subdirectory.


Why Convert System Header Files?
*********************************

   It is very important to run the `fixincludes' step of installation
(either explicitly, as `Install fixincludes', or by default when you
run `Install' with no arguments).  You must do this on *each
installation*: if many SPARC computers share the same binaries on a
shared filesystem, you need only do it once--but if you install
separate copies, you must run `Install fixincludes' on each.

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

   GCC defines `__STDC__' to 1 when running with `-ansi', when it
functions as an "ANSI C superset" compiler.  (It also sets
`__STRICT_ANSI__' when it runs with the `-pedantic' option.) However,
GCC leaves `__STDC__' undefined when it is not running as an ANSI C
compiler.

   Unfortunately, the Solaris 2 header files follow the SVr4 choice. 
Since GCC never defines `__STDC__' as 0, the distributed header files
can leave out some declarations.  (Look in `/usr/include/time.h', for
example.)

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

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


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

   Anyone who wishes to run the Cygnus development tools will need to
make sure the `PATH' environment variable will find them.  The simplest
thing is to include `/opt/cygnus-sol2-1.0/bin' in the `PATH' variable. 
Since the directory name contains the release number `1.0', 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:

     eg$ cd /opt
     eg$ ln -s cygnus-sol2-1.0 cygnus

   Then people can use settings like these in initialization files:

For shells compatible with Bourne shell (`/bin/sh', `bash', or Korn shell):
     PATH=/opt/cygnus/bin:$PATH
     export PATH

For C shell:
     set path=(/opt/cygnus/bin $path)

You can also ensure that the `man' command can pick up the manual
pages, using the `MANPATH' environment variable.

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

For C shell:
     setenv MANPATH /opt/cygnus/man:$MANPATH


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

   The binaries shipped by Cygnus are configured for installation under
the directory `/opt/cygnus-sol2-1.0'.  In particular, `gcc' 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 to tell the tools where to find pieces
     of the installation; or

   * rebuild the tools from source, with your preferred paths built in.
     See *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
`/opt/cygnus-sol2-1.0'.

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

     GCC_EXEC_PREFIX=/local/cygnus-sol2-1.0/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/cygnus-sol2-1.0/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...'.

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

   The standalone documentation browser `info' also needs to know the
location of its documentation files in the distribution.   The default
location, `/opt/cygnus-sol2-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 (`/bin/sh', `bash', or Korn shell):
     INFOPATH=/local/cygnus-sol2-1.0/info
     export INFOPATH

For C shell:
     setenv INFOPATH /local/cygnus-sol2-1.0/info

`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 `/opt/cygnus-sol2-1.0', `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
     `/opt/cygnus-sol2-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 Access to `/opt'
====================

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

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

     eg$ su root
     password:           (enter root password)
     # mkdir SHR/cygnus-sol2-1.0      (ignore error if any)
     # chmod 777 SHR/cygnus-sol2-1.0
     # exit              root access not needed beyond this

If you do set write permissions to `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
`/opt' or `/opt/cygnus-sol2-1.0', use a different installation
directory, where you *can* write. You will also have to either override
default paths for the pre-compiled tools, or else recompile the
software.

     *WARNING:* If you can't install in `/opt/cygnus-sol2-1.0' (or link
     your installation directory to that name), some of the defaults
     configured into the cygnus-sol2-1.0 distribution won't work.  See
     *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.

   If you get one of these messages, please
   * send electronic mail to `help@cygnus.com'.


Rebuilding From Source
***********************

   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 `DIST/cygnus-sol2-1.0.src.tar.Z'.

   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 SPARC computer native version of all the tools in
a nonstandard directory:

     eg$ cd INSTALLDIR/src
     
     eg$ ./configure sparc-sun-solaris2 -prefix=/local/gnu
     Created "Makefile" in INSTALLDIR/src
     
     eg$ make clean all info install install-info

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 `sun4sol2' as a HOST argument or
in a `-target=TARGET' option, but the equivalent full name is
`sparc-sun-solaris2'.

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

     configure -prefix /opt/cygnus-sol2-1.0 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=/opt/cygnus-sol2-1.0' was used to build the binaries in
     this 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.

     No `-exec-prefix' was used to build the binaries in this 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'; for the binaries in this release,
     `/opt/cygnus-sol2-1.0').

`-srcdir=PATH'
     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.  (This option requires a `make' program with
     the `VPATH' feature, such as the one included with Solaris 2.)

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

   The `make' output is lengthy; consider redirecting it to a file.

   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

   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


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:

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

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

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

   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.


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
