453 lines
14 KiB
Text
453 lines
14 KiB
Text
\input texinfo
|
|
@c $Id$
|
|
@setfilename intro.info
|
|
@settitle Introduction
|
|
@iftex
|
|
@c The include file "texiplus.tex" is in the texinfo/cygnus dir, and
|
|
@c implements Cygnus modifications to the texinfo manual style.
|
|
@input texiplus
|
|
@c The include file "smpklug.texi" is a kluge to deal with local
|
|
@c document production issues at Cygnus; it's safe to comment out this
|
|
@c line if you don't have (or don't want) the file.
|
|
@input smpklug.texi
|
|
@smallbook
|
|
@cropmarks
|
|
@finalout
|
|
@c We don't actually want a titlepage; HEADINGSon is usually called by
|
|
@c @end titlepage to turn on footers and headers.
|
|
@setchapternewpage odd
|
|
@HEADINGSon
|
|
@end iftex
|
|
|
|
@node Top,,,
|
|
@unnumbered Introduction
|
|
|
|
This Developer's Kit puts at your disposal, in a single coordinated
|
|
and tested release, some of the best software development tools
|
|
available:
|
|
|
|
@table @t
|
|
@item gcc
|
|
C compiler
|
|
|
|
@item g++
|
|
C++ compiler
|
|
|
|
@item gdb
|
|
Debugger
|
|
|
|
@item make
|
|
Automates building and installing your programs
|
|
|
|
@item gprof
|
|
Performance analyzer
|
|
|
|
@item byacc
|
|
Parser generator
|
|
|
|
@item flex
|
|
Fast lexical analyzer generator
|
|
|
|
@item libg++.a
|
|
Class library for C++
|
|
|
|
@item send_pr
|
|
Script to send structured problem reports to Cygnus
|
|
|
|
@item diff
|
|
Compares source files
|
|
|
|
@item patch
|
|
Installs source fixes
|
|
|
|
@item info
|
|
@itemx makeinfo
|
|
Online documentation tools
|
|
|
|
@item texinfo.tex
|
|
@itemx texindex
|
|
Documentation printing tools
|
|
@end table
|
|
|
|
On most host systems, the following are also included (to see if
|
|
they are available on your host, @pxref{Contents, Release Contents,
|
|
Release Contents, README.info, Installation Notes}).
|
|
|
|
@table @t
|
|
@item gas
|
|
Assembler
|
|
|
|
@item ld
|
|
Linker
|
|
|
|
@item ar
|
|
Manages object code archives
|
|
|
|
@item nm
|
|
Lists object file symbol tables
|
|
|
|
@item objdump
|
|
Displays object file information
|
|
|
|
@item ranlib
|
|
Generates archive index
|
|
|
|
@item size
|
|
Lists section and total sizes
|
|
|
|
@item strip
|
|
Discards symbols
|
|
@end table
|
|
|
|
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 @dfn{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. @xref{Cygnus,,About Cygnus
|
|
Support}, for more information.
|
|
|
|
@page
|
|
@node Copying,,,
|
|
@section 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 @dfn{free software}, protected by the @sc{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 @strong{LICENSE} section in this manual
|
|
set.
|
|
|
|
@page
|
|
@node Manuals,,,
|
|
@section Manuals
|
|
@noindent
|
|
These printed manuals are included in your Cygnus Progressive Release:
|
|
@display
|
|
|
|
@cite{Using the @sc{gnu} C Compiler}
|
|
|
|
@cite{The C Preprocessor}
|
|
|
|
@cite{GDB: The @sc{gnu} Source-Level Debugger}
|
|
|
|
@cite{Using @code{as}: The @sc{gnu} Assembler}
|
|
|
|
@cite{The @sc{gnu} Binary Utilities}
|
|
|
|
@cite{@code{gld}, the @sc{gnu} Linker}
|
|
|
|
@cite{@sc{gnu} Make: A Program for Directing Recompilation}
|
|
|
|
@cite{User's Guide to the @sc{GNU} C++ Class Library}
|
|
|
|
@end display
|
|
|
|
The manuals are designed for easy online browsing (@pxref{Info,,Online
|
|
Documentation}). For online use, the accompanying software distribution
|
|
tape includes all the printed manuals, and also the following documents:
|
|
|
|
@table @emph
|
|
@item FLEX: A Fast Lexical Analyzer Generator
|
|
Generates lexical analyzers suitable for GCC and other compilers.
|
|
|
|
@item Info: Documentation Browsing System
|
|
Full details on the @code{info} browser.
|
|
|
|
@item Texinfo: The @sc{gnu} Documentation Format
|
|
How you can use @TeX{} to print these manuals, and how to write your own
|
|
manuals in this style.
|
|
|
|
@item Using and Porting @sc{gnu cc}
|
|
Detailed information about what's needed to put @sc{gnu cc} on different
|
|
platforms, or to modify @sc{gnu cc}. Also includes all the
|
|
information in the printed manual @cite{Using the @sc{gnu} C Compiler}.
|
|
@end table
|
|
|
|
@noindent
|
|
Finally, @code{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.
|
|
|
|
@node Info,,,
|
|
@section Using Online Documentation
|
|
|
|
You can browse through the online documentation using either @sc{gnu} Emacs,
|
|
or the program @code{info} included on the accompanying tape.
|
|
Online, the manuals are organized into @dfn{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. @code{info} has ``hot''
|
|
references; if one section refers to another, you can tell @code{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 @code{info}. After the Progressive Release is installed on
|
|
your system, you can get into @code{info} by just typing its name---no
|
|
options or arguments are necessary---at your shell's prompt (shown as
|
|
@samp{eg%} here):
|
|
@example
|
|
eg% info
|
|
@end example
|
|
|
|
@noindent
|
|
@code{info} will display its first screen, a menu of the documentation
|
|
available, and will await your input. Typing the single letter
|
|
@example
|
|
h
|
|
@end example
|
|
@noindent
|
|
requests a tutorial, designed to teach you how to use @code{info}.
|
|
|
|
If you already use Emacs, you may want to get into the documentation
|
|
browsing mode, instead, by typing @kbd{C-h i} inside Emacs.
|
|
|
|
You can get out of @code{info} at any time by typing the single letter
|
|
@kbd{q}.
|
|
|
|
@page
|
|
Here is a summary of all the @code{info} commands; @code{info} itself
|
|
can display a summary like this at any time, when you type the single
|
|
character @kbd{?}.
|
|
|
|
@smallexample
|
|
@cartouche
|
|
h @r{Invoke the Info tutorial.}
|
|
q @r{Quit Info}
|
|
|
|
@i{Selecting other nodes:}
|
|
n @r{Move to the ``next'' node of this node.}
|
|
p @r{Move to the ``previous'' node of this node.}
|
|
u @r{Move ``up'' from this node.}
|
|
m @r{Pick menu item specified by name (or abbreviation).}
|
|
@r{Picking a menu item moves to the corresponding node.}
|
|
f @r{Follow a cross reference. Reads name of reference.}
|
|
l @r{Move to the last node you were looking at.}
|
|
|
|
@i{Moving within a node:}
|
|
Space @r{scroll forward a page.}
|
|
DEL @r{scroll backward a page.}
|
|
b @r{Go to beginning of this node.}
|
|
|
|
@i{Advanced commands:}
|
|
1 @r{Pick first item in node's menu.}
|
|
2 - 5 @r{Pick second ... fifth item in node's menu.}
|
|
g @r{Move to node specified by name.}
|
|
@r{You may include a filename as well, as @code{(@var{FILENAME})@var{NODENAME}}.}
|
|
s @r{Search through this Info file for a specified string,}
|
|
@r{and select the node in which the next occurrence is found.}
|
|
Ctl-p @r{Print the contents of this node using @samp{lpr}.}
|
|
@end cartouche
|
|
@end smallexample
|
|
|
|
@page
|
|
@node Bugs,,,
|
|
@section 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 @code{send_pr} to send us your
|
|
problem reports.
|
|
|
|
@code{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, @code{send_pr} sends the filled out form to the
|
|
problem report management system (PRMS) at Cygnus Support. You can
|
|
use the environment variable @code{EDITOR} to specify what editor to
|
|
use (the default is @code{vi}).
|
|
|
|
@code{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 @samp{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 @w{+1 415 322 3270}.
|
|
|
|
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
|
|
@code{send_pr} with the @samp{-request-id} option.
|
|
|
|
@page
|
|
@subsection 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:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Each PR needs a valid customer-id and category.
|
|
|
|
@item
|
|
Describe only one problem with one PR.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
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''.
|
|
|
|
@item
|
|
You don't need to delete the comment lines while editing the PR form;
|
|
this is done by @code{send_pr}. Put your information before or
|
|
after the comment.
|
|
@end itemize
|
|
|
|
@page
|
|
For full details on @code{send_pr} and the supporting form, see the man
|
|
page @code{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 @w{+1 415 322 3270}.
|
|
|
|
@iftex
|
|
@widen{28pt}
|
|
@end iftex
|
|
|
|
@smallexample
|
|
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)>
|
|
@end smallexample
|
|
|
|
@iftex
|
|
@widen{-28pt}
|
|
@end iftex
|
|
|
|
@page
|
|
@node Cygnus,,,
|
|
@section 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.
|
|
|
|
@sp 4
|
|
|
|
@display
|
|
Cygnus Support
|
|
814 University Avenue
|
|
Palo Alto, CA 94301, USA
|
|
|
|
+1 415 322 3811
|
|
|
|
email: @code{info@@cygnus.com}
|
|
fax: +1 415 322 3270
|
|
@end display
|
|
|
|
@bye
|