     START-INFO-DIR-ENTRY
     * Intro: (intro).		The Cygnus Support Developer's Kit
     END-INFO-DIR-ENTRY

Introduction
************

This Developer's Kit puts at your disposal, in a single coordinated and tested release, some of the best software development tools available:

gcc
     C compiler

g++
     C++ compiler

gdb
     Debugger

make
     Automates building and installing your programs

gprof
     Performance analyzer

byacc
     Parser generator

flex
     Fast lexical analyzer generator

libg++.a
     Class library for C++

send_pr
     Script to send structured problem reports to Cygnus

diff
     Compares source files

patch
     Installs source fixes

info
makeinfo
     Online documentation tools

texinfo.tex
texindex
     Documentation printing tools

The Developer's Kit is available for native development (where the same kind of system can run both the tools and the code you develop with them) and for cross-development (where one system, the host, runs the tools to develop software for another system, the target).

On cross-development configurations, and on some native configurations, the following are also included (to see if they are available on your host, see Release Contents (Installation Notes)).

gas
     Assembler

ld
     Linker

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

On cross-development configurations only, two C subroutine libraries are included:

libc.a
     C support library

libm.a
     C mathematical subroutine library

These tools are free software; most of them are from the GNU project, produced by the Free Software Foundation (FSF).  ``GNU'' is the name of the FSF's evolving system (in speech, the `G' is sounded).  Cygnus Support collaborates with the FSF in developing these tools.  In this, our Progressive product, we've assembled the most recent forms of the development tools, tested them, made sure they work well together, made them easy to install---the installation tape comes with binaries already compiled for your system---and made them easy to reconfigure and recompile from source.

Cygnus Support exists to help our clients exploit their freedom in using, adapting, or enhancing this software.  See About Cygnus Support, for more information.

Free Software
=============

If you find our Developer's Kit useful, please feel free to give or sell copies of the software and documentation to anyone you like.

Cygnus products are free software, protected by the GNU General Public License (GPL).  The GPL gives you the freedom to copy or adapt any program it licenses---but every person getting a copy also gets with it the freedom to modify that copy (which means that they must get access to the source code), and the freedom to distribute further copies.  Typical software companies use copyrights to limit your freedoms; the GPL is designed to preserve your freedoms.

Fundamentally, the General Public License is a license which grants you these freedoms, and only imposes restrictions to ensure that no one can take these freedoms away from anyone else.

For full details, see the LICENSE section in this manual set.

Manuals
=======

These printed manuals are included in your Cygnus Progressive Release:

     Using the GNU C Compiler

     The C Preprocessor

     The Cygnus C Support Library

     The Cygnus C Math Library

     GDB: The GNU Source-Level Debugger

     Using as: The GNU Assembler

     The GNU Binary Utilities

     gld, the GNU Linker

     GNU Make: A Program for Directing Recompilation

     User's Guide to the GNU C++ Class Library

The manuals are designed for easy online browsing (see Online Documentation).  For online use, the accompanying software distribution tape includes all the printed manuals, and also the following documents:

FLEX: A Fast Lexical Analyzer Generator
     Generates lexical analyzers suitable for GCC and other compilers.

Info: Documentation Browsing System
     Full details on the info browser.

Texinfo: The GNU Documentation Format
     How you can use TeX to print these manuals, and how to write your own manuals in this style.

Using and Porting GNU CC
     Detailed information about what's needed to put GNU CC on different platforms, or to modify GNU CC.  Also includes all the information in the printed manual Using the GNU C Compiler.

Finally, man pages are included for all the programs in the release.

You have the freedom to copy the manuals, like the software they cover; each manual's copyright statement includes the necessary permissions. The manuals themselves are also free software, and the source for them is also available on the tape.

Using Online Documentation
==========================

You can browse through the online documentation using either GNU Emacs, or the program info included on the accompanying tape. Online, the manuals are organized into nodes, which correspond to the chapters and sections of a printed book.  You can follow them in sequence, if you wish, just like in the printed book---but there are also other choices.  The documents have menus that let you go quickly to the node that has the information you need.  info has ``hot'' references; if one section refers to another, you can tell info to take you immediately to that other section---and you can get back again easily to take up your reading where you left off.  Naturally, you can also search for particular words or phrases.

The best way to get started with the online documentation system is to run the browser info.  After the Progressive Release is installed on your system, you can get into info by just typing its name---no options or arguments are necessary---at your shell's prompt (shown as eg% here):

     eg% info

info will display its first screen, a menu of the documentation available, and will await your input.  Typing the single letter

     h

requests a tutorial, designed to teach you how to use info.

If you already use Emacs, you may want to get into the documentation browsing mode, instead, by typing C-h i inside Emacs.

You can get out of info at any time by typing the single letter q.

Here is a summary of all the info commands; info itself can display a summary like this at any time, when you type the single character ?.

     h       Invoke the Info tutorial.
     q       Quit Info

     Selecting other nodes:
     n       Move to the ``next'' node of this node.
     p       Move to the ``previous'' node of this node.
     u       Move ``up'' from this node.
     m       Pick menu item specified by name (or abbreviation).
             Picking a menu item moves to the corresponding node.
     f       Follow a cross reference.  Reads name of reference.
     l       Move to the last node you were looking at.

     Moving within a node:
     Space   scroll forward a page.
     DEL     scroll backward a page.
     b       Go to beginning of this node.

     Advanced commands:
     1       Pick first item in node's menu.
     2 - 5   Pick second ... fifth item in node's menu.
     g       Move to node specified by name.
             You may include a filename as well, as (FILENAME)NODENAME.
     s       Search through this Info file for a specified string,
             and select the node in which the next occurrence is found.
     Ctl-p   Print the contents of this node using lpr.

Reporting Trouble
=================

We've tried to make the programs in your Progressive Release as trouble-free as possible.  If you do encounter trouble, however, we'd like to be able to diagnose and fix the problem as quickly as possible. You can help us do that by using the script send_pr to send us your problem reports.

send_pr invokes an editor on a problem report form (after trying to fill in some fields with reasonable default values). After you exit the editor, send_pr sends the filled out form to the problem report management system (PRMS) at Cygnus Support.  You can use the environment variable EDITOR to specify what editor to use (the default is vi).

send_pr attempts to send your problem report to Cygnus via electronic mail.  If your site cannot support this, you can still use the problem report form: use send_pr -p to capture a copy of the blank problem-report form and fill it in.  (You can also photocopy the blank form at the end of this section to fill in.)  In either case you can FAX the problem report to Cygnus at +1 415 903 0122.

At Cygnus Support, the problem report is assigned a unique number and is stored in the PRMS database according to its category and your customer-id.  PRMS automatically replies with an acknowledgement, citing the category and the PR number.  As the next step, Cygnus staff inspects the bugreport (if you've marked your report as high priority, we respond with an analysis of the problem in less than one business day).  We'll offer a solution as soon as possible, and await your feedback.  As a matter of policy, we do not consider your problem report closed until you've agreed with a solution we offer.

To ensure that a problem report is handled promptly, it must contain your (unique) customer-id and one of the available categories, shown as comments in the problem report form, to identify the problem area. As a Cygnus Support customer, you can obtain your customer-id by invoking send_pr with the -request-id option.

Filling out a problem report
----------------------------

Problem reports are structured so that a program can manage them. When filling out the form, please remember the following guidelines:

  * Each PR needs a valid customer-id and category.

  * Describe only one problem with one PR.

  * For follow-up mail, use the same subject line as the one in the automatic acknowledgent. It shows the category, the PR number and the original synopsis line.  This allows Cygnus Support to make sure mail on the same problem report stays together.

  * Please try to make the subject or synopsis line as informative as possible.  For misbehaving software, you might use a sentence of the form ``with input foo, component xyz produces bar''.

  * You don't need to delete the comment lines while editing the PR form; this is done by send_pr.  Put your information before or after the comment.

For full details on send_pr and the supporting form, see the man page send_pr(1).  Here is a sample blank problem-report form; if electronic mail from your site does not reach Cygnus, you can send us problem reports by photocopying this sample, filling it out, and sending it by FAX to +1 415 903 0122.

     SEND_PR: Choose from the following categories:
     SEND_PR:
     SEND_PR: bfd       binutils  bison     clib      config    cvs
     SEND_PR: diff      doc       emacs     g++       gas       gcc
     SEND_PR: gdb       grep      ispell    ld        libg++    libiberty
     SEND_PR: libiberty make      rcs       readline  send_pr   texinfo
     SEND_PR: other
     SEND_PR:

     To: cygnus-bugs@cygnus.com

     Subject:

     From:

     Reply-To:

     X-send-pr-version: send_pr: 1.15

     >Customer-Id:

     >Originator:    <name of the PR author (one line)>

     >Organization:  <organization of PR author (multiple lines)>

     >Confidential:  <[ yes | no ] (one line)>

     >Synopsis:	<synopsis of the problem (one line)>

     >Severity:	<[ non-critical | serious | critical ] (one line)>

     >Priority:	<[ low | medium | high ] (one line)>

     >Category: 	<name of the product (one line)>

     >Class:		<[ sw-bug | doc-bug | change-request | support ] (one line)>

     >Release:	<release number or tag (one line)>

     >Environment:
             <machine, os, target, libraries (multiple lines)>

     >Description:
             <precise description of the problem (multiple lines)>

     >How-To-Repeat:
             <code/input/activities to reproduce the problem (multiple lines)>

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 that software.

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

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
     hotline: +1 415 903 1401
     email: info@cygnus.com

     HEADQUARTERS                                    EAST COAST
     1937 Landings Drive                     One Kendall Square
     Mountain View, CA 94043 USA            Cambridge, MA 02139

     +1 415 903 1400                            +1 617 494 1040
     +1 415 903 0122 fax                    fax +1 617 494 1325