This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
New `gnucc.info' doc patch for gcc 2.95
- To: egcs-patches at egcs dot cygnus dot com
- Subject: New `gnucc.info' doc patch for gcc 2.95
- From: craig at jcb-sc dot com
- Date: 1 Jul 1999 07:27:02 -0000
- Cc: craig at jcb-sc dot com
Here's a proposed patch that adds a top-level Info document,
gnucc.info, to serve as an overview document of sorts for the
new GNU Compiler Collection (GCC).
It certainly needs a lot of filling out, to say the least.
Another issue is the naming. We saved ourselves a bit of hassle
by calling this new project GCC, but that turns out to be painful
wrt to the /usr/info/ directory, which already *has* a gcc.info,
which basically documents just gcc, g++, and gobjc. Where do users
find info on the *whole* GCC product?
After all, /usr/info/ is a *flat* directory, as far as users are
concerned. Maybe that wasn't the best design, but, for now, we're
stuck with it.
Well, for now, all I could think of was to call it gnucc.info.
Which turns out to be not so great, since, sometimes, gcc itself
is called "GNU CC", which naturally abbreviates to GNUCC.
So, the documentation for GCC is in gnucc.info, and the documentation
for GNU CC is in gcc.info.
Rather than try to solve this conundrum, I punted and went with the flow,
mainly just to try to get as much useful info into an overview document
before I left for my mini-vacation (Friday morning through Monday).
I'd like to see *at least* the chapter on Multilibs make it into gcc 2.95
somehow. It's based on an email exchange Robert Lipe and I had, well,
mostly his email to me containing info on multilibs. Couldn't see an
obvious place to insert it into the gcc.info outline, then it occurred
to me that we really could use an overview document, and maybe I could
throw one together in time for 2.95.
The reason multilibs needs to be described in 2.95 is that I believe
this is the first time they'll be widely seen in a product called "gcc",
if not in egcs 1.0 and 1.1. (Well, I know libf2c didn't support them
until 1.2. I think it was Robert who reminded me to document this new
feature in g77's docs.)
Also, maybe gnucc.texi should go into a subdir, like etc/ or maybe a
new one named doc/. I dunno. Just wanted to get this done. So I
cribbed gcc.texi, cut out a bunch of stuff, and generally whacked away
at it for the past few hours until it seemed adequate.
tq vm, (burley)
1999-07-01 Craig Burley <craig@jcb-sc.com>
* gnucc.texi: New file to document overall product.
* Makefile.in (gnucc.info): New rule to build new doc.
(info): Depend on gnucc.info rule.
(install-gnucc): New rule to install new doc.
($INSTALL_TARGET): Depend on install-gnucc rule.
(install-info): Depend on install-gnucc rule, even though
do-install-info rule currently dies in texinfo subdir.
*** g77-e/Makefile.in.~1~ Wed Jun 23 12:36:18 1999
--- g77-e/Makefile.in Thu Jul 1 03:15:59 1999
*************** REALLY_SET_LIB_PATH = \
*** 198,201 ****
--- 198,202 ----
ALL = all.normal
INSTALL_TARGET = installdirs \
+ install-gnucc \
install-gcc \
$(INSTALL_MODULES) \
*************** $(DO_X):
*** 1020,1037 ****
# Here are the targets which correspond to the do-X targets.
! .PHONY: info installcheck dvi install-info
.PHONY: clean distclean mostlyclean maintainer-clean realclean
.PHONY: local-clean local-distclean local-maintainer-clean
! info: do-info
installcheck: do-installcheck
dvi: do-dvi
# Make sure makeinfo is built before we do a `make info'.
do-info: all-texinfo
! install-info: do-install-info dir.info
s=`cd $(srcdir); pwd`; export s; \
if [ -f dir.info ] ; then \
$(INSTALL_DATA) dir.info $(infodir)/dir.info ; \
else true ; fi
--- 1021,1047 ----
# Here are the targets which correspond to the do-X targets.
! .PHONY: info installcheck dvi install-info install-gnucc
.PHONY: clean distclean mostlyclean maintainer-clean realclean
.PHONY: local-clean local-distclean local-maintainer-clean
! info: do-info gnucc.info
installcheck: do-installcheck
dvi: do-dvi
+ gnucc.info: all-texinfo gnucc.texi
+ $(MAKEINFO) $(MAKEINFOFLAGS) -I$(srcdir) -o gnucc.info $(srcdir)/gnucc.texi
+
# Make sure makeinfo is built before we do a `make info'.
do-info: all-texinfo
! install-info: do-install-info dir.info install-gnucc
s=`cd $(srcdir); pwd`; export s; \
if [ -f dir.info ] ; then \
$(INSTALL_DATA) dir.info $(infodir)/dir.info ; \
+ else true ; fi
+
+ install-gnucc: gnucc.info
+ s=`cd $(srcdir); pwd`; export s; \
+ if [ -f gnucc.info ] ; then \
+ $(INSTALL_DATA) gnucc.info $(infodir)/gnucc.info ; \
else true ; fi
*** g77-e/gnucc.texi.~1~ Thu Jul 1 00:29:17 1999
--- g77-e/gnucc.texi Thu Jul 1 03:10:19 1999
***************
*** 0 ****
--- 1,815 ----
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename gnucc.info
+
+ @set version-gnucc 2.95
+
+ @c (For FSF printing, turn on smallbook, comment out finalout below;
+ @c that is all that is needed.)
+
+ @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition.
+ @c @smallbook
+
+ @c i also commented out the finalout command, so if there *are* any
+ @c overfulls, you'll (hopefully) see the rectangle in the right hand
+ @c margin. -mew 15june93
+ @c @finalout
+
+ @c NOTE: checks/things to do:
+ @c
+ @c -have bob do a search in all seven files for "mew" (ideally --mew,
+ @c but i may have forgotten the occasional "--"..).
+ @c Just checked... all have `--'! Bob 22Jul96
+ @c Use this to search: grep -n '\-\-mew' *.texi
+ @c -item/itemx, text after all (sub/sub)section titles, etc..
+ @c -consider putting the lists of options on pp 17--> etc in columns or
+ @c some such.
+ @c -spellcheck
+ @c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi
+ @c -overfulls. do a search for "mew" in the files, and you will see
+ @c overfulls that i noted but could not deal with.
+ @c -have to add text: beginning of chapter 8
+
+ @c
+ @c anything else? --mew 10feb93
+
+ @settitle The GNU Compiler Collection (GCC)
+
+ @syncodeindex fn cp
+ @syncodeindex vr cp
+ @c %**end of header
+
+ @c Use with @@smallbook.
+
+ @c Cause even numbered pages to be printed on the left hand side of
+ @c the page and odd numbered pages to be printed on the right hand
+ @c side of the page. Using this, you can print on both sides of a
+ @c sheet of paper and have the text on the same part of the sheet.
+
+ @c The text on right hand pages is pushed towards the right hand
+ @c margin and the text on left hand pages is pushed toward the left
+ @c hand margin.
+ @c (To provide the reverse effect, set bindingoffset to -0.75in.)
+
+ @c @tex
+ @c \global\bindingoffset=0.75in
+ @c \global\normaloffset =0.75in
+ @c @end tex
+
+ @ifinfo
+ @dircategory Programming
+ @direntry
+ * gnucc: (gnucc). The GNU Compiler Collection (GCC).
+ @end direntry
+ This file documents the GNU Compiler Collection (GCC).
+
+ Published by the Free Software Foundation
+ 59 Temple Place - Suite 330
+ Boston, MA 02111-1307 USA
+
+ Copyright (C) 1999 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of
+ this manual provided the copyright notice and this permission notice
+ are preserved on all copies.
+
+ @ignore
+ Permission is granted to process this file through Tex and print the
+ results, provided the printed document carries copying permission
+ notice identical to this one except for the removal of this paragraph
+ (this paragraph not being relevant to the printed manual).
+
+ @end ignore
+ Permission is granted to copy and distribute modified versions of this
+ manual under the conditions for verbatim copying, provided also that the
+ sections entitled ``GNU General Public License'' and ``Funding for Free
+ Software'' are included exactly as in the original, and provided that
+ the entire resulting derived work is distributed under the terms of a
+ permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this manual
+ into another language, under the above conditions for modified versions,
+ except that the sections entitled ``GNU General Public License'' and
+ ``Funding for Free Software'', and this permission notice, may be
+ included in translations approved by the Free Software Foundation
+ instead of in the original English.
+ @end ifinfo
+
+ @setchapternewpage odd
+ @c @finalout
+ @titlepage
+ @center @titlefont{The GNU Compiler Collection (GCC)}
+
+ @sp 2
+ @center The EGCS Project
+ @sp 3
+ @center Last updated 1999-07-01
+ @sp 1
+
+ @center for version @value{version-gnucc}
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} 1999 Free Software Foundation, Inc.
+ @sp 2
+ For GCC Version @value{version-gnucc}@*
+ @sp 1
+ Published by the Free Software Foundation @*
+ 59 Temple Place - Suite 330@*
+ Boston, MA 02111-1307, USA@*
+ @c Last printed ???, 1999?.@*
+ @c Printed copies are available for $? each.@*
+ @c ISBN ???
+ @sp 1
+ Permission is granted to make and distribute verbatim copies of
+ this manual provided the copyright notice and this permission notice
+ are preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+ manual under the conditions for verbatim copying, provided also that the
+ sections entitled ``GNU General Public License'' and ``Funding for Free
+ Software'' are included exactly as in the original, and provided that
+ the entire resulting derived work is distributed under the terms of a
+ permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this manual
+ into another language, under the above conditions for modified versions,
+ except that the sections entitled ``GNU General Public License'' and
+ ``Funding for Free Software'', and this permission notice, may be
+ included in translations approved by the Free Software Foundation
+ instead of in the original English.
+ @end titlepage
+ @page
+
+ @ifinfo
+
+ @node Top, Components,, (DIR)
+ @top Introduction
+ @cindex introduction
+
+ This manual documents the GNU Compiler Collection (GCC).
+ It corresponds to GCC version @value{version-gnucc}.
+
+ @end ifinfo
+ @menu
+ * Components:: Components of GCC.
+ * Externals:: Components external to GCC.
+ * Concepts:: Concepts pertinent to GCC users.
+
+ * Funding:: How to help assure funding for free software.
+ * GNU/Linux:: Linux and the GNU Project
+
+ * Licensing:: Licensing terms for GCC.
+ * Contributors:: People who have contributed to GCC.
+
+ * Index:: Index of concepts and symbol names.
+ @end menu
+
+ @node Components
+ @chapter Components
+ @cindex components
+
+ The GNU Compiler Collection (GCC),
+ first introduced as @code{gcc} version 2.95,
+ includes the following major components:
+
+ @itemize @bullet
+ @item
+ The C-language family of compilers,
+ sometimes referred to collectively as GCC:
+
+ @itemize --
+ @item
+ @code{gcc}, the GNU CC compiler
+
+ @item
+ @code{g++}, the GNU C++ compiler
+
+ @item
+ The GNU Objective-C compiler
+ @end itemize
+
+ These three compilers are documented separately.
+ @xref{Top,,Top,
+ gcc.info, Using and Porting GCC}.
+
+ Subcomponents of this component of GCC include:
+
+ @itemize --
+ @item
+ @code{protoize}
+
+ @item
+ @code{unprotoize}
+
+ @item
+ @code{c++filt}
+ @end itemize
+
+ @code{protoize} and @code{unprotoize} also are documented
+ in the GCC manual.
+ @xref{Running Protoize,,Running Protoize,
+ gcc.info, Using and Porting GCC}.
+
+ @code{c++filt} is documented in the G++ FAQ.
+ @c ??? where exactly is this -- why not installed in infodir? -- jcb
+
+ @item
+ @code{g77}, the GNU Fortran compiler, documented separately.
+ @xref{Top,,Top,
+ g77.info, Using and Porting GNU Fortran}.
+
+ @item
+ @code{gcj}, the GNU Java compiler.
+ @c ??? no docs?!?
+
+ @item
+ @code{chill}, the GNU Chill compiler, documented separately.
+ @xref{Top,, Top,
+ chill.info, GNU Chill}.
+
+ @item
+ The GCC test suite.
+
+ @item
+ Run-time libraries:
+
+ @table @code
+ @item libchill
+ Supports GNU Chill (@code{chill}).
+
+ @item libf2c
+ Supports GNU Fortran (@code{g77}).
+
+ @item libio
+ Supports GNU C++ (@code{g++}).
+
+ @item libobjc
+ Supports GNU Objective-C.
+
+ @item libstdc++
+ Supports GNU C++ (@code{g++}).
+ @end table
+
+ @item
+ The @code{install} subdirectory,
+ which contains documentation on how to build and install GCC.
+
+ @item
+ Miscellaneous support subdirectories:
+
+ @table @code
+ @item config
+ Contains top-level configuration information on per-host and
+ per-target bases.
+
+ @item contrib
+ This subdirectory contains a variety of useful things,
+ like scripts to compare test-suite-run output.
+
+ @item etc
+ This subdirectory contains documentation
+ on designing, writing, and maintaining GNU products.
+ @xref{Preface,, Preface,
+ standards.info, GNU Coding Standards}.
+
+ @item include
+ This subdirectory contains @code{#include} files
+ for use by some other components of GCC.
+
+ @item libiberty
+ Supports various GCC components.
+
+ @item texinfo
+ A recent version of GNU @code{texinfo},
+ for the convenience of users who don't already have it on their system.
+ @xref{Texinfo,, Texinfo,
+ texinfo.info, Texinfo}.
+
+ This component is likely to be removed in a future version of GCC,
+ as @code{texinfo} is distributed with more and more operating systems.
+
+ @item xiberty
+ A mystery wrapped in a conundrum.
+ @end table
+ @end itemize
+
+ @node Externals
+ @chapter Externals
+
+ Other components that GCC depends upon, in some way,
+ but aren't distributed with GCC, include:
+
+ @itemize @bullet
+ @item
+ The operating-system environment needed to build, install,
+ and run GCC components, as well as
+ run programs generated via GCC.
+
+ This environment typically includes an operating-system kernel
+ (such as Linux),
+ C and other support libraries (such as @code{glibc}),
+ a shell (such as @code{bash})
+ for user and script-driven interaction with the system,
+ and other utitilies (such as @code{cp}, @code{mv}, @code{sed})
+ for use by the scripts distributed with GCC.
+
+ @item
+ @code{make}, which drives most of the process of
+ building and installing GCC.
+
+ @item
+ An @dfn{assembler} (such as @code{gas}, part of GNU @code{binutils}),
+ which GCC uses to perform the low-level conversion of
+ symbolic machine-level instructions to (binary) machine code
+ when creating @dfn{object files}.
+
+ @item
+ A @dfn{linker} (such as @code{gld}, also part of GNU @code{binutils}),
+ which GCC uses to link together object files into program
+ @dfn{executables}.
+ @end itemize
+
+ @node Concepts
+ @chapter Concepts
+ @cindex concepts
+
+ A few concepts pertain to GCC users of various sorts:
+
+ @itemize @bullet
+ @item
+ @emph{Developers}, who debug, modify, or build GCC itself.
+
+ @item
+ @emph{Installers}, who install GCC on computer systems.
+
+ @item
+ @emph{Programmers}, who use GCC to compile and link their programs.
+
+ @item
+ @emph{End users} of executables
+ (programs compiled and/or linked by GCC).
+ @end itemize
+
+ @menu
+ * Terminology::
+ * Dynamic Linking::
+ * Multilibs::
+ @end menu
+
+ @node Terminology
+ @section Terminology
+ @cindex terminology
+
+ Various terms are used throughout GCC documentation, diagnostics, and so on.
+ These include:
+
+ @table @dfn
+ @item build
+ @cindex build
+ The process of converting the @emph{source} code for a package
+ (such as GCC)
+ to the @emph{machine code} a given computer understands.
+
+ Used as a noun, this also refers to the system used to build GCC,
+ even if that version of GCC is intended to run on a different type of system
+ and/or generate code for yet another type of system.
+
+ @item host
+ @cindex host
+ This usually refers to the system
+ (or, more specifically, the @emph{type} of system)
+ upon which GCC itself is run to compile object files and link executables.
+
+ @item target
+ @cindex target
+ The system for which GCC is generating code
+ in the object files and executables it produces.
+ @end table
+
+ @node Dynamic Linking
+ @section Dynamic Linking
+ @cindex dynamic linking
+
+ Dynamic linking allows executables to invoke run-time-library code
+ that is not actually linked in to those executables.
+
+ Advantages of using dynamically linked libraries include:
+
+ @itemize @bullet
+ @item
+ Smaller executables, if more than one or two use the same library
+ or libraries.
+
+ @item
+ Automatic sharing of the actual code in the libraries
+ across multiple processes,
+ even if those processes are running different executables,
+ assuming the underlying operating system supports such automatic sharing.
+
+ @item
+ Easy upgrading of libraries.
+ A bug-fix to a library can be installed in the library code itself,
+ causing all executables that reference that library via dynamic linking
+ to invoke the new, bug-fix version,
+ without requiring relinking of each such executable.
+ @end itemize
+
+ Disadvantages include:
+
+ @itemize @bullet
+ @item
+ End users must invoke executables that use dynamic libraries
+ in environments consistent with those used to create the executables.
+
+ For example, the end user must have access to the actual library code
+ for a sample library named @code{libuser}
+ each time he invokes any executable linked to the dynamic version of
+ that library
+ (specifying @samp{-luser} at link time, for example).
+
+ @item
+ Developers of dynamically linked libraries must be extra careful
+ to ensure that no changes to the @dfn{signatures} of their libraries
+ are made as ``bug-fix'' updates.
+
+ A library's signature includes not only the names of globals,
+ and the return types, argument types, and so on of global functions,
+ but also some of the visible @emph{behavior} of those functions and globals.
+
+ Developers must be careful to not change this signature,
+ because, even if they account for such changes in the header
+ (sometimes called @code{#include}) files for the library,
+ such as by changing the code in inline functions, or the values
+ of C @code{enum} types,
+ @emph{existing} executables will not experience these changes,
+ but will try to link to the new library.
+
+ When such signature changes are made,
+ the new version of the library must be flagged
+ as one that cannot simply replace the previous library.
+
+ Usually, this is done by increasing a ``major version number'',
+ which tells the dynamic linker itself
+ to not consider linking an executable expecting major version 5 of a library
+ to major version 6 of its implementation,
+ for example.
+
+ Other mechanisms for protecting against this sort of problem
+ exist on various sorts of systems,
+ but the burden is always on the developer to @emph{identify}
+ when the signature of a library has changed in a way that
+ could possibly introduce bugs in @emph{existing} executables
+ when they are linked to the new, changed, library.
+ @end itemize
+
+ @node Multilibs
+ @section Multilibs
+ @cindex multilibs
+
+ @c The following text came straight from Robert Lipe
+ @c in an email to <craig@jcb-sc.com> dated Tue, 8 Jun 1999 01:30:47 -0500.
+ @c It was then edited and put into texinfo format by Craig Burley.
+ @c Thanks, Robert!!
+
+ Some GCC targets support multiple types of code generations.
+ These varying types are not always compatible with each other.
+ Reasons for different types of code generation include:
+
+ @itemize @bullet
+ @item
+ Different binary object file formats.
+
+ @item
+ Different code-generation conventions
+ (whether Position-Independent Code, or PIC, is generated, for example).
+
+ @item
+ Different naming conventions
+ (whether an underscore is prefixed to global names, for example).
+
+ @item
+ Different sizes for underlying data types
+ (which can offer compatibility for older object files, for example).
+
+ @item
+ Different formats for data types
+ (big-endian versus little-endian, for example).
+
+ @item
+ Different assumptions about instruction-set availability
+ (whether a Floating-Point Unit, or FPU, is available, for example).
+
+ @item
+ Different ranges of values for data types
+ (such as whether the full range of IEEE 754 floating-point values is supported,
+ or a range limited to that supported directly by the target's
+ arithmetic logic units when running at full speed).
+ @end itemize
+
+ GCC needs to be able to build the libraries it directly references
+ in all these forms so that it can always link against a compatible library.
+
+ This process of building and using multiple libraries
+ from a single GCC build is called ``multilibbing''.
+
+ @menu
+ * Programmer Multilibs:: How programmers and end users see multilibs.
+ * Developer Multilibs:: How developers and installers see multilibs.
+ * Target Multilibs:: Adding multilibs to a target.
+ * Library Multilibs:: Adding multilib support to a run-time library.
+ * Checking for Multilibs:: See whether a target supports multilibs.
+ * Testing Multilibs:: Testing a set of multilibs for a target.
+ @end menu
+
+ @node Programmer Multilibs
+ @subsection Programmer Multilibs
+
+ If things are working correctly, the multilib process
+ should be transparent to the programmer and to the end user.
+
+ Programmers can see it in action by
+ watching the subtle changes of the include and link lines
+ in the output of, for example, @code{gcc},
+ when the @samp{-v} (@samp{--verbose}) option is specified.
+
+ However, programmers must be careful to use @emph{consistent}
+ options when compiling @emph{and} linking their programs.
+ This does not always mean the same exact set of options,
+ but it does mean ensuring that the use of options that assume
+ executable-wide specification of those options are,
+ in fact, specified when compiling and linking @emph{all} code
+ for an executable,
+ or @emph{no} code.
+
+ End users shouldn't have to worry about multilibs at all.
+ However, problems can arise
+ when executables need dynamically linked libraries
+ and those libraries are not found in the proper place
+ due, for example, to an incorrect end-user environment.
+
+ @node Developer Multilibs
+ @subsection Developer Multilibs
+
+ To the GCC developer and installer,
+ multilibs offer a way to meet the needs of programmers and end users,
+ but they also make certain kinds of activities more painful.
+
+ For example,
+ multilib targets can be multiplicative,
+ so the number of combinations can grow exponentially.
+
+ It's important to be aware of
+ multilibs when working on a heavily multilibbed target,
+ because simple changes can result in hundreds or even thousands of recompiles
+ to rebuild support libraries.
+
+ GCC itself will build @file{libgcc.a} once for each multilib target.
+ (You can identify the targets via @samp{gcc -print-multi-lib}.)
+
+ All of the support libraries (@code{libchill}, @code{libf2c},
+ @code{libstdc++}, etc.)
+ also will be built once for each multilib target.
+
+ When debugging problems, it's important to note the exact
+ include paths and the exact libraries linked.
+ Use the @samp{-v} option,
+ when compiling @emph{and} when linking,
+ to see exactly what archives are being linked.
+ Debugging the wrong library can turn out to be a waste of time,
+ so it is wise to avoid doing that.
+ @samp{gcc -print-libgcc-file-name} can be helpful
+ in determining which library should be debugged.
+
+ @node Target Multilibs
+ @subsection Target Multilibs
+
+ To add multilibs to a target,
+ find a well-supported target that is multilibbed
+ (such as AIX, Iris 6, or SCO OpenServer)
+ and crib the configs from those hosts.
+ Search for @samp{MULTILIB_} in the @file{tm.h} and @file{t-*} files.
+
+ For example, on Iris 6,
+ all the multilib configuration is done in
+ @file{mips/iris6.h} and @file{t-iris6}.
+
+ @node Library Multilibs
+ @subsection Library Multilibs
+
+ To support multilibs in a library,
+ crib the code from a well-supported multilibbed library.
+ @code{libstdc++} is probably the most thoroughly invasive example.
+ @code{libobjc} is probably the simplest example.
+
+ It's actually pretty straightforward.
+ @file{configure.in} gets a handful of lines so it can add
+ magic to @file{Makefile} when it builds it from @file{Makefile.in}.
+
+ Various @file{Makefile} targets have to be changed
+ to invoke @samp{$(MULTIDO)} to loop over all the appropriate targets.
+ Search for @samp{multi} and @samp{MULTI}
+ and you'll at least be able to size the task.
+
+ @node Checking for Multilibs
+ @subsection Checking for Multilibs
+
+ To check whether a target is multilibbed,
+ check whether @samp{gcc -print-multi-lib}
+ (invoking @code{gcc} for that target)
+ prints more than @samp{.;}.
+ If it does, it prints the name of the additional multilib targets.
+
+ @node Testing Multilibs
+ @subsection Testing Multilibs
+
+ To test a set of multilibs for a target
+ using a single @samp{make check} command,
+ test these the same way as any other multi-pass testsuite run.
+ For example:
+
+ @smallexample
+ make RUNTESTFLAGS='--target_board "unix@{-fPIC,-mcoff,@}"' check
+ @end smallexample
+
+ This will run the testsuite three times.
+
+ @c End of Robert Lipe's initial contribution. Thanks again!!
+
+ @node Funding
+ @unnumbered Funding Free Software
+ @cindex funding
+
+ If you want to have more free software a few years from now, it makes
+ sense for you to help encourage people to contribute funds for its
+ development. The most effective approach known is to encourage
+ commercial redistributors to donate.
+
+ Users of free software systems can boost the pace of development by
+ encouraging for-a-fee distributors to donate part of their selling price
+ to free software developers---the Free Software Foundation, and others.
+
+ The way to convince distributors to do this is to demand it and expect
+ it from them. So when you compare distributors, judge them partly by
+ how much they give to free software development. Show distributors
+ they must compete to be the one who gives the most.
+
+ To make this approach work, you must insist on numbers that you can
+ compare, such as, ``We will donate ten dollars to the Frobnitz project
+ for each disk sold.'' Don't be satisfied with a vague promise, such as
+ ``A portion of the profits are donated,'' since it doesn't give a basis
+ for comparison.
+
+ Even a precise fraction ``of the profits from this disk'' is not very
+ meaningful, since creative accounting and unrelated business decisions
+ can greatly alter what fraction of the sales price counts as profit.
+ If the price you pay is $50, ten percent of the profit is probably
+ less than a dollar; it might be a few cents, or nothing at all.
+
+ Some redistributors do development work themselves. This is useful too;
+ but to keep everyone honest, you need to inquire how much they do, and
+ what kind. Some kinds of development make much more long-term
+ difference than others. For example, maintaining a separate version of
+ a program contributes very little; maintaining the standard version of a
+ program for the whole community contributes much. Easy new ports
+ contribute little, since someone else would surely do them; difficult
+ ports such as adding a new CPU to the GNU C compiler contribute more;
+ major new features or packages contribute the most.
+
+ By establishing the idea that supporting further development is ``the
+ proper thing to do'' when distributing free software for a fee, we can
+ assure a steady flow of resources into making more free software.
+
+ @display
+ Copyright (C) 1994 Free Software Foundation, Inc.
+ Verbatim copying and redistribution of this section is permitted
+ without royalty; alteration is not permitted.
+ @end display
+
+ @node GNU/Linux
+ @unnumbered Linux and the GNU Project
+
+ Many computer users run a modified version of the GNU system every
+ day, without realizing it. Through a peculiar turn of events, the
+ version of GNU which is widely used today is more often known as
+ ``Linux'', and many users are not aware of the extent of its
+ connection with the GNU Project.
+
+ There really is a Linux; it is a kernel, and these people are using
+ it. But you can't use a kernel by itself; a kernel is useful only as
+ part of a whole system. The system in which Linux is typically used
+ is a modified variant of the GNU system---in other words, a Linux-based
+ GNU system.
+
+ Many users are not fully aware of the distinction between the kernel,
+ which is Linux, and the whole system, which they also call ``Linux''.
+ The ambiguous use of the name doesn't promote understanding.
+
+ Programmers generally know that Linux is a kernel. But since they
+ have generally heard the whole system called ``Linux'' as well, they
+ often envisage a history which fits that name. For example, many
+ believe that once Linus Torvalds finished writing the kernel, his
+ friends looked around for other free software, and for no particular
+ reason most everything necessary to make a Unix-like system was
+ already available.
+
+ What they found was no accident---it was the GNU system. The available
+ free software added up to a complete system because the GNU Project
+ had been working since 1984 to make one. The GNU Manifesto
+ had set forth the goal of developing a free Unix-like system, called
+ GNU. By the time Linux was written, the system was almost finished.
+
+ Most free software projects have the goal of developing a particular
+ program for a particular job. For example, Linus Torvalds set out to
+ write a Unix-like kernel (Linux); Donald Knuth set out to write a text
+ formatter (TeX); Bob Scheifler set out to develop a window system (X
+ Windows). It's natural to measure the contribution of this kind of
+ project by specific programs that came from the project.
+
+ If we tried to measure the GNU Project's contribution in this way,
+ what would we conclude? One CD-ROM vendor found that in their ``Linux
+ distribution'', GNU software was the largest single contingent, around
+ 28% of the total source code, and this included some of the essential
+ major components without which there could be no system. Linux itself
+ was about 3%. So if you were going to pick a name for the system
+ based on who wrote the programs in the system, the most appropriate
+ single choice would be ``GNU''.
+
+ But we don't think that is the right way to consider the question.
+ The GNU Project was not, is not, a project to develop specific
+ software packages. It was not a project to develop a C compiler,
+ although we did. It was not a project to develop a text editor,
+ although we developed one. The GNU Project's aim was to develop
+ @emph{a complete free Unix-like system}.
+
+ Many people have made major contributions to the free software in the
+ system, and they all deserve credit. But the reason it is @emph{a
+ system}---and not just a collection of useful programs---is because the
+ GNU Project set out to make it one. We wrote the programs that were
+ needed to make a @emph{complete} free system. We wrote essential but
+ unexciting major components, such as the assembler and linker, because
+ you can't have a system without them. A complete system needs more
+ than just programming tools, so we wrote other components as well,
+ such as the Bourne Again SHell, the PostScript interpreter
+ Ghostscript, and the GNU C library.
+
+ By the early 90s we had put together the whole system aside from the
+ kernel (and we were also working on a kernel, the GNU Hurd, which runs
+ on top of Mach). Developing this kernel has been a lot harder than we
+ expected, and we are still working on finishing it.
+
+ Fortunately, you don't have to wait for it, because Linux is working
+ now. When Linus Torvalds wrote Linux, he filled the last major gap.
+ People could then put Linux together with the GNU system to make a
+ complete free system: a Linux-based GNU system (or GNU/Linux system,
+ for short).
+
+ Putting them together sounds simple, but it was not a trivial job.
+ The GNU C library (called glibc for short) needed substantial changes.
+ Integrating a complete system as a distribution that would work ``out
+ of the box'' was a big job, too. It required addressing the issue of
+ how to install and boot the system---a problem we had not tackled,
+ because we hadn't yet reached that point. The people who developed
+ the various system distributions made a substantial contribution.
+
+ The GNU Project supports GNU/Linux systems as well as @emph{the}
+ GNU system---even with funds. We funded the rewriting of the
+ Linux-related extensions to the GNU C library, so that now they are
+ well integrated, and the newest GNU/Linux systems use the current
+ library release with no changes. We also funded an early stage of the
+ development of Debian GNU/Linux.
+
+ We use Linux-based GNU systems today for most of our work, and we hope
+ you use them too. But please don't confuse the public by using the
+ name ``Linux'' ambiguously. Linux is the kernel, one of the essential
+ major components of the system. The system as a whole is more or less
+ the GNU system.
+
+ @node Licensing
+ @unnumbered Licensing Terms for GCC
+ @cindex licensing
+
+ GCC is generally distributed under the terms of the
+ GNU General Public License (GPL).
+
+ Some components of GCC are distributed under different licenses,
+ such as the GNU Library General Public License (LGPL).
+
+ Before distributing GCC, or a library or executable linked with
+ components of GCC (such as one or more of its run-time libraries),
+ check the pertinent licenses,
+ which are found in the source distribution of GCC.
+
+ @node Contributors
+ @unnumbered Contributors to GCC
+ @cindex contributors
+
+ This section needs work!
+
+ @node Index
+ @unnumbered Index
+
+ @printindex cp
+
+ @summarycontents
+ @contents
+ @bye