mirror/gcc
2
0
Fork 0
mirror of git://gcc.gnu.org/git/gcc.git synced 2025-03-09 00:07:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

gcc.texi: Move several chapters out to ...

Browse Source 
* doc/gcc.texi: Move several chapters out to ...
	* doc/configterms.texi, doc/fragments.texi, doc/hostconfig.texi,
	doc/include/linux-and-gnu.texi, doc/interface.texi,
	doc/makefile.texi, doc/passes.texi, doc/portability.texi:
	... here.  New files.
	* doc/gcc.texi, doc/contrib.texi: Move section headings into
	contrib.texi.
	* Makefile.in ($(docdir)/gcc.info, gcc.dvi): Update dependencies.

From-SVN: r46951
This commit is contained in:
Joseph Myers 2001-11-12 15:46:48 +00:00 committed by Joseph Myers
parent 285a5742c0
commit 73a8ed7ed4
12 changed files with 1506 additions and 1454 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
gcc/ChangeLog
View File

@ -1,3 +1,14 @@
2001-11-12 Joseph S. Myers <jsm28@cam.ac.uk>
* doc/gcc.texi: Move several chapters out to ...
* doc/configterms.texi, doc/fragments.texi, doc/hostconfig.texi,
doc/include/linux-and-gnu.texi, doc/interface.texi,
doc/makefile.texi, doc/passes.texi, doc/portability.texi:
... here. New files.
* doc/gcc.texi, doc/contrib.texi: Move section headings into
contrib.texi.
* Makefile.in ($(docdir)/gcc.info, gcc.dvi): Update dependencies.
2001-11-12 Kazu Hirata <kazu@hxi.com>
* config/alpha/alpha-interix.h: Fix comment formatting.

12
gcc/Makefile.in
View File

@ -2318,7 +2318,11 @@ $(docdir)/gcc.info: $(docdir)/gcc.texi $(docdir)/extend.texi \
$(docdir)/include/funding.texi $(docdir)/bugreport.texi \
$(docdir)/contribute.texi $(docdir)/frontends.texi \
$(docdir)/service.texi $(docdir)/standards.texi \
$(docdir)/trouble.texi $(docdir)/vms.texi
$(docdir)/trouble.texi $(docdir)/vms.texi $(docdir)/configterms.texi \
$(docdir)/fragments.texi $(docdir)/hostconfig.texi \
$(docdir)/include/linux-and-gnu.texi $(docdir)/interface.texi \
$(docdir)/makefile.texi $(docdir)/passes.texi \
$(docdir)/portability.texi
cd $(srcdir) && $(MAKEINFO) $(MAKEINFOFLAGS) -I doc -I doc/include -o doc/gcc.info doc/gcc.texi
$(docdir)/cppinternals.info: $(docdir)/cppinternals.texi
@ -2339,7 +2343,11 @@ gcc.dvi: $(docdir)/gcc.texi $(docdir)/extend.texi $(docdir)/install-old.texi \
$(docdir)/include/funding.texi $(docdir)/bugreport.texi \
$(docdir)/contribute.texi $(docdir)/frontends.texi \
$(docdir)/service.texi $(docdir)/standards.texi \
$(docdir)/trouble.texi $(docdir)/vms.texi
$(docdir)/trouble.texi $(docdir)/vms.texi $(docdir)/configterms.texi \
$(docdir)/fragments.texi $(docdir)/hostconfig.texi \
$(docdir)/include/linux-and-gnu.texi $(docdir)/interface.texi \
$(docdir)/makefile.texi $(docdir)/passes.texi \
$(docdir)/portability.texi
$(TEXI2DVI) -I $(docdir) -I $(docdir)/include $(docdir)/gcc.texi
cppinternals.dvi: $(docdir)/cppinternals.texi

65
gcc/doc/configterms.texi Normal file
View File

@ -0,0 +1,65 @@
@c Copyright (C) 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@section Configure Terms and History
@cindex configure terms
@cindex canadian
This section is not instructions for building GCC. If you are trying to
do a build, you should first read @uref{http://gcc.gnu.org/install/} or
whatever installation instructions came with your source package.
The configure and build process has a long and colorful history, and can
be confusing to anyone who doesn't know why things are the way they are.
While there are other documents which describe the configuration process
in detail, here are a few things that everyone working on GCC should
know.
There are three system names that the build knows about: the machine you
are building on (@dfn{build}), the machine that you are building for
(@dfn{host}), and the machine that GCC will produce code for
(@dfn{target}). When you configure GCC, you specify these with
@option{--build=}, @option{--host=}, and @option{--target=}.
Specifying the host without specifying the build should be avoided, as
@command{configure} may (and once did) assume that the host you specify
is also the build, which may not be true.
If build, host, and target are all the same, this is called a
@dfn{native}. If build and host are the same but target is different,
this is called a @dfn{cross}. If build, host, and target are all
different this is called a @dfn{canadian} (for obscure reasons dealing
with Canada's political party and the background of the person working
on the build at that time). If host and target are the same, but build
is different, you are using a cross-compiler to build a native for a
different system. Some people call this a @dfn{host-x-host},
@dfn{crossed native}, or @dfn{cross-built native}. If build and target
are the same, but host is different, you are using a cross compiler to
build a cross compiler that produces code for the machine you're
building on. This is rare, so there is no common say of describing it
(although I propose calling it a @dfn{crossback}).
If build and host are the same, the GCC you are building will also be
used to build the target libraries (like @code{libstdc++}). If build and host
are different, you must have already build and installed a cross
compiler that will be used to build the target libraries (if you
configured with @option{--target=foo-bar}, this compiler will be called
@command{foo-bar-gcc}).
In the case of target libraries, the machine you're building for is the
machine you specified with @option{--target}. So, build is the machine
you're building on (no change there), host is the machine you're
building for (the target libraries are built for the target, so host is
the target you specified), and target doesn't apply (because you're not
building a compiler, you're building libraries). The configure/make
process will adjust these variables as needed. It also sets
@code{$with_cross_host} to the original @option{--host} value in case you
need it.
Libiberty, for example, is built twice. The first time, host comes from
@option{--host} and the second time host comes from @option{--target}.
Historically, libiberty has not been built for the build machine,
though, which causes some interesting issues with programs used to
generate sources for the build. Fixing this, so that libiberty is built
three times, has long been on the to-do list.

4
gcc/doc/contrib.texi
View File

@ -3,6 +3,10 @@
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Contributors
@unnumbered Contributors to GCC
@cindex contributors
The GCC project would like to thank its many contributors. Without them the
project would not have been nearly as successful as it has been. Any omissions
in this list are accidental. Feel free to contact

159
gcc/doc/fragments.texi Normal file
View File

@ -0,0 +1,159 @@
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Fragments
@chapter Makefile Fragments
@cindex makefile fragment
When you configure GCC using the @file{configure} script
(@pxref{Installation}), it will construct the file @file{Makefile} from
the template file @file{Makefile.in}. When it does this, it will
incorporate makefile fragment files from the @file{config} directory,
named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
not exist, it means nothing needs to be added for a given target or
host.
@menu
* Target Fragment:: Writing the @file{t-@var{target}} file.
* Host Fragment:: Writing the @file{x-@var{host}} file.
@end menu
@node Target Fragment
@section The Target Makefile Fragment
@cindex target makefile fragment
@cindex @file{t-@var{target}}
The target makefile fragment, @file{t-@var{target}}, defines special
target dependent variables and targets used in the @file{Makefile}:
@table @code
@findex LIBGCC2_CFLAGS
@item LIBGCC2_CFLAGS
Compiler flags to use when compiling @file{libgcc2.c}.
@findex LIB2FUNCS_EXTRA
@item LIB2FUNCS_EXTRA
A list of source file names to be compiled or assembled and inserted
into @file{libgcc.a}.
@findex Floating Point Emulation
@item Floating Point Emulation
To have GCC include software floating point libraries in @file{libgcc.a}
define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
@smallexample
# We want fine grained libraries, so use the new code
# to build the floating point emulation libraries.
FPBIT = fp-bit.c
DPBIT = dp-bit.c
fp-bit.c: $(srcdir)/config/fp-bit.c
echo '#define FLOAT' > fp-bit.c
cat $(srcdir)/config/fp-bit.c >> fp-bit.c
dp-bit.c: $(srcdir)/config/fp-bit.c
cat $(srcdir)/config/fp-bit.c > dp-bit.c
@end smallexample
You may need to provide additional #defines at the beginning of @file{fp-bit.c}
and @file{dp-bit.c} to control target endianness and other options.
@findex CRTSTUFF_T_CFLAGS
@item CRTSTUFF_T_CFLAGS
Special flags used when compiling @file{crtstuff.c}.
@xref{Initialization}.
@findex CRTSTUFF_T_CFLAGS_S
@item CRTSTUFF_T_CFLAGS_S
Special flags used when compiling @file{crtstuff.c} for shared
linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
in @code{EXTRA-PARTS}.
@xref{Initialization}.
@findex MULTILIB_OPTIONS
@item MULTILIB_OPTIONS
For some targets, invoking GCC in different ways produces objects
that can not be linked together. For example, for some targets GCC
produces both big and little endian code. For these targets, you must
arrange for multiple versions of @file{libgcc.a} to be compiled, one for
each set of incompatible options. When GCC invokes the linker, it
arranges to link in the right version of @file{libgcc.a}, based on
the command line options used.
The @code{MULTILIB_OPTIONS} macro lists the set of options for which
special versions of @file{libgcc.a} must be built. Write options that
are mutually incompatible side by side, separated by a slash. Write
options that may be used together separated by a space. The build
procedure will build all combinations of compatible options.
For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
msoft-float}, @file{Makefile} will build special versions of
@file{libgcc.a} using the following sets of options: @option{-m68000},
@option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
@samp{-m68020 -msoft-float}.
@findex MULTILIB_DIRNAMES
@item MULTILIB_DIRNAMES
If @code{MULTILIB_OPTIONS} is used, this variable specifies the
directory names that should be used to hold the various libraries.
Write one element in @code{MULTILIB_DIRNAMES} for each element in
@code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
as spaces.
For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
@samp{m68000 m68020 msoft-float}. You may specify a different value if
you desire a different set of directory names.
@findex MULTILIB_MATCHES
@item MULTILIB_MATCHES
Sometimes the same option may be written in two different ways. If an
option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
items of the form @samp{option=option} to describe all relevant
synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
@findex MULTILIB_EXCEPTIONS
@item MULTILIB_EXCEPTIONS
Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
specified, there are combinations that should not be built. In that
case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
in shell case syntax that should not be built.
For example, in the PowerPC embedded ABI support, it is not desirable
to build libraries compiled with the @option{-mcall-aix} option
and either of the @option{-fleading-underscore} or @option{-mlittle} options
at the same time. Therefore @code{MULTILIB_EXCEPTIONS} is set to
@smallexample
*mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
@end smallexample
@findex MULTILIB_EXTRA_OPTS
@item MULTILIB_EXTRA_OPTS
Sometimes it is desirable that when building multiple versions of
@file{libgcc.a} certain options should always be passed on to the
compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
of options to be used for all builds.
@end table
@node Host Fragment
@section The Host Makefile Fragment
@cindex host makefile fragment
@cindex @file{x-@var{host}}
The host makefile fragment, @file{x-@var{host}}, defines special host
dependent variables and targets used in the @file{Makefile}:
@table @code
@findex CC
@item CC
The compiler to use when building the first stage.
@findex INSTALL
@item INSTALL
The install program to use.
@end table

1460
gcc/doc/gcc.texi
View File

File diff suppressed because it is too large Load Diff

240
gcc/doc/hostconfig.texi Normal file
View File

@ -0,0 +1,240 @@
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Config
@chapter The Configuration File
@cindex configuration file
@cindex @file{xm-@var{machine}.h}
The configuration file @file{xm-@var{machine}.h} contains macro
definitions that describe the machine and system on which the compiler
is running, unlike the definitions in @file{@var{machine}.h}, which
describe the machine for which the compiler is producing output. Most
of the values in @file{xm-@var{machine}.h} are actually the same on all
machines that GCC runs on, so large parts of all configuration files
are identical. But there are some macros that vary:
@table @code
@findex USG
@item USG
Define this macro if the host system is System V@.
@findex VMS
@item VMS
Define this macro if the host system is VMS@.
@findex FATAL_EXIT_CODE
@item FATAL_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits after serious errors. The default is the system-provided macro
@samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
macro. Define this macro only if these defaults are incorrect.
@findex SUCCESS_EXIT_CODE
@item SUCCESS_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits without serious errors. (Warnings are not serious errors.) The
default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
the system doesn't define that macro. Define this macro only if these
defaults are incorrect.
@findex HOST_WORDS_BIG_ENDIAN
@item HOST_WORDS_BIG_ENDIAN
Defined if the host machine stores words of multi-word values in
big-endian order. (GCC does not depend on the host byte ordering
within a word.)
@findex HOST_FLOAT_WORDS_BIG_ENDIAN
@item HOST_FLOAT_WORDS_BIG_ENDIAN
Define this macro to be 1 if the host machine stores @code{DFmode},
@code{XFmode} or @code{TFmode} floating point numbers in memory with the
word containing the sign bit at the lowest address; otherwise, define it
to be zero.
This macro need not be defined if the ordering is the same as for
multi-word integers.
@findex HOST_FLOAT_FORMAT
@item HOST_FLOAT_FORMAT
A numeric code distinguishing the floating point format for the host
machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
alternatives and default.
@findex HOST_BITS_PER_CHAR
@item HOST_BITS_PER_CHAR
A C expression for the number of bits in @code{char} on the host
machine.
@findex HOST_BITS_PER_SHORT
@item HOST_BITS_PER_SHORT
A C expression for the number of bits in @code{short} on the host
machine.
@findex HOST_BITS_PER_INT
@item HOST_BITS_PER_INT
A C expression for the number of bits in @code{int} on the host
machine.
@findex HOST_BITS_PER_LONG
@item HOST_BITS_PER_LONG
A C expression for the number of bits in @code{long} on the host
machine.
@findex HOST_BITS_PER_LONGLONG
@item HOST_BITS_PER_LONGLONG
A C expression for the number of bits in @code{long long} on the host
machine.
@findex ONLY_INT_FIELDS
@item ONLY_INT_FIELDS
Define this macro to indicate that the host compiler only supports
@code{int} bit-fields, rather than other integral types, including
@code{enum}, as do most C compilers.
@findex OBSTACK_CHUNK_SIZE
@item OBSTACK_CHUNK_SIZE
A C expression for the size of ordinary obstack chunks.
If you don't define this, a usually-reasonable default is used.
@findex OBSTACK_CHUNK_ALLOC
@item OBSTACK_CHUNK_ALLOC
The function used to allocate obstack chunks.
If you don't define this, @code{xmalloc} is used.
@findex OBSTACK_CHUNK_FREE
@item OBSTACK_CHUNK_FREE
The function used to free obstack chunks.
If you don't define this, @code{free} is used.
@findex USE_C_ALLOCA
@item USE_C_ALLOCA
Define this macro to indicate that the compiler is running with the
@code{alloca} implemented in C@. This version of @code{alloca} can be
found in the file @file{alloca.c}; to use it, you must also alter the
@file{Makefile} variable @code{ALLOCA}. (This is done automatically
for the systems on which we know it is needed.)
If you do define this macro, you should probably do it as follows:
@example
#ifndef __GNUC__
#define USE_C_ALLOCA
#else
#define alloca __builtin_alloca
#endif
@end example
@noindent
so that when the compiler is compiled with GCC it uses the more
efficient built-in @code{alloca} function.
@item FUNCTION_CONVERSION_BUG
@findex FUNCTION_CONVERSION_BUG
Define this macro to indicate that the host compiler does not properly
handle converting a function value to a pointer-to-function when it is
used in an expression.
@findex MULTIBYTE_CHARS
@item MULTIBYTE_CHARS
Define this macro to enable support for multibyte characters in the
input to GCC@. This requires that the host system support the ISO C
library functions for converting multibyte characters to wide
characters.
@findex POSIX
@item POSIX
Define this if your system is POSIX.1 compliant.
@findex PATH_SEPARATOR
@item PATH_SEPARATOR
Define this macro to be a C character constant representing the
character used to separate components in paths. The default value is
the colon character
@findex DIR_SEPARATOR
@item DIR_SEPARATOR
If your system uses some character other than slash to separate
directory names within a file specification, define this macro to be a C
character constant specifying that character. When GCC displays file
names, the character you specify will be used. GCC will test for
both slash and the character you specify when parsing filenames.
@findex DIR_SEPARATOR_2
@item DIR_SEPARATOR_2
If your system uses an alternative character other than
@samp{DIR_SEPARATOR} to separate directory names within a file
specification, define this macro to be a C character constant specifying
that character. If you define this macro, GCC will test for slash,
@samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
@findex TARGET_OBJECT_SUFFIX
@item TARGET_OBJECT_SUFFIX
Define this macro to be a C string representing the suffix for object
files on your target machine. If you do not define this macro, GCC will
use @samp{.o} as the suffix for object files.
@findex TARGET_EXECUTABLE_SUFFIX
@item TARGET_EXECUTABLE_SUFFIX
Define this macro to be a C string representing the suffix to be
automatically added to executable files on your target machine. If you
do not define this macro, GCC will use the null string as the suffix for
executable files.
@findex HOST_OBJECT_SUFFIX
@item HOST_OBJECT_SUFFIX
Define this macro to be a C string representing the suffix for object
files on your host machine (@samp{xm-*.h}). If you do not define this
macro, GCC will use @samp{.o} as the suffix for object files.
@findex HOST_EXECUTABLE_SUFFIX
@item HOST_EXECUTABLE_SUFFIX
Define this macro to be a C string representing the suffix for
executable files on your host machine (@samp{xm-*.h}). If you do not
define this macro, GCC will use the null string as the suffix for
executable files.
@findex HOST_BIT_BUCKET
@item HOST_BIT_BUCKET
The name of a file or file-like object on the host system which acts as
a ``bit bucket''. If you do not define this macro, GCC will use
@samp{/dev/null} as the bit bucket. If the target does not support a
bit bucket, this should be defined to the null string, or some other
invalid filename. If the bit bucket is not writable, GCC will use a
temporary file instead.
@findex COLLECT_EXPORT_LIST
@item COLLECT_EXPORT_LIST
If defined, @code{collect2} will scan the individual object files
specified on its command line and create an export list for the linker.
Define this macro for systems like AIX, where the linker discards
object files that are not referenced from @code{main} and uses export
lists.
@findex COLLECT2_HOST_INITIALIZATION
@item COLLECT2_HOST_INITIALIZATION
If defined, a C statement (sans semicolon) that performs host-dependent
initialization when @code{collect2} is being initialized.
@findex GCC_DRIVER_HOST_INITIALIZATION
@item GCC_DRIVER_HOST_INITIALIZATION
If defined, a C statement (sans semicolon) that performs host-dependent
initialization when a compilation driver is being initialized.
@findex UPDATE_PATH_HOST_CANONICALIZE
@item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
If defined, a C statement (sans semicolon) that performs host-dependent
canonicalization when a path used in a compilation driver or
preprocessor is canonicalized. @var{path} is a malloc-ed path to be
canonicalized. If the C statement does canonicalize @var{path} into a
different buffer, the old path should be freed and the new buffer should
have been allocated with malloc.
@end table
@findex bzero
@findex bcmp
In addition, configuration files for system V define @code{bcopy},
@code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
as a macro when compiled with GCC, in order to take advantage of the
benefit of GCC's built-in @code{alloca}.

102
gcc/doc/include/linux-and-gnu.texi Normal file
View File

@ -0,0 +1,102 @@
@c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@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.

102
gcc/doc/interface.texi Normal file
View File

@ -0,0 +1,102 @@
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Interface
@chapter Interfacing to GCC Output
@cindex interfacing to GCC output
@cindex run-time conventions
@cindex function call conventions
@cindex conventions, run-time
GCC is normally configured to use the same function calling convention
normally in use on the target system. This is done with the
machine-description macros described (@pxref{Target Macros}).
@cindex unions, returning
@cindex structures, returning
@cindex returning structures and unions
However, returning of structure and union values is done differently on
some target machines. As a result, functions compiled with PCC
returning such types cannot be called from code compiled with GCC,
and vice versa. This does not cause trouble often because few Unix
library routines return structures or unions.
GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
long in the same registers used for @code{int} or @code{double} return
values. (GCC typically allocates variables of such types in
registers also.) Structures and unions of other sizes are returned by
storing them into an address passed by the caller (usually in a
register). The machine-description macros @code{STRUCT_VALUE} and
@code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
By contrast, PCC on most target machines returns structures and unions
of any size by copying the data into an area of static storage, and then
returning the address of that storage as if it were a pointer value.
The caller must copy the data from that memory area to the place where
the value is wanted. This is slower than the method used by GCC, and
fails to be reentrant.
On some target machines, such as RISC machines and the 80386, the
standard system convention is to pass to the subroutine the address of
where to return the value. On these machines, GCC has been
configured to be compatible with the standard compiler, when this method
is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
@cindex argument passing
@cindex passing arguments
GCC uses the system's standard convention for passing arguments. On
some machines, the first few arguments are passed in registers; in
others, all are passed on the stack. It would be possible to use
registers for argument passing on any machine, and this would probably
result in a significant speedup. But the result would be complete
incompatibility with code that follows the standard convention. So this
change is practical only if you are switching to GCC as the sole C
compiler for the system. We may implement register argument passing on
certain machines once we have a complete GNU system so that we can
compile the libraries with GCC@.
On some machines (particularly the Sparc), certain types of arguments
are passed ``by invisible reference''. This means that the value is
stored in memory, and the address of the memory location is passed to
the subroutine.
@cindex @code{longjmp} and automatic variables
If you use @code{longjmp}, beware of automatic variables. ISO C says that
automatic variables that are not declared @code{volatile} have undefined
values after a @code{longjmp}. And this is all GCC promises to do,
because it is very difficult to restore register variables correctly, and
one of GCC's features is that it can put variables in registers without
your asking it to.
If you want a variable to be unaltered by @code{longjmp}, and you don't
want to write @code{volatile} because old C compilers don't accept it,
just take the address of the variable. If a variable's address is ever
taken, even if just to compute it and ignore it, then the variable cannot
go in a register:
@example
@{
int careful;
&careful;
@dots{}
@}
@end example
@cindex arithmetic libraries
@cindex math libraries
@opindex msoft-float
Code compiled with GCC may call certain library routines. Most of
them handle arithmetic for which there are no instructions. This
includes multiply and divide on some machines, and floating point
operations on any machine for which floating point support is disabled
with @option{-msoft-float}. Some standard parts of the C library, such as
@code{bcopy} or @code{memcpy}, are also called automatically. The usual
function call interface is used for calling the library routines.
Some of these routines can be defined in mostly machine-independent C;
they appear in @file{libgcc2.c}. Others must be hand-written in
assembly language for each processor. Wherever they are defined, they
are compiled into the support library, @file{libgcc.a}, which is
automatically searched when you link programs with GCC@.

104
gcc/doc/makefile.texi Normal file
View File

@ -0,0 +1,104 @@
@c Copyright (C) 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Makefile
@chapter Additional Makefile and configure information.
@section Makefile Targets
@cindex makefile targets
@cindex targets, makefile
@table @code
@item all
This is the default target. Depending on what your build/host/target
configuration is, it coordinates all the things that need to be built.
@item doc
Produce info-formatted documentation. Also, @code{make dvi} is
available for DVI-formatted documentation, and @code{make
generated-manpages} to generate man pages.
@item mostlyclean
Delete the files made while building the compiler.
@item clean
That, and all the other files built by @code{make all}.
@item distclean
That, and all the files created by @code{configure}.
@item extraclean
That, and any temporary or intermediate files, like emacs backup files.
@item maintainer-clean
Distclean plus any file that can be generated from other files. Note
that additional tools may be required beyond what is normally needed to
build gcc.
@item install
Installs gcc.
@item uninstall
Deletes installed files.
@item check
Run the testsuite. This creates a @file{testsuite} subdirectory that
has various @file{.sum} and @file{.log} files containing the results of
the testing. You can run subsets with, for example, @code{make check-gcc}.
You can specify specific tests by setting RUNTESTFLAGS to be the name
of the @file{.exp} file, optionally followed by (for some tests) an equals
and a file wildcard, like:
@example
make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
@end example
Note that running the testsuite may require additional tools be
installed, such as TCL or dejagnu.
@item bootstrap
Builds gcc three times---once with the native compiler, once with the
native-built compiler it just built, and once with the compiler it built
the second time. In theory, the last two should produce the same
results, which @code{make compare} can check. Each step of this process
is called a ``stage'', and the results of each stage @var{N}
(@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
@item bootstrap-lean
Like @code{bootstrap}, except that the various stages are removed once
they're no longer needed. This saves disk space.
@item bubblestrap
Once bootstrapped, this incrementally rebuilds each of the three stages,
one at a time. It does this by ``bubbling'' the stages up from their
subdirectories, rebuilding them, and copying them back to their
subdirectories. This will allow you to, for example, quickly rebuild a
bootstrapped compiler after changing the sources, without having to do a
full bootstrap.
@item quickstrap
Rebuilds the most recently built stage. Since each stage requires
special invocation, using this target means you don't have to keep track
of which stage you're on or what invocation that stage needs.
@item cleanstrap
Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
@item stage@var{N} (@var{N} = 1@dots{}4)
For each stage, moves the appropriate files to the @file{stage@var{N}}
subdirectory.
@item unstage@var{N} (@var{N} = 1@dots{}4)
Undoes the corresponding @code{stage@var{N}}.
@item restage@var{N} (@var{N} = 1@dots{}4)
Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
appropriate flags.
@item compare
Compares the results of stages 2 and 3. This ensures that the compiler
is running properly, since it should produce the same object files
regardless of how it itself was compiled.
@end table

663
gcc/doc/passes.texi Normal file
View File

@ -0,0 +1,663 @@
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Passes
@chapter Passes and Files of the Compiler
@cindex passes and files of the compiler
@cindex files and passes of the compiler
@cindex compiler passes and files
@cindex top level of compiler
The overall control structure of the compiler is in @file{toplev.c}. This
file is responsible for initialization, decoding arguments, opening and
closing files, and sequencing the passes.
@cindex parsing pass
The parsing pass is invoked only once, to parse the entire input. A
high level tree representation is then generated from the input,
one function at a time. This tree code is then transformed into RTL
intermediate code, and processed. The files involved in transforming
the trees into RTL are @file{expr.c}, @file{expmed.c}, and
@file{stmt.c}.
@c Note, the above files aren't strictly the only files involved. It's
@c all over the place (function.c, final.c,etc). However, those are
@c the files that are supposed to be directly involved, and have
@c their purpose listed as such, so i've only listed them.
The order of trees that are processed, is not
necessarily the same order they are generated from
the input, due to deferred inlining, and other considerations.
@findex rest_of_compilation
@findex rest_of_decl_compilation
Each time the parsing pass reads a complete function definition or
top-level declaration, it calls either the function
@code{rest_of_compilation}, or the function
@code{rest_of_decl_compilation} in @file{toplev.c}, which are
responsible for all further processing necessary, ending with output of
the assembler language. All other compiler passes run, in sequence,
within @code{rest_of_compilation}. When that function returns from
compiling a function definition, the storage used for that function
definition's compilation is entirely freed, unless it is an inline
function, or was deferred for some reason (this can occur in
templates, for example).
@ifset USING
(@pxref{Inline,,An Inline Function is As Fast As a Macro}).
@end ifset
@ifclear USING
(@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
@end ifclear
Here is a list of all the passes of the compiler and their source files.
Also included is a description of where debugging dumps can be requested
with @option{-d} options.
@itemize @bullet
@item
Parsing. This pass reads the entire text of a function definition,
constructing a high level tree representation. (Because of the semantic
analysis that takes place during this pass, it does more than is
formally considered to be parsing.)
The tree representation does not entirely follow C syntax, because it is
intended to support other languages as well.
Language-specific data type analysis is also done in this pass, and every
tree node that represents an expression has a data type attached.
Variables are represented as declaration nodes.
The language-independent source files for parsing are
@file{tree.c}, @file{fold-const.c}, and @file{stor-layout.c}.
There are also header files @file{tree.h} and @file{tree.def}
which define the format of the tree representation.
C preprocessing, for language front ends, that want or require it, is
performed by cpplib, which is covered in separate documentation. In
particular, the internals are covered in @xref{Top, ,Cpplib internals,
cppinternals, Cpplib Internals}.
@c Avoiding overfull is tricky here.
The source files to parse C are
@file{c-convert.c},
@file{c-decl.c},
@file{c-errors.c},
@file{c-lang.c},
@file{c-parse.in},
@file{c-aux-info.c},
and
@file{c-typeck.c},
along with a header file
@file{c-tree.h}
and some files shared with Objective-C and C++.
The source files for parsing C++ are in @file{cp/}.
They are @file{parse.y},
@file{class.c},
@file{cvt.c}, @file{decl.c}, @file{decl2.c},
@file{except.c},
@file{expr.c}, @file{init.c}, @file{lex.c},
@file{method.c}, @file{ptree.c},
@file{search.c}, @file{spew.c},
@file{semantics.c}, @file{tree.c},
@file{typeck2.c}, and
@file{typeck.c}, along with header files @file{cp-tree.def},
@file{cp-tree.h}, and @file{decl.h}.
The special source files for parsing Objective-C are in @file{objc/}.
They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}.
Certain C-specific files are used for this as well.
The files
@file{c-common.c},
@file{c-common.def},
@file{c-dump.c},
@file{c-format.c},
@file{c-pragma.c},
@file{c-semantics.c},
and
@file{c-lex.c},
along with header files
@file{c-common.h},
@file{c-dump.h},
@file{c-lex.h},
and
@file{c-pragma.h},
are also used for all of the above languages.
@cindex Tree optimization
@item
Tree optimization. This is the optimization of the tree
representation, before converting into RTL code.
@cindex inline on trees, automatic
Currently, the main optimization performed here is tree-based
inlining.
This is implemented for C++ in @file{cp/optimize.c}. Note that
tree based inlining turns off rtx based inlining (since it's more
powerful, it would be a waste of time to do rtx based inlining in
addition).
The C front end currently does not perform tree based inlining.
@cindex constant folding
@cindex arithmetic simplifications
@cindex simplifications, arithmetic
Constant folding and some arithmetic simplifications are also done
during this pass, on the tree representation.
The routines that perform these tasks are located in @file{fold-const.c}.
@cindex RTL generation
@item
RTL generation. This is the conversion of syntax tree into RTL code.
@cindex target-parameter-dependent code
This is where the bulk of target-parameter-dependent code is found,
since often it is necessary for strategies to apply only when certain
standard kinds of instructions are available. The purpose of named
instruction patterns is to provide this information to the RTL
generation pass.
@cindex tail recursion optimization
Optimization is done in this pass for @code{if}-conditions that are
comparisons, boolean operations or conditional expressions. Tail
recursion is detected at this time also. Decisions are made about how
best to arrange loops and how to output @code{switch} statements.
@c Avoiding overfull is tricky here.
The source files for RTL generation include
@file{stmt.c},
@file{calls.c},
@file{expr.c},
@file{explow.c},
@file{expmed.c},
@file{function.c},
@file{optabs.c}
and @file{emit-rtl.c}.
Also, the file
@file{insn-emit.c}, generated from the machine description by the
program @code{genemit}, is used in this pass. The header file
@file{expr.h} is used for communication within this pass.
@findex genflags
@findex gencodes
The header files @file{insn-flags.h} and @file{insn-codes.h},
generated from the machine description by the programs @code{genflags}
and @code{gencodes}, tell this pass which standard names are available
for use and which patterns correspond to them.
Aside from debugging information output, none of the following passes
refers to the tree structure representation of the function (only
part of which is saved).
@cindex inline on rtx, automatic
The decision of whether the function can and should be expanded inline
in its subsequent callers is made at the end of rtl generation. The
function must meet certain criteria, currently related to the size of
the function and the types and number of parameters it has. Note that
this function may contain loops, recursive calls to itself
(tail-recursive functions can be inlined!), gotos, in short, all
constructs supported by GCC@. The file @file{integrate.c} contains
the code to save a function's rtl for later inlining and to inline that
rtl when the function is called. The header file @file{integrate.h}
is also used for this purpose.
@opindex dr
The option @option{-dr} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.rtl} to
the input file name.
@c Should the exception handling pass be talked about here?
@cindex sibling call optimization
@item
Sibiling call optimization. This pass performs tail recursion
elimination, and tail and sibling call optimizations. The purpose of
these optimizations is to reduce the overhead of function calls,
whenever possible.
The source file of this pass is @file{sibcall.c}
@opindex di
The option @option{-di} causes a debugging dump of the RTL code after
this pass is run. This dump file's name is made by appending
@samp{.sibling} to the input file name.
@cindex jump optimization
@cindex unreachable code
@cindex dead code
@item
Jump optimization. This pass simplifies jumps to the following
instruction, jumps across jumps, and jumps to jumps. It deletes
unreferenced labels and unreachable code, except that unreachable code
that contains a loop is not recognized as unreachable in this pass.
(Such loops are deleted later in the basic block analysis.) It also
converts some code originally written with jumps into sequences of
instructions that directly set values from the results of comparisons,
if the machine has such instructions.
Jump optimization is performed two or three times. The first time is
immediately following RTL generation. The second time is after CSE,
but only if CSE says repeated jump optimization is needed. The
last time is right before the final pass. That time, cross-jumping
and deletion of no-op move instructions are done together with the
optimizations described above.
The source file of this pass is @file{jump.c}.
@opindex dj
The option @option{-dj} causes a debugging dump of the RTL code after
this pass is run for the first time. This dump file's name is made by
appending @samp{.jump} to the input file name.
@cindex register use analysis
@item
Register scan. This pass finds the first and last use of each
register, as a guide for common subexpression elimination. Its source
is in @file{regclass.c}.
@cindex jump threading
@item
@opindex fthread-jumps
Jump threading. This pass detects a condition jump that branches to an
identical or inverse test. Such jumps can be @samp{threaded} through
the second conditional test. The source code for this pass is in
@file{jump.c}. This optimization is only performed if
@option{-fthread-jumps} is enabled.
@cindex SSA optimizations
@cindex Single Static Assignment optimizations
@opindex fssa
@item
Static Single Assignment (SSA) based optimization passes. The
SSA conversion passes (to/from) are turned on by the @option{-fssa}
option (it is also done automatically if you enable an SSA optimization pass).
These passes utilize a form called Static Single Assignment. In SSA form,
each variable (pseudo register) is only set once, giving you def-use
and use-def chains for free, and enabling a lot more optimization
passes to be run in linear time.
Conversion to and from SSA form is handled by functions in
@file{ssa.c}.
@opindex de
The option @option{-de} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.ssa} to
the input file name.
@itemize @bullet
@cindex SSA Conditional Constant Propagation
@cindex Conditional Constant Propagation, SSA based
@cindex conditional constant propagation
@opindex fssa-ccp
@item
SSA Conditional Constant Propagation. Turned on by the @option{-fssa-ccp}
SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
option. This pass performs conditional constant propagation to simplify
instructions including conditional branches. This pass is more aggressive
than the constant propgation done by the CSE and GCSE pases, but operates
in linear time.
@opindex dW
The option @option{-dW} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.ssaccp} to
the input file name.
@cindex SSA DCE
@cindex DCE, SSA based
@cindex dead code elimination
@opindex fssa-dce
@item
SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
option. This pass performs elimination of code considered unnecessary because
it has no externally visible effects on the program. It operates in
linear time.
@opindex dX
The option @option{-dX} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.ssadce} to
the input file name.
@end itemize
@cindex common subexpression elimination
@cindex constant propagation
@item
Common subexpression elimination. This pass also does constant
propagation. Its source files are @file{cse.c}, and @file{cselib.c}.
If constant propagation causes conditional jumps to become
unconditional or to become no-ops, jump optimization is run again when
CSE is finished.
@opindex ds
The option @option{-ds} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.cse} to
the input file name.
@cindex global common subexpression elimination
@cindex constant propagation
@cindex copy propagation
@item
Global common subexpression elimination. This pass performs two
different types of GCSE depending on whether you are optimizing for
size or not (LCM based GCSE tends to increase code size for a gain in
speed, while Morel-Renvoise based GCSE does not).
When optimizing for size, GCSE is done using Morel-Renvoise Partial
Redundancy Elimination, with the exception that it does not try to move
invariants out of loops---that is left to the loop optimization pass.
If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
well as load motion.
If you are optimizing for speed, LCM (lazy code motion) based GCSE is
done. LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
based GCSE also does loop invariant code motion. We also perform load
and store motion when optimizing for speed.
Regardless of which type of GCSE is used, the GCSE pass also performs
global constant and copy propagation.
The source file for this pass is @file{gcse.c}, and the LCM routines
are in @file{lcm.c}.
@opindex dG
The option @option{-dG} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.gcse} to
the input file name.
@cindex loop optimization
@cindex code motion
@cindex strength-reduction
@item
Loop optimization. This pass moves constant expressions out of loops,
and optionally does strength-reduction and loop unrolling as well.
Its source files are @file{loop.c} and @file{unroll.c}, plus the header
@file{loop.h} used for communication between them. Loop unrolling uses
some functions in @file{integrate.c} and the header @file{integrate.h}.
Loop dependency analysis routines are contained in @file{dependence.c}.
@opindex dL
The option @option{-dL} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.loop} to
the input file name.
@item
@opindex frerun-cse-after-loop
If @option{-frerun-cse-after-loop} was enabled, a second common
subexpression elimination pass is performed after the loop optimization
pass. Jump threading is also done again at this time if it was specified.
@opindex dt
The option @option{-dt} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.cse2} to
the input file name.
@cindex data flow analysis
@cindex analysis, data flow
@cindex basic blocks
@item
Data flow analysis (@file{flow.c}). This pass divides the program
into basic blocks (and in the process deletes unreachable loops); then
it computes which pseudo-registers are live at each point in the
program, and makes the first instruction that uses a value point at
the instruction that computed the value.
@cindex autoincrement/decrement analysis
This pass also deletes computations whose results are never used, and
combines memory references with add or subtract instructions to make
autoincrement or autodecrement addressing.
@opindex df
The option @option{-df} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.flow} to
the input file name. If stupid register allocation is in use, this
dump file reflects the full results of such allocation.
@cindex instruction combination
@item
Instruction combination (@file{combine.c}). This pass attempts to
combine groups of two or three instructions that are related by data
flow into single instructions. It combines the RTL expressions for
the instructions by substitution, simplifies the result using algebra,
and then attempts to match the result against the machine description.
@opindex dc
The option @option{-dc} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.combine}
to the input file name.
@cindex if conversion
@item
If-conversion is a transformation that transforms control dependencies
into data dependencies (IE it transforms conditional code into a
single control stream).
It is implemented in the file @file{ifcvt.c}.
@opindex dE
The option @option{-dE} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.ce} to
the input file name.
@cindex register movement
@item
Register movement (@file{regmove.c}). This pass looks for cases where
matching constraints would force an instruction to need a reload, and
this reload would be a register to register move. It then attempts
to change the registers used by the instruction to avoid the move
instruction.
@opindex dN
The option @option{-dN} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.regmove}
to the input file name.
@cindex instruction scheduling
@cindex scheduling, instruction
@item
Instruction scheduling (@file{sched.c}). This pass looks for
instructions whose output will not be available by the time that it is
used in subsequent instructions. (Memory loads and floating point
instructions often have this behavior on RISC machines). It re-orders
instructions within a basic block to try to separate the definition and
use of items that otherwise would cause pipeline stalls.
Instruction scheduling is performed twice. The first time is immediately
after instruction combination and the second is immediately after reload.
@opindex dS
The option @option{-dS} causes a debugging dump of the RTL code after this
pass is run for the first time. The dump file's name is made by
appending @samp{.sched} to the input file name.
@cindex register class preference pass
@item
Register class preferencing. The RTL code is scanned to find out
which register class is best for each pseudo register. The source
file is @file{regclass.c}.
@cindex register allocation
@cindex local register allocation
@item
Local register allocation (@file{local-alloc.c}). This pass allocates
hard registers to pseudo registers that are used only within one basic
block. Because the basic block is linear, it can use fast and
powerful techniques to do a very good job.
@opindex dl
The option @option{-dl} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.lreg} to
the input file name.
@cindex global register allocation
@item
Global register allocation (@file{global.c}). This pass
allocates hard registers for the remaining pseudo registers (those
whose life spans are not contained in one basic block).
@cindex reloading
@item
Reloading. This pass renumbers pseudo registers with the hardware
registers numbers they were allocated. Pseudo registers that did not
get hard registers are replaced with stack slots. Then it finds
instructions that are invalid because a value has failed to end up in
a register, or has ended up in a register of the wrong kind. It fixes
up these instructions by reloading the problematical values
temporarily into registers. Additional instructions are generated to
do the copying.
The reload pass also optionally eliminates the frame pointer and inserts
instructions to save and restore call-clobbered registers around calls.
Source files are @file{reload.c} and @file{reload1.c}, plus the header
@file{reload.h} used for communication between them.
@opindex dg
The option @option{-dg} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.greg} to
the input file name.
@cindex instruction scheduling
@cindex scheduling, instruction
@item
Instruction scheduling is repeated here to try to avoid pipeline stalls
due to memory loads generated for spilled pseudo registers.
@opindex dR
The option @option{-dR} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.sched2}
to the input file name.
@cindex basic block reordering
@cindex reordering, block
@item
Basic block reordering. This pass implements profile guided code
positioning. If profile information is not available, various types of
static analysis are performed to make the predictions normally coming
from the profile feedback (IE execution frequency, branch probability,
etc). It is implemented in the file @file{bb-reorder.c}, and the
various prediction routines are in @file{predict.c}.
@opindex dB
The option @option{-dB} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.bbro} to
the input file name.
@cindex cross-jumping
@cindex no-op move instructions
@item
Jump optimization is repeated, this time including cross-jumping
and deletion of no-op move instructions.
@opindex dJ
The option @option{-dJ} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.jump2}
to the input file name.
@cindex delayed branch scheduling
@cindex scheduling, delayed branch
@item
Delayed branch scheduling. This optional pass attempts to find
instructions that can go into the delay slots of other instructions,
usually jumps and calls. The source file name is @file{reorg.c}.
@opindex dd
The option @option{-dd} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.dbr}
to the input file name.
@cindex branch shortening
@item
Branch shortening. On many RISC machines, branch instructions have a
limited range. Thus, longer sequences of instructions must be used for
long branches. In this pass, the compiler figures out what how far each
instruction will be from each other instruction, and therefore whether
the usual instructions, or the longer sequences, must be used for each
branch.
@cindex register-to-stack conversion
@item
Conversion from usage of some hard registers to usage of a register
stack may be done at this point. Currently, this is supported only
for the floating-point registers of the Intel 80387 coprocessor. The
source file name is @file{reg-stack.c}.
@opindex dk
The options @option{-dk} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.stack}
to the input file name.
@cindex final pass
@cindex peephole optimization
@item
Final. This pass outputs the assembler code for the function. It is
also responsible for identifying spurious test and compare
instructions. Machine-specific peephole optimizations are performed
at the same time. The function entry and exit sequences are generated
directly as assembler code in this pass; they never exist as RTL@.
The source files are @file{final.c} plus @file{insn-output.c}; the
latter is generated automatically from the machine description by the
tool @file{genoutput}. The header file @file{conditions.h} is used
for communication between these files.
@cindex debugging information generation
@item
Debugging information output. This is run after final because it must
output the stack slot offsets for pseudo registers that did not get
hard registers. Source files are @file{dbxout.c} for DBX symbol table
format, @file{sdbout.c} for SDB symbol table format, @file{dwarfout.c}
for DWARF symbol table format, and the files @file{dwarf2out.c} and
@file{dwarf2asm.c} for DWARF2 symbol table format.
@end itemize
Some additional files are used by all or many passes:
@itemize @bullet
@item
Every pass uses @file{machmode.def} and @file{machmode.h} which define
the machine modes.
@item
Several passes use @file{real.h}, which defines the default
representation of floating point constants and how to operate on them.
@item
All the passes that work with RTL use the header files @file{rtl.h}
and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
@code{gen*} also use these files to read and work with the machine
description RTL@.
@item
All the tools that read the machine description use support routines
found in @file{gensupport.c}, @file{errors.c}, and @file{read-rtl.c}.
@findex genconfig
@item
Several passes refer to the header file @file{insn-config.h} which
contains a few parameters (C macro definitions) generated
automatically from the machine description RTL by the tool
@code{genconfig}.
@cindex instruction recognizer
@item
Several passes use the instruction recognizer, which consists of
@file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
and @file{insn-extract.c} that are generated automatically from the
machine description by the tools @file{genrecog} and
@file{genextract}.
@item
Several passes use the header files @file{regs.h} which defines the
information recorded about pseudo register usage, and @file{basic-block.h}
which defines the information recorded about basic blocks.
@item
@file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
with a bit for each hard register, and some macros to manipulate it.
This type is just @code{int} if the machine has few enough hard registers;
otherwise it is an array of @code{int} and some of the macros expand
into loops.
@item
Several passes use instruction attributes. A definition of the
attributes defined for a particular machine is in file
@file{insn-attr.h}, which is generated from the machine description by
the program @file{genattr}. The file @file{insn-attrtab.c} contains
subroutines to obtain the attribute values for insns. It is generated
from the machine description by the program @file{genattrtab}.
@end itemize

38
gcc/doc/portability.texi Normal file
View File

@ -0,0 +1,38 @@
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Portability
@chapter GCC and Portability
@cindex portability
@cindex GCC and portability
The main goal of GCC was to make a good, fast compiler for machines in
the class that the GNU system aims to run on: 32-bit machines that address
8-bit bytes and have several general registers. Elegance, theoretical
power and simplicity are only secondary.
GCC gets most of the information about the target machine from a machine
description which gives an algebraic formula for each of the machine's
instructions. This is a very clean way to describe the target. But when
the compiler needs information that is difficult to express in this
fashion, I have not hesitated to define an ad-hoc parameter to the machine
description. The purpose of portability is to reduce the total work needed
on the compiler; it was not of interest for its own sake.
@cindex endianness
@cindex autoincrement addressing, availability
@findex abort
GCC does not contain machine dependent code, but it does contain code
that depends on machine parameters such as endianness (whether the most
significant byte has the highest or lowest address of the bytes in a word)
and the availability of autoincrement addressing. In the RTL-generation
pass, it is often necessary to have multiple strategies for generating code
for a particular kind of syntax tree, strategies that are usable for different
combinations of parameters. Often I have not tried to address all possible
cases, but only the common ones or only the ones that I have encountered.
As a result, a new target may require additional strategies. You will know
if this happens because the compiler will call @code{abort}. Fortunately,
the new strategies can be added in a machine-independent fashion, and will
affect only the target machines that need them.