Initial revision
[external/binutils.git] / intro.texi
1 \input texinfo
2 @c $Id$
3 @setfilename intro.info
4 @settitle Introduction
5 @iftex
6 @c The include file "texiplus.tex" is in the texinfo/cygnus dir, and
7 @c implements Cygnus modifications to the texinfo manual style.
8 @input texiplus
9 @c The include file "smpklug.texi" is a kluge to deal with local
10 @c document production issues at Cygnus; it's safe to comment out this
11 @c line if you don't have (or don't want) the file.
12 @input smpklug.texi
13 @smallbook
14 @cropmarks
15 @finalout
16 @c We don't actually want a titlepage; HEADINGSon is usually called by
17 @c @end titlepage to turn on footers and headers.
18 @setchapternewpage odd
19 @HEADINGSon
20 @end iftex
21
22 @node Top,,,
23 @unnumbered Introduction
24
25 This Developer's Kit puts at your disposal, in a single coordinated
26 and tested release, some of the best software development tools
27 available:
28
29 @table @t
30 @item gcc
31 C compiler
32
33 @item g++
34 C++ compiler
35
36 @item gdb
37 Debugger
38
39 @item make
40 Automates building and installing your programs
41
42 @item gprof
43 Performance analyzer
44
45 @item byacc
46 Parser generator
47
48 @item flex
49 Fast lexical analyzer generator
50
51 @item libg++.a
52 Class library for C++
53
54 @item send_pr
55 Script to send structured problem reports to Cygnus
56
57 @item diff
58 Compares source files
59
60 @item patch
61 Installs source fixes
62
63 @item info
64 @itemx makeinfo
65 Online documentation tools
66
67 @item texinfo.tex
68 @itemx texindex
69 Documentation printing tools
70 @end table
71
72 On most host systems, the following are also included (to see if
73 they are available on your host, @pxref{Contents, Release Contents,
74 Release Contents, README.info, Installation Notes}).
75
76 @table @t
77 @item gas
78 Assembler
79
80 @item ld
81 Linker
82
83 @item ar
84 Manages object code archives
85
86 @item nm
87 Lists object file symbol tables
88
89 @item objdump
90 Displays object file information
91
92 @item ranlib
93 Generates archive index
94
95 @item size
96 Lists section and total sizes
97
98 @item strip
99 Discards symbols
100 @end table
101
102 These tools are free software; most of them are from the GNU project,
103 produced by the Free Software Foundation (FSF).  ``GNU'' is the name of
104 the FSF's evolving system (in speech, the `G' is sounded).  Cygnus
105 Support collaborates with the FSF in developing these tools.  In this,
106 our @dfn{Progressive} product, we've assembled the most recent forms of
107 the development tools, tested them, made sure they work well together,
108 made them easy to install---the installation tape comes with binaries
109 already compiled for your system---and made them easy to reconfigure and
110 recompile from source.
111
112 Cygnus Support exists to help our clients exploit their freedom in
113 using, adapting, or enhancing this software.  @xref{Cygnus,,About Cygnus
114 Support}, for more information.
115
116 @page
117 @node Copying,,,
118 @section Free Software
119 If you find our Developer's Kit useful, please feel free to give or sell
120 copies of the software and documentation to anyone you like.
121
122 Cygnus products are @dfn{free software}, protected by the @sc{gnu} General
123 Public License (GPL).  The GPL gives you the freedom to copy or adapt any
124 program it licenses---but every person getting a copy also gets with it the
125 freedom to modify that copy (which means that they must get access to
126 the source code), and the freedom to distribute further copies.  Typical
127 software companies use copyrights to limit your freedoms; the GPL is
128 designed to preserve your freedoms.
129
130 Fundamentally, the General Public License is a license which grants you
131 these freedoms, and only imposes restrictions to ensure that no one can
132 take these freedoms away from anyone else.
133
134 For full details, see the @strong{LICENSE} section in this manual
135 set.
136
137 @page
138 @node Manuals,,,
139 @section Manuals
140 @noindent
141 These printed manuals are included in your Cygnus Progressive Release:
142 @display
143
144 @cite{Using the @sc{gnu} C Compiler}
145
146 @cite{The C Preprocessor}
147
148 @cite{GDB: The @sc{gnu} Source-Level Debugger}
149
150 @cite{Using @code{as}: The @sc{gnu} Assembler}
151
152 @cite{The @sc{gnu} Binary Utilities}
153
154 @cite{@code{gld}, the @sc{gnu} Linker}
155
156 @cite{@sc{gnu} Make: A Program for Directing Recompilation}
157
158 @cite{User's Guide to the @sc{GNU} C++ Class Library}
159
160 @end display
161
162 The manuals are designed for easy online browsing (@pxref{Info,,Online
163 Documentation}).  For online use, the accompanying software distribution
164 tape includes all the printed manuals, and also the following documents:
165
166 @table @emph
167 @item FLEX: A Fast Lexical Analyzer Generator
168 Generates lexical analyzers suitable for GCC and other compilers.
169
170 @item Info: Documentation Browsing System
171 Full details on the @code{info} browser.
172
173 @item Texinfo: The @sc{gnu} Documentation Format
174 How you can use @TeX{} to print these manuals, and how to write your own
175 manuals in this style.
176
177 @item Using and Porting @sc{gnu cc}
178 Detailed information about what's needed to put @sc{gnu cc} on different
179 platforms, or to modify @sc{gnu cc}.  Also includes all the
180 information in the printed manual @cite{Using the @sc{gnu} C Compiler}.
181 @end table
182
183 @noindent
184 Finally, @code{man} pages are included for all the programs in the release.
185
186 You have the freedom to copy the manuals, like the software they cover;
187 each manual's copyright statement includes the necessary permissions.
188 The manuals themselves are also free software, and the source for them
189 is also available on the tape.
190
191 @node Info,,,
192 @section Using Online Documentation
193
194 You can browse through the online documentation using either @sc{gnu} Emacs,
195 or the program @code{info} included on the accompanying tape.
196 Online, the manuals are organized into @dfn{nodes}, which correspond to
197 the chapters and sections of a printed book.  You can follow them in
198 sequence, if you wish, just like in the printed book---but there are
199 also other choices.  The documents have menus that let you go quickly to
200 the node that has the information you need.  @code{info} has ``hot''
201 references; if one section refers to another, you can tell @code{info}
202 to take you immediately to that other section---and you can get back
203 again easily to take up your reading where you left off.  Naturally, you
204 can also search for particular words or phrases.
205
206 The best way to get started with the online documentation system is to
207 run the browser @code{info}.  After the Progressive Release is installed on
208 your system, you can get into @code{info} by just typing its name---no
209 options or arguments are necessary---at your shell's prompt (shown as
210 @samp{eg%} here):
211 @example
212 eg% info
213 @end example
214
215 @noindent
216 @code{info} will display its first screen, a menu of the documentation
217 available, and will await your input.  Typing the single letter
218 @example
219 h
220 @end example
221 @noindent
222 requests a tutorial, designed to teach you how to use @code{info}.
223
224 If you already use Emacs, you may want to get into the documentation
225 browsing mode, instead, by typing @kbd{C-h i} inside Emacs.
226
227 You can get out of @code{info} at any time by typing the single letter
228 @kbd{q}.  
229
230 @page
231 Here is a summary of all the @code{info} commands; @code{info} itself
232 can display a summary like this at any time, when you type the single
233 character @kbd{?}.
234
235 @smallexample
236 @cartouche
237 h       @r{Invoke the Info tutorial.}
238 q       @r{Quit Info}
239
240 @i{Selecting other nodes:}
241 n       @r{Move to the ``next'' node of this node.}
242 p       @r{Move to the ``previous'' node of this node.}
243 u       @r{Move ``up'' from this node.}
244 m       @r{Pick menu item specified by name (or abbreviation).}
245         @r{Picking a menu item moves to the corresponding node.}
246 f       @r{Follow a cross reference.  Reads name of reference.}
247 l       @r{Move to the last node you were looking at.}
248
249 @i{Moving within a node:}
250 Space   @r{scroll forward a page.}
251 DEL     @r{scroll backward a page.}
252 b       @r{Go to beginning of this node.}
253
254 @i{Advanced commands:}
255 1       @r{Pick first item in node's menu.}
256 2 - 5   @r{Pick second ... fifth item in node's menu.}
257 g       @r{Move to node specified by name.}
258         @r{You may include a filename as well, as @code{(@var{FILENAME})@var{NODENAME}}.}
259 s       @r{Search through this Info file for a specified string,}
260         @r{and select the node in which the next occurrence is found.}
261 Ctl-p   @r{Print the contents of this node using @samp{lpr}.}
262 @end cartouche
263 @end smallexample
264
265 @page
266 @node Bugs,,,
267 @section Reporting Trouble
268 We've tried to make the programs in your Progressive Release as
269 trouble-free as possible.  If you do encounter trouble, however, we'd
270 like to be able to diagnose and fix the problem as quickly as possible.
271 You can help us do that by using the script @code{send_pr} to send us your
272 problem reports.
273
274 @code{send_pr} invokes an editor on a problem report form (after
275 trying to fill in some fields with reasonable default values). After
276 you exit the editor, @code{send_pr} sends the filled out form to the
277 problem report management system (PRMS) at Cygnus Support.  You can
278 use the environment variable @code{EDITOR} to specify what editor to
279 use (the default is @code{vi}).
280
281 @code{send_pr} attempts to send your problem report to Cygnus via
282 electronic mail.  If your site cannot support this, you can still use
283 the problem report form: use @samp{send_pr -p} to capture a copy of the
284 blank problem-report form and fill it in.  (You can also photocopy the
285 blank form at the end of this section to fill in.)  In either case you
286 can FAX the problem report to Cygnus at @w{+1 415 322 3270}.
287
288 At Cygnus Support, the problem report is assigned a unique number and is
289 stored in the PRMS database according to its category and your
290 customer-id.  PRMS automatically replies with an acknowledgement, citing
291 the category and the PR number.  As the next step, Cygnus staff inspects
292 the bugreport (if you've marked your report as high priority, we respond
293 with an analysis of the problem in less than one business day).  We'll
294 offer a solution as soon as possible, and await your feedback.  As a
295 matter of policy, we do not consider your problem report closed until
296 you've agreed with a solution we offer.
297
298 To ensure that a problem report is handled promptly, it must contain
299 your (unique) customer-id and one of the available categories, shown as
300 comments in the problem report form, to identify the problem area. As a
301 Cygnus Support customer, you can obtain your customer-id by invoking
302 @code{send_pr} with the @samp{-request-id} option.
303
304 @page
305 @subsection Filling out a problem report
306 Problem reports are structured so that a program can manage them. When
307 filling out the form, please remember the following guidelines:
308
309 @itemize @bullet
310 @item
311 Each PR needs a valid customer-id and category.
312
313 @item
314 Describe only one problem with one PR.
315
316 @item
317 For follow-up mail, use the same subject line as the one in the
318 automatic acknowledgent. It shows the category, the PR number and the
319 original synopsis line.  This allows Cygnus Support to make sure mail on
320 the same problem report stays together.
321
322 @item 
323 Please try to make the subject or synopsis line as informative
324 as possible.  For misbehaving software, you might use a sentence of
325 the form ``with input foo, component xyz produces bar''.
326
327 @item
328 You don't need to delete the comment lines while editing the PR form;
329 this is done by @code{send_pr}.  Put your information before or
330 after the comment.
331 @end itemize
332
333 @page
334 For full details on @code{send_pr} and the supporting form, see the man
335 page @code{send_pr}(1).  Here is a sample blank problem-report form; if
336 electronic mail from your site does not reach Cygnus, you can send us
337 problem reports by photocopying this sample, filling it out, and sending
338 it by FAX to @w{+1 415 322 3270}.
339
340 @iftex
341 @widen{28pt}
342 @end iftex
343
344 @smallexample
345 SEND_PR: Choose from the following categories:
346 SEND_PR:
347 SEND_PR: bfd       binutils  bison     clib      config    cvs
348 SEND_PR: diff      doc       emacs     g++       gas       gcc       
349 SEND_PR: gdb       grep      ispell    ld        libg++    libiberty
350 SEND_PR: libiberty make      rcs       readline  send_pr   texinfo
351 SEND_PR: other
352 SEND_PR:
353
354 To: cygnus-bugs@@cygnus.com 
355
356 Subject: 
357
358 From: 
359
360 Reply-To: 
361
362 X-send-pr-version: send_pr: 1.15
363
364
365 >Customer-Id:
366
367 >Originator:    <name of the PR author (one line)>
368
369 >Organization:  <organization of PR author (multiple lines)>
370
371
372
373 >Confidential:  <[ yes | no ] (one line)>
374
375 >Synopsis:      <synopsis of the problem (one line)>
376
377 >Severity:      <[ non-critical | serious | critical ] (one line)>
378
379 >Priority:      <[ low | medium | high ] (one line)>
380
381 >Category:      <name of the product (one line)>
382
383 >Class:         <[ sw-bug | doc-bug | change-request | support ] (one line)>
384
385 >Release:       <release number or tag (one line)>
386
387 >Environment:
388         <machine, os, target, libraries (multiple lines)>
389
390
391
392 >Description:    
393         <precise description of the problem (multiple lines)>
394
395
396
397
398
399
400 >How-To-Repeat:  
401         <code/input/activities to reproduce the problem (multiple lines)>
402 @end smallexample
403
404 @iftex
405 @widen{-28pt}
406 @end iftex
407
408 @page
409 @node Cygnus,,,
410 @section About Cygnus Support
411 Cygnus Support was founded in 1989 to provide commercial support for
412 free software.  Cygnus supplies products and services that benefit
413 advanced development groups by allowing them to use state-of-the-art
414 tools without having to maintain them.  With Cygnus Support, sites that
415 once were forced to do their own tool support can recover that valuable
416 staff time.  Former users of proprietary software now may choose
417 supported free software, combining the advantages of both worlds.
418
419 Free software is faster, more powerful, and more portable than its
420 proprietary counterparts.  It evolves faster because users who want to
421 make improvements are free to do so.  Cygnus tracks these
422 improvements and integrates them into tested, stable versions ready
423 for commercial use, then backs this software with comprehensive
424 support.
425
426 With Cygnus Support as your partner, you will have the software and
427 the support you need to meet your business objectives.  Cygnus
428 is intimately familiar with this software from extensive experience
429 using, debugging, and implementing it.  You get direct access to the
430 most qualified support people: the authors of that software.
431
432 We provide up-to-the minute ``progressive'' releases, for those who need
433 the very latest version---or ``vintage'' releases: stable versions which
434 have been through extensive use and testing.
435
436 Because all our improvements are also free software, you can
437 distribute them widely within your organization, or to your customers,
438 without extra cost.
439
440 @sp 4
441
442 @display
443 Cygnus Support
444 814 University Avenue
445 Palo Alto, CA 94301, USA
446
447 +1 415 322 3811
448
449 email: @code{info@@cygnus.com}
450 fax: +1 415 322 3270
451 @end display
452
453 @bye