     START-INFO-DIR-ENTRY
     * intro: (intro.info).         An Introduction to Cygnus Releases
     END-INFO-DIR-ENTRY

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

This manual introduces the Cygnus Support Progressive Developer's Kit distribution.  For details, see the nodes below.

Cygnus Support Developer's Kit
******************************

This Developer's Kit release puts at your disposal, in a single coordinated and tested release, some of the best software development tools available. These tools are 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).

Cygnus Support has ported GNU tools to over sixty different platforms.  As part of our service, we integrate all our tools to ensure that they all work together.  Our developers use a regression testing method that checks not only for problems with a single tool, but across all the tools.  We check for problems that a change in one program may cause in another.  We don't ship your Developer's Kit release until we know it works.

The Developer's Kit contains these development tools and utilities:

(Not all tools are available for all platforms and operating systems.  See Overview (Release Notes), for specific information on your system.)

Compilers and Development Tools
-------------------------------

gcc
     C compiler

g++
     C++ compiler

gdb
     Debugger

as
     Assembler

gasp
     Assembler Preprocessor

ld
     Linker

Libraries
---------

libg++
     C++ class library

libio
     C++ iostreams library

libc
     ANSI C runtime library (only available for cross-development toolkits)

libm
     C mathematical subroutine library (only available for cross-development toolkits)

General Utilities
-----------------

byacc
     Parser generator

flex
     Fast lexical analyzer generator

make
     Compilation control program

diff
diff3
sdiff
     Compare text files

patch
     Installs source fixes

cmp
     Compares files byte-by-byte

send-pr
     Sends structured problem reports to Cygnus

install-sid
     Customizes send-pr for your site

gprof
     Performance analyzer (only available for Sun 4 systems running SunOS 4 or Solaris 2)

gcov
     Coverage analyzer

Binary Utilities
----------------

c++filt
     C++ symbol name deciphering utility

nm
     Lists object file symbol tables

objdump
     Displays object file information

size
     Lists section and total sizes

ar
     Manages object code archives

ranlib
     Generates archive index

strip
     Discards symbols

objcopy
     Copies and translates object files

Text Utilities
--------------

Texinfo (requires TeX)
texindex
texi2dvi
     Documentation formatting tools

makeinfo
info
     Online documentation tools

Manuals
*******

These manuals may be included in a hardcopy format in this Cygnus Support Progressive Release, depending on the nature of your support contract.  Note: hardcopy versions of the documentation are available as a separate product from Cygnus Support if your contract does not include printed manuals.  All documentation is included online with every release; see Using Online Documentation.

For convenience we have bound them in eight wire-bound volumes.

Cygnus Developer's Kit

       * Introduction

       * Release Notes

       * Install Notes

       * GNU General Public License

Embedded Systems

       * Embedded Systems Programming

Using GNU CC

       * Using GNU CC

Debugging With GDB

       * Debugging With GDB

Support Libraries

       * The GNU C++ Iostream Library

       * The Cygnus C Support Library

       * The Cygnus C Math Library

Binary Utilities

       * The GNU C Preprocessor

       * Using AS, the GNU Assembler

       * GASP, the GNU Assembler Preprocessor

       * Using LD, the GNU Linker

       * The GNU Binary Utilities

GNU Make

       * GNU Make

Developer's Kit Support

       * Reporting Problems Using send-pr

       * Online Documentation

       * Rebuilding From Source

       * Comparing and Merging Files (diff and patch)

Source for all documentation is also included.

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

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

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

BYacc
     A discussion of the Berkeley Yacc parser generator.

User's Guide to the GNU C++ Library
     Details about the general-purpose GNU C++ library, covered under the GNU Library General Public License.

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

Cygnus configure
     Details on the configuration program used in Cygnus releases.

GNU Coding Standards
     A complete discussion of the coding standards used by the GNU project.

On the Sun-3 and Sun-4 (SunOS 4.1 or Solaris 2) platforms, the following manual is also provided online:

GNU gprof
     Details on the GNU performance analyzer.

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 code for them is also available on the tape.

Conventions
-----------

Our manuals use these conventions to help you distinguish commands, filenames, and other program-specific objects from the descriptive text.

Typewriter-text
     Indicates text that is a literal example of a piece of a program, such as environmental variable names like EDITOR. It will also indicate keyboard characters you should type, or other literal bits of text from a program, such as filenames or examples.

key-name
     Indicates the conventional name for a special key on a keyboard, such as RET or DEL.

GENERIC-NAME
     Stands for another piece of text. For example, in the command description ``To delete the file named FILENAME, type rm FILENAME.''  FILENAME stands for the file you want to delete, no matter what you've named it.

Using Online Documentation
**************************

You can browse through the online documentation using either GNU Emacs or the documentation browser program info included in the Developer's Kit distribution.  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 this Developer's Kit 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

(You may need to check that info is in your shell path after you install the Developer's Kit release. If you have problems running info, please contact your systems administrator.)

To learn how to use info, type the command h for a programmed instruction sequence, or CTL-h for a short summary of commands.  If at any time you are ready to stop using info, type q.

See The Info Program (GNU Online Documentation), for detailed discussion of the info program.

Cygnus Support Online Library
-----------------------------

All of the manuals in our printed documentation set (see Manuals) are also available via the Cygnus Support Information Gallery, our World-Wide Web server, available at

     http://www.cygnus.com/

Contact Cygnus Support for information on connecting via the World-Wide Web.

As with all GNU software, the HTML source for our documents is available (or you can convert them yourself using publicly available utilities) if you wish to put them into an internal Web server for use at your facility.  Contact Cygnus Support for details, and please report any problems to the Cygnus documentation department at doc@cygnus.com.

Free Software Report
     The Free Software Report is a Cygnus publication dedicated to the business of supporting free software.

     Volume 1, Number 1: ``Free Software? Yes, Free Software''

     Volume 2, Number 1: ``Free Software And The Law''

     Volume 2, Number 2: ``Free Software Business Models''

     Volume 2, Number 3: ``Free Software: An Agent For Open Systems''

     Volume 3, Number 1: ``Testing, Testing, 1-2-3''

Inside Cygnus Engineering
     Inside Cygnus Engineering is a newsletter describing recent and upcoming activities in the Cygnus Support engineering division. We now have a complete archive of previous issues of Inside Cygnus Engineering.

Technical Reports
     Cygnus Support technical reports, written by Cygnus engineers.

     Security Issues in Embedded Networking

     Simple Garbage Collection in G++

     The GNU Instruction Scheduler

     Runtime Type Support in C and C++

Your Support Contract
*********************

GNU development tools provide a powerful, integrated applications development environment. Cygnus Support is one of the primary develpment centers for GNU tools; your support contract links you directly with the developers.  With this release, Cygnus Support has provided the latest fully-tested release of the GNU tools, preconfigured for your supported system.

Updates to your progressive release
-----------------------------------

Every quarter during the period of your support contract, Cygnus Support provides an updated toolchain, complete with the latest enhancements and improvements.  The updates also include bug fixes and updated documentation. Most customers receive these updates automatically; if you wish to get automatic updating, please call our support hotline at +1 415 903 1401.

You also receive a monthly newsletter, Inside Cygnus Engineering, which keeps you informed about release dates, improvements, new supported platforms, and new products.  We often request information about your needs via surveys in this newsletter.

Contacting Cygnus Support
-------------------------

You can reach Cygnus Support by email, phone, or fax.  To submit problem reports,

     Cygnus Support
     toll free: +1 800 CYGNUS-1
     main line: +1 415 903 1400
     hotline:   +1 415 903 1401
     email:   support@cygnus.com

     HEADQUARTERS                                    EAST COAST
     1937 Landings Drive                 48 Grove St., Ste. 105
     Mountain View, CA 94043 USA       Somerville, MA 02144 USA
     +1 415 903 1400                            +1 617 629 3000
     +1 415 903 0122 fax                    fax +1 617 629 3010

Faxes are answered 8 am--5pm, Monday through Friday.

Future Needs
------------

The availability of source code enables anyone to enhance the GNU tools.  While Cygnus is doing the greatest amount of ongoing development, many other users around the world are also contributing enhancements and improvments.  Cygnus integration and regression testing ensures that enhancements made elsewhere can work with Cygnus' developments.  As your needs evolve, so do the capabilities of the GNU tools and the support services available from Cygnus Support.

Reporting Trouble
*****************

We've tried to make the programs in this release of the Cygnus Support Developer's Kit as trouble-free as possible.  If you do encounter problems, however, we'd like 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 (PRs). send-pr comes with this release, and is easily configured to send reports back to Cygnus.

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 which editor to use (the default is vi). Emacs users will find PRMS especially easy to use.

For more information on send-pr, see Overview (Reporting Problems).

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

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

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

  * Describe only one problem per PR.

  * For follow-up mail, use the same subject line as the one in the automatic acknowledgment. It shows the category, the PR number and the original synopsis line.  This causes your mail to automatically be filed with the original bug report. Your followup comments will be sent to all the people who are working on the bug.

  * Please try to make the subject or synopsis line as informative as possible.  For misbehaving software, you might use a sentence of the form Encrypted rlogin hangs if you send interrupt or g++: calling wrong overloaded function.

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

Consult the Examples and guidelines for effective PRs (Reporting Problems), for more discussion on this topic.

Free Software
*************

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

In this release, we've assembled the most current editions of these software development tools, tested them, made sure they work well together, and made them easy to install. The installation tape comes with binaries already compiled for your system, and we've made them easy to reconfigure and recompile from source.

These tools are free software; they are part of the GNU project, produced by the Free Software Foundation (FSF).  ``GNU'' is the name of the FSF's evolving operating system (in speech, the `G' is sounded).  Cygnus Support collaborates with the FSF in developing these tools. (For more information on the relationship between Cygnus Support and the FSF, please see Cygnus Support and the FSF.)

Cygnus Support exists to help our clients exploit their freedom in using, adapting, or enhancing this software.  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 have access to the source code), and the freedom to distribute further copies.  Traditional 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, or the file COPYING in the top level of the source code distribution.

About Cygnus Support
********************

Cygnus Support, founded in 1989, provides commercial support for free software.  Why free software? Free software is fast, powerful, and more portable than its proprietary counterparts.  It evolves faster because users who want to make improvements are free to do so.

Cygnus Support has become the leading development organization of the GNU tools, contributing more than 50% of ongoing development. In addition to in-house development, Cygnus leverages the increasing cumulative pool of functionality available as public domain software on the Internet, creating a virtual community of developers. Building upon and contributing to this effort, Cygnus raises the level of functionality available to the entire industry.

The problem with free software has always been that your company's programmers and engineers must spend time maintaining the tools as well as using them, which ties up company resources. Cygnus frees up those resources by supplying products and services, which allows you to use state-of-the-art tools without the problems of maintenance. You can now choose to use free software and get the advantages of powerful and prompt support, combining the best of both.

Our team of experienced engineers include the leading architects for G++, GDB, GAS, and BFD. We use one of the most comprehensive bug-reporting and tracking software in the business, PRMS.

Because all our improvements are also free software, you can distribute them widely within your organization, or to your customers, without extra cost. No unwieldy licenses to manage, and no worries about buying extra copies.

Cygnus makes sure that our customers' problems get solved the right way. No grungy little programs, no klugey fixes that don't generalize, no work-arounds that end up being features instead of temporary situations.

     Cygnus Support
     toll free: +1 800 CYGNUS-1
     main line: +1 415 903 1400
     hotline:   +1 415 903 1401
     email:   support@cygnus.com

     HEADQUARTERS                                    EAST COAST
     1937 Landings Drive                 48 Grove St., Ste. 105
     Mountain View, CA 94043 USA       Somerville, MA 02144 USA
     +1 415 903 1400                            +1 617 629 3000
     +1 415 903 0122 fax                    fax +1 617 629 3010

Cygnus Support and the FSF
**************************

Cygnus Support and the Free Software Foundation cooperate on major projects, such as the port of the GNU development tools to Solaris 2.  We look forward to continuing such cooperation in the future.

Cygnus maintains many programs and libraries for the FSF: G++, GDB, GAS, the linker, GPROF, the binary utilities, LIBG++, and the Binary File Descriptor libraries.  In addition, Cygnus and the FSF share sources for other programs on a regular basis.

Both Cygnus and the FSF agree that free software is the best way to meet the industry's technical needs.  However, Cygnus and the FSF have different missions.  Cygnus, as a for-profit company, concentrates on meeting its customers' needs.  The FSF concentrates on meeting the internal needs of the GNU project.

Therefore, Cygnus may not accept into our source tree certain FSF changes until they are reworked into a form acceptable for our customers' needs---for example, changes that reduce performance or reliability on the software platforms we support.  Conversely, the FSF may not accept changes from Cygnus that improve support for only a limited group of users (Cygnus customers).

Also, Cygnus sometimes supports non-FSF code.  Our C subroutine library is an example.  The FSF's version carries licensing restrictions which are impractical for customers who write code for embedded systems; as a result, we developed our own subroutine library, LIBC.  The Cygnus C subroutine library, although also freely redistributable, does not carry the licensing restrictions that would inconvenience these customers.

Finally, although the FSF makes every effort to provide high-quality releases, its development requirements take priority.  The FSF regards software testing as the user community's contribution to the GNU project.  Cygnus releases go through a quality assurance cycle which is in large part driven by our knowledge of customer requirements.