Skip to content

R
riscv-gcc-1
Commit 73a8ed7e by Joseph Myers Committed by Joseph Myers
Options

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

	* 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
parent 285a5742
Showing with 835 additions and 2 deletions
gcc/ChangeLog
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.
......
gcc/Makefile.in
......@@ -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
......
gcc/doc/configterms.texi 0 → 100644
@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.
gcc/doc/contrib.texi
......@@ -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
......
gcc/doc/fragments.texi 0 → 100644
@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
gcc/doc/hostconfig.texi 0 → 100644
@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}.
gcc/doc/include/linux-and-gnu.texi 0 → 100644
@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.
gcc/doc/interface.texi 0 → 100644
@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@.
gcc/doc/makefile.texi 0 → 100644
@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
gcc/doc/portability.texi 0 → 100644
@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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment