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.

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

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

  * the distribution file, cygnus-sol2-||RELNO||.tar.Z, 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 Optional OS packages.

  * at least ||DF|| MB of disk space available.  See 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-||RELNO||, see Changing the 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 No Access to /opt.

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

          If you can install directly in /opt:
          eg$ cd /opt
          eg$ zcat DIST/cygnus-sol2-||RELNO||.tar.Z | tar xfov -

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

 3. Fix up copies of the system header files for your ||HOST||, 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-||RELNO||
          eg$ ./Install
          Install displays messages about its activity, ending with
          Done.

     For background information on this step, see Why Convert System Header Files?.

 4. Record your Cygnus customer-ID (see cover letter):

          eg$ /opt/cygnus-sol2-||RELNO||/bin/install_cid ID

 5. Make a symbolic link to simplify pathnames:

          eg$ cd /opt
          eg$ ln -s cygnus-sol2-||RELNO|| 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
===================

||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
     /opt/cygnus-sol2-||RELNO||) 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 ||DF|| megabytes.

The software is configured to go into /opt/cygnus-sol2-||RELNO||.  If you have
space available, but not in the same file system as /opt, you can
use ln -s to create /opt/cygnus-sol2-||RELNO|| 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-||RELNO|| directory.  If you can't write in
/opt or /opt/cygnus-sol2-||RELNO||, see No Access to /opt.

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 Why Convert System Header Files?, for more discussion of the fixincludes step.  Install will only attempt these two steps if you run it on the ||HOST||.

     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-||RELNO|| 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 ||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 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-||RELNO||/bin in the PATH variable.  Since the directory name contains the release number ||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:

     eg$ cd /opt
     eg$ ln -s cygnus-sol2-||RELNO|| 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-||RELNO||.  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 Rebuilding from Source, 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-||RELNO||.

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-||RELNO||/lib/gcc-lib/\
     ||HOSTstr||/||GCCvn||/
     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-||RELNO||/lib/gcc-lib/\
     ||HOSTstr||/||GCCvn||/

     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-||RELNO||/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-||RELNO||/info
     export INFOPATH

     For C shell:

     setenv INFOPATH /local/cygnus-sol2-||RELNO||/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-||RELNO||, 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-||RELNO||,

  * 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-||RELNO||      (ignore error if any)
     # chmod 777 SHR/cygnus-sol2-||RELNO||
     # 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-||RELNO||, 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-||RELNO|| (or link your installation directory to that name), some of the defaults configured into the cygnus-sol2-||RELNO|| distribution won't work.  See Changing the 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

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

     eg$ cd INSTALLDIR/src

     eg$ ./configure ||HOSTstr|| -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.  See Using Configure (configure.info), 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-||RELNO|| ||HOSTstr||

-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-||RELNO|| 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-||RELNO||).

-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 Overview of make (GNU Make: A Program for Directing Recompilation).

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