OpenE2K
/
gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

* doc/gcc.texi: Move several chapters out to ...
	* doc/bugreport.texi, doc/contribute.texi, doc/frontends.texi,
	doc/service.texi, doc/standards.texi, doc/trouble.texi,
	doc/vms.texi: ... here.  New files.
	* Makefile.in ($(docdir)/gcc.info, gcc.dvi): Update dependencies.

From-SVN: r46929
This commit is contained in:
Joseph Myers 2001-11-11 11:31:24 +00:00 committed by Joseph Myers
parent eaec9b3d7e
commit b64a6a114e
10 changed files with 2512 additions and 2456 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
gcc/ChangeLog
View File

@ -1,3 +1,11 @@
2001-11-11 Joseph S. Myers <jsm28@cam.ac.uk>
* doc/gcc.texi: Move several chapters out to ...
* doc/bugreport.texi, doc/contribute.texi, doc/frontends.texi,
doc/service.texi, doc/standards.texi, doc/trouble.texi,
doc/vms.texi: ... here. New files.
* Makefile.in ($(docdir)/gcc.info, gcc.dvi): Update dependencies.
2001-11-11 Joseph S. Myers <jsm28@cam.ac.uk>
* ChangeLog.2, ChangeLog.3, ChangeLog.4, ChangeLog.5, ChangeLog,

10
gcc/Makefile.in
View File

@ -2315,7 +2315,10 @@ $(docdir)/gcc.info: $(docdir)/gcc.texi $(docdir)/extend.texi \
$(docdir)/c-tree.texi $(docdir)/rtl.texi $(docdir)/tm.texi \
$(docdir)/gcov.texi $(docdir)/contrib.texi $(docdir)/objc.texi \
$(docdir)/include/fdl.texi $(docdir)/include/gpl.texi \
$(docdir)/include/funding.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
cd $(srcdir) && $(MAKEINFO) $(MAKEINFOFLAGS) -I doc -I doc/include -o doc/gcc.info doc/gcc.texi
$(docdir)/cppinternals.info: $(docdir)/cppinternals.texi
@ -2333,7 +2336,10 @@ gcc.dvi: $(docdir)/gcc.texi $(docdir)/extend.texi $(docdir)/install-old.texi \
$(docdir)/rtl.texi $(docdir)/tm.texi $(docdir)/gcov.texi \
$(docdir)/contrib.texi $(docdir)/objc.texi \
$(docdir)/include/fdl.texi $(docdir)/include/gpl.texi \
$(docdir)/include/funding.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
$(TEXI2DVI) -I $(docdir) -I $(docdir)/include $(docdir)/gcc.texi
cppinternals.dvi: $(docdir)/cppinternals.texi

394
gcc/doc/bugreport.texi Normal file
View File

@ -0,0 +1,394 @@
@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 Bugs
@chapter Reporting Bugs
@cindex bugs
@cindex reporting bugs
Your bug reports play an essential role in making GCC reliable.
When you encounter a problem, the first thing to do is to see if it is
already known. @xref{Trouble}. If it isn't known, then you should
report the problem.
Reporting a bug may help you by bringing a solution to your problem, or
it may not. (If it does not, look in the service directory; see
@ref{Service}.) In any case, the principal function of a bug report is
to help the entire community by making the next version of GCC work
better. Bug reports are your contribution to the maintenance of GCC@.
Since the maintainers are very overloaded, we cannot respond to every
bug report. However, if the bug has not been fixed, we are likely to
send you a patch and ask you to tell us whether it works.
In order for a bug report to serve its purpose, you must include the
information that makes for fixing the bug.
@menu
* Criteria: Bug Criteria. Have you really found a bug?
* Where: Bug Lists. Where to send your bug report.
* Reporting: Bug Reporting. How to report a bug effectively.
* GNATS: gccbug. You can use a bug reporting tool.
* Known: Trouble. Known problems.
* Help: Service. Where to ask for help.
@end menu
@node Bug Criteria,Bug Lists,,Bugs
@section Have You Found a Bug?
@cindex bug criteria
If you are not sure whether you have found a bug, here are some guidelines:
@itemize @bullet
@cindex fatal signal
@cindex core dump
@item
If the compiler gets a fatal signal, for any input whatever, that is a
compiler bug. Reliable compilers never crash.
@cindex invalid assembly code
@cindex assembly code, invalid
@item
If the compiler produces invalid assembly code, for any input whatever
(except an @code{asm} statement), that is a compiler bug, unless the
compiler reports errors (not just warnings) which would ordinarily
prevent the assembler from being run.
@cindex undefined behavior
@cindex undefined function value
@cindex increment operators
@item
If the compiler produces valid assembly code that does not correctly
execute the input source code, that is a compiler bug.
However, you must double-check to make sure, because you may have run
into an incompatibility between GNU C and traditional C
(@pxref{Incompatibilities}). These incompatibilities might be considered
bugs, but they are inescapable consequences of valuable features.
Or you may have a program whose behavior is undefined, which happened
by chance to give the desired results with another C or C++ compiler.
For example, in many nonoptimizing compilers, you can write @samp{x;}
at the end of a function instead of @samp{return x;}, with the same
results. But the value of the function is undefined if @code{return}
is omitted; it is not a bug when GCC produces different results.
Problems often result from expressions with two increment operators,
as in @code{f (*p++, *p++)}. Your previous compiler might have
interpreted that expression the way you intended; GCC might
interpret it another way. Neither compiler is wrong. The bug is
in your code.
After you have localized the error to a single source line, it should
be easy to check for these things. If your program is correct and
well defined, you have found a compiler bug.
@item
If the compiler produces an error message for valid input, that is a
compiler bug.
@cindex invalid input
@item
If the compiler does not produce an error message for invalid input,
that is a compiler bug. However, you should note that your idea of
``invalid input'' might be my idea of ``an extension'' or ``support
for traditional practice''.
@item
If you are an experienced user of one of the languages GCC supports, your
suggestions for improvement of GCC are welcome in any case.
@end itemize
@node Bug Lists,Bug Reporting,Bug Criteria,Bugs
@section Where to Report Bugs
@cindex bug report mailing lists
@kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
Send bug reports for the GNU Compiler Collection to
@email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
convention, in which bug reports for tool ``foo'' are sent
to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
may also be used; it will forward to the address given above.
Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
more up-to-date bug reporting instructions before you post a bug report.
@node Bug Reporting,gccbug,Bug Lists,Bugs
@section How to Report Bugs
@cindex compiler bugs, reporting
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
fact or leave it out, state it!
Often people omit facts because they think they know what causes the
problem and they conclude that some details don't matter. Thus, you might
assume that the name of the variable you use in an example does not matter.
Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
stray memory reference which happens to fetch from the location where that
name is stored in memory; perhaps, if the name were different, the contents
of that location would fool the compiler into doing the right thing despite
the bug. Play it safe and give a specific, complete example. That is the
easiest thing for you to do, and the most helpful.
Keep in mind that the purpose of a bug report is to enable someone to
fix the bug if it is not known. It isn't very important what happens if
the bug is already known. Therefore, always write your bug reports on
the assumption that the bug is not known.
Sometimes people give a few sketchy facts and ask, ``Does this ring a
bell?'' This cannot help us fix a bug, so it is basically useless. We
respond by asking for enough details to enable us to investigate.
You might as well expedite matters by sending them to begin with.
Try to make your bug report self-contained. If we have to ask you for
more information, it is best if you include all the previous information
in your response, as well as the information that was missing.
Please report each bug in a separate message. This makes it easier for
us to track which bugs have been fixed and to forward your bugs reports
to the appropriate maintainer.
To enable someone to investigate the bug, you should include all these
things:
@itemize @bullet
@item
The version of GCC@. You can get this by running it with the
@option{-v} option.
Without this, we won't know whether there is any point in looking for
the bug in the current version of GCC@.
@item
A complete input file that will reproduce the bug. If the bug is in the
C preprocessor, send a source file and any header files that it
requires. If the bug is in the compiler proper (@file{cc1}), send the
preprocessor output generated by adding @option{-save-temps} to the
compilation command (@pxref{Debugging Options}). When you do this, use
the same @option{-I}, @option{-D} or @option{-U} options that you used in
actual compilation. Then send the @var{input}.i or @var{input}.ii files
generated.
A single statement is not enough of an example. In order to compile it,
it must be embedded in a complete file of compiler input; and the bug
might depend on the details of how this is done.
Without a real example one can compile, all anyone can do about your bug
report is wish you luck. It would be futile to try to guess how to
provoke the bug. For example, bugs in register allocation and reloading
frequently depend on every little detail of the function they happen in.
Even if the input file that fails comes from a GNU program, you should
still send the complete test case. Don't ask the GCC maintainers to
do the extra work of obtaining the program in question---they are all
overworked as it is. Also, the problem may depend on what is in the
header files on your system; it is unreliable for the GCC maintainers
to try the problem with the header files available to them. By sending
CPP output, you can eliminate this source of uncertainty and save us
a certain percentage of wild goose chases.
@item
The command arguments you gave GCC to compile that example
and observe the bug. For example, did you use @option{-O}? To guarantee
you won't omit something important, list all the options.
If we were to try to guess the arguments, we would probably guess wrong
and then we would not encounter the bug.
@item
The type of machine you are using, and the operating system name and
version number.
@item
The operands you gave to the @code{configure} command when you installed
the compiler.
@item
A complete list of any modifications you have made to the compiler
source. (We don't promise to investigate the bug unless it happens in
an unmodified compiler. But if you've made modifications and don't tell
us, then you are sending us on a wild goose chase.)
Be precise about these changes. A description in English is not
enough---send a context diff for them.
Adding files of your own (such as a machine description for a machine we
don't support) is a modification of the compiler source.
@item
Details of any other deviations from the standard procedure for installing
GCC@.
@item
A description of what behavior you observe that you believe is
incorrect. For example, ``The compiler gets a fatal signal,'' or,
``The assembler instruction at line 208 in the output is incorrect.''
Of course, if the bug is that the compiler gets a fatal signal, then one
can't miss it. But if the bug is incorrect output, the maintainer might
not notice unless it is glaringly wrong. None of us has time to study
all the assembler code from a 50-line C program just on the chance that
one instruction might be wrong. We need @emph{you} to do this part!
Even if the problem you experience is a fatal signal, you should still
say so explicitly. Suppose something strange is going on, such as, your
copy of the compiler is out of synch, or you have encountered a bug in
the C library on your system. (This has happened!) Your copy might
crash and the copy here would not. If you @i{said} to expect a crash,
then when the compiler here fails to crash, we would know that the bug
was not happening. If you don't say to expect a crash, then we would
not know whether the bug was happening. We would not be able to draw
any conclusion from our observations.
If the problem is a diagnostic when compiling GCC with some other
compiler, say whether it is a warning or an error.
Often the observed symptom is incorrect output when your program is run.
Sad to say, this is not enough information unless the program is short
and simple. None of us has time to study a large program to figure out
how it would work if compiled correctly, much less which line of it was
compiled wrong. So you will have to do that. Tell us which source line
it is, and what incorrect result happens when that line is executed. A
person who understands the program can find this as easily as finding a
bug in the program itself.
@item
If you send examples of assembler code output from GCC,
please use @option{-g} when you make them. The debugging information
includes source line numbers which are essential for correlating the
output with the input.
@item
If you wish to mention something in the GCC source, refer to it by
context, not by line number.
The line numbers in the development sources don't match those in your
sources. Your line numbers would convey no useful information to the
maintainers.
@item
Additional information from a debugger might enable someone to find a
problem on a machine which he does not have available. However, you
need to think when you collect this information if you want it to have
any chance of being useful.
@cindex backtrace for bug reports
For example, many people send just a backtrace, but that is never
useful by itself. A simple backtrace with arguments conveys little
about GCC because the compiler is largely data-driven; the same
functions are called over and over for different RTL insns, doing
different things depending on the details of the insn.
Most of the arguments listed in the backtrace are useless because they
are pointers to RTL list structure. The numeric values of the
pointers, which the debugger prints in the backtrace, have no
significance whatever; all that matters is the contents of the objects
they point to (and most of the contents are other such pointers).
In addition, most compiler passes consist of one or more loops that
scan the RTL insn sequence. The most vital piece of information about
such a loop---which insn it has reached---is usually in a local variable,
not in an argument.
@findex debug_rtx
What you need to provide in addition to a backtrace are the values of
the local variables for several stack frames up. When a local
variable or an argument is an RTX, first print its value and then use
the GDB command @code{pr} to print the RTL expression that it points
to. (If GDB doesn't run on your machine, use your debugger to call
the function @code{debug_rtx} with the RTX as an argument.) In
general, whenever a variable is a pointer, its value is no use
without the data it points to.
@end itemize
Here are some things that are not necessary:
@itemize @bullet
@item
A description of the envelope of the bug.
Often people who encounter a bug spend a lot of time investigating
which changes to the input file will make the bug go away and which
changes will not affect it.
This is often time consuming and not very useful, because the way we
will find the bug is by running a single example under the debugger with
breakpoints, not by pure deduction from a series of examples. You might
as well save your time for something else.
Of course, if you can find a simpler example to report @emph{instead} of
the original one, that is a convenience. Errors in the output will be
easier to spot, running under the debugger will take less time, etc.
Most GCC bugs involve just one function, so the most straightforward
way to simplify an example is to delete all the function definitions
except the one where the bug occurs. Those earlier in the file may be
replaced by external declarations if the crucial function depends on
them. (Exception: inline functions may affect compilation of functions
defined later in the file.)
However, simplification is not vital; if you don't want to do this,
report the bug anyway and send the entire test case you used.
@item
In particular, some people insert conditionals @samp{#ifdef BUG} around
a statement which, if removed, makes the bug not happen. These are just
clutter; we won't pay any attention to them anyway. Besides, you should
send us cpp output, and that can't have conditionals.
@item
A patch for the bug.
A patch for the bug is useful if it is a good one. But don't omit the
necessary information, such as the test case, on the assumption that a
patch is all we need. We might see problems with your patch and decide
to fix the problem another way, or we might not understand it at all.
Sometimes with a program as complicated as GCC it is very hard to
construct an example that will make the program follow a certain path
through the code. If you don't send the example, we won't be able to
construct one, so we won't be able to verify that the bug is fixed.
And if we can't understand what bug you are trying to fix, or why your
patch should be an improvement, we won't install it. A test case will
help us to understand.
See @uref{http://gcc.gnu.org/contribute.html}
for guidelines on how to make it easy for us to
understand and install your patches.
@item
A guess about what the bug is or what it depends on.
Such guesses are usually wrong. Even I can't guess right about such
things without first using the debugger to find the facts.
@item
A core dump file.
We have no way of examining a core dump for your type of machine
unless we have an identical system---and if we do have one,
we should be able to reproduce the crash ourselves.
@end itemize
@node gccbug,, Bug Reporting, Bugs
@section The gccbug script
@cindex gccbug script
To simplify creation of bug reports, and to allow better tracking of
reports, we use the GNATS bug tracking system. Part of that system is
the @code{gccbug} script. This is a Unix shell script, so you need a
shell to run it. It is normally installed in the same directory where
@code{gcc} is installed.
The gccbug script is derived from send-pr, @pxref{using
send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
invoked, it starts a text editor so you can fill out the various fields
of the report. When the you quit the editor, the report is automatically
send to the bug reporting address.
A number of fields in this bug report form are specific to GCC, and are
explained at @uref{http://gcc.gnu.org/gnats.html}.

25
gcc/doc/contribute.texi Normal file
View File

@ -0,0 +1,25 @@
@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 Contributing
@chapter Contributing to GCC Development
If you would like to help pretest GCC releases to assure they work well,
our current development sources are available by CVS (see
@uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are
also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
If you would like to work on improvements to GCC, please read the
advice at these URLs:
@smallexample
@uref{http://gcc.gnu.org/contribute.html}
@uref{http://gcc.gnu.org/contributewhy.html}
@end smallexample
@noindent
for information on how to make useful contributions and avoid
duplication of effort. Suggested projects are listed at
@uref{http://gcc.gnu.org/projects/}.

70
gcc/doc/frontends.texi Normal file
View File

@ -0,0 +1,70 @@
@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 G++ and GCC
@chapter Compile C, C++, Objective-C, Ada, CHILL, Fortran, or Java
@cindex Objective-C
@cindex Fortran
@cindex Java
@cindex CHILL
@cindex Ada
Several versions of the compiler (C, C++, Objective-C, Ada, CHILL,
Fortran, and Java) are integrated; this is why we use the name
``GNU Compiler Collection''. GCC can compile programs written in any of these
languages. The Ada, CHILL, Fortran, and Java compilers are described in
separate manuals.
@cindex GCC
``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
the most general name for the compiler, and the name used when the
emphasis is on compiling C programs (as the abbreviation formerly
stood for ``GNU C Compiler'').
@cindex C++
@cindex G++
When referring to C++ compilation, it is usual to call the compiler
``G++''. Since there is only one compiler, it is also accurate to call
it ``GCC'' no matter what the language context; however, the term
``G++'' is more useful when the emphasis is on compiling C++ programs.
@cindex Ada
@cindex GNAT
Similarly, when we talk about Ada compilation, we usually call the
compiler ``GNAT'', for the same reasons.
We use the name ``GCC'' to refer to the compilation system as a
whole, and more specifically to the language-independent part of the
compiler. For example, we refer to the optimization options as
affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
Front ends for other languages, such as Mercury and Pascal exist but
have not yet been integrated into GCC@. These front ends, like that for C++,
are built in subdirectories of GCC and link to it. The result is an
integrated compiler that can compile programs written in C, C++,
Objective-C, or any of the languages for which you have installed front
ends.
In this manual, we only discuss the options for the C, Objective-C, and
C++ compilers and those of the GCC core. Consult the documentation
of the other front ends for the options to use when compiling programs
written in other languages.
@cindex compiler compared to C++ preprocessor
@cindex intermediate C version, nonexistent
@cindex C intermediate output, nonexistent
G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
code directly from your C++ program source. There is no intermediate C
version of the program. (By contrast, for example, some other
implementations use a program that generates a C program from your C++
source.) Avoiding an intermediate C representation of the program means
that you get better object code, and better debugging information. The
GNU debugger, GDB, works with this information in the object code to
give you comprehensive C++ source-level editing capabilities
(@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
@c FIXME! Someone who knows something about Objective-C ought to put in
@c a paragraph or two about it here, and move the index entry down when
@c there is more to point to than the general mention in the 1st par.

2461
gcc/doc/gcc.texi
View File

File diff suppressed because it is too large Load Diff

30
gcc/doc/service.texi Normal file
View File

@ -0,0 +1,30 @@
@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 Service
@chapter How To Get Help with GCC
If you need help installing, using or changing GCC, there are two
ways to find it:
@itemize @bullet
@item
Send a message to a suitable network mailing list. First try
@email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
that brings no response, try @email{gcc@@gcc.gnu.org}. For help
changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
a bug in GCC, please report it following the instructions at
@pxref{Bug Reporting}.
@item
Look in the service directory for someone who might help you for a fee.
The service directory is found at
@uref{http://www.gnu.org/prep/service.html}.
@end itemize
@c For further information, see
@c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
@c FIXME: this URL may be too volatile, this FAQ entry needs to move to
@c the regular web pages before we can uncomment the reference.

174
gcc/doc/standards.texi Normal file
View File

@ -0,0 +1,174 @@
@c Copyright (C) 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Standards
@chapter Language Standards Supported by GCC
@cindex C standard
@cindex C standards
@cindex ANSI C standard
@cindex ANSI C
@cindex ANSI C89
@cindex C89
@cindex ANSI X3.159-1989
@cindex X3.159-1989
@cindex ISO C standard
@cindex ISO C
@cindex ISO C89
@cindex ISO C90
@cindex ISO/IEC 9899
@cindex ISO 9899
@cindex C90
@cindex ISO C94
@cindex C94
@cindex ISO C95
@cindex C95
@cindex ISO C99
@cindex C99
@cindex ISO C9X
@cindex C9X
@cindex Technical Corrigenda
@cindex TC1
@cindex Technical Corrigendum 1
@cindex TC2
@cindex Technical Corrigendum 2
@cindex AMD1
@cindex freestanding implementation
@cindex freestanding environment
@cindex hosted implementation
@cindex hosted environment
@findex __STDC_HOSTED__
For each language compiled by GCC for which there is a standard, GCC
attempts to follow one or more versions of that standard, possibly
with some exceptions, and possibly with some extensions.
GCC supports three versions of the C standard, although support for
the most recent version is not yet complete.
@opindex std
@opindex ansi
@opindex pedantic
@opindex pedantic-errors
The original ANSI C standard (X3.159-1989) was ratified in 1989 and
published in 1990. This standard was ratified as an ISO standard
(ISO/IEC 9899:1990) later in 1990. There were no technical
differences between these publications, although the sections of the
ANSI standard were renumbered and became clauses in the ISO standard.
This standard, in both its forms, is commonly known as @dfn{C89}, or
occasionally as @dfn{C90}, from the dates of ratification. The ANSI
standard, but not the ISO standard, also came with a Rationale
document. To select this standard in GCC, use one of the options
@option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
all the diagnostics required by the standard, you should also specify
@option{-pedantic} (or @option{-pedantic-errors} if you want them to be
errors rather than warnings). @xref{C Dialect Options,,Options
Controlling C Dialect}.
Errors in the 1990 ISO C standard were corrected in two Technical
Corrigenda published in 1994 and 1996. GCC does not support the
uncorrected version.
An amendment to the 1990 standard was published in 1995. This
amendment added digraphs and @code{__STDC_VERSION__} to the language,
but otherwise concerned the library. This amendment is commonly known
as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
@dfn{C95}. To select this standard in GCC, use the option
@option{-std=iso9899:199409} (with, as for other standard versions,
@option{-pedantic} to receive all required diagnostics).
A new edition of the ISO C standard was published in 1999 as ISO/IEC
9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
support for this standard version; see
@uref{http://gcc.gnu.org/c99status.html} for details. To select this
standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in
development, drafts of this standard version were referred to as
@dfn{C9X}.)
@opindex traditional
GCC also has some limited support for traditional (pre-ISO) C with the
@option{-traditional} option. This support may be of use for compiling
some very old programs that have not been updated to ISO C, but should
not be used for new programs. It will not work with some modern C
libraries such as the GNU C library.
By default, GCC provides some extensions to the C language that on
rare occasions conflict with the C standard. @xref{C
Extensions,,Extensions to the C Language Family}. Use of the
@option{-std} options listed above will disable these extensions where
they conflict with the C standard version selected. You may also
select an extended version of the C language explicitly with
@option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
(for C99 with GNU extensions). The default, if no C language dialect
options are given, is @option{-std=gnu89}; this will change to
@option{-std=gnu99} in some future release when the C99 support is
complete. Some features that are part of the C99 standard are
accepted as extensions in C89 mode.
The ISO C standard defines (in clause 4) two classes of conforming
implementation. A @dfn{conforming hosted implementation} supports the
whole standard including all the library facilities; a @dfn{conforming
freestanding implementation} is only required to provide certain
library facilities: those in @code{<float.h>}, @code{<limits.h>},
@code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
@code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
@code{<stdint.h>}. In addition, complex types, added in C99, are not
required for freestanding implementations. The standard also defines
two environments for programs, a @dfn{freestanding environment},
required of all implementations and which may not have library
facilities beyond those required of freestanding implementations,
where the handling of program startup and termination are
implementation-defined, and a @dfn{hosted environment}, which is not
required, in which all the library facilities are provided and startup
is through a function @code{int main (void)} or @code{int main (int,
char *[])}. An OS kernel would be a freestanding environment; a
program using the facilities of an operating system would normally be
in a hosted implementation.
@opindex ffreestanding
GCC aims towards being usable as a conforming freestanding
implementation, or as the compiler for a conforming hosted
implementation. By default, it will act as the compiler for a hosted
implementation, defining @code{__STDC_HOSTED__} as @code{1} and
presuming that when the names of ISO C functions are used, they have
the semantics defined in the standard. To make it act as a conforming
freestanding implementation for a freestanding environment, use the
option @option{-ffreestanding}; it will then define
@code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
meanings of function names from the standard library. To build an OS
kernel, you may well still need to make your own arrangements for
linking and startup. @xref{C Dialect Options,,Options Controlling C
Dialect}.
GCC does not provide the library facilities required only of hosted
implementations, nor yet all the facilities required by C99 of
freestanding implementations; to use the facilities of a hosted
environment, you will need to find them elsewhere (for example, in the
GNU C library). @xref{Standard Libraries,,Standard Libraries}.
For references to Technical Corrigenda, Rationale documents and
information concerning the history of C that is available online, see
@uref{http://gcc.gnu.org/readings.html}
@c FIXME: details of C++ standard.
There is no formal written standard for Objective-C@. The most
authoritative manual is ``Object-Oriented Programming and the
Objective-C Language'', available at a number of web sites;
@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
is an older example. @uref{http://www.gnustep.org} includes useful
information as well.
@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm,
GNAT Reference Manual}, for information on standard
conformance and compatibility of the Ada compiler.
@xref{References,,Language Definition References, chill, GNU Chill},
for details of the CHILL standard.
@xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
Fortran}, for details of the Fortran language supported by GCC@.
@xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
for details of compatibility between @code{gcj} and the Java Platform.

1465
gcc/doc/trouble.texi Normal file
View File

File diff suppressed because it is too large Load Diff

331
gcc/doc/vms.texi Normal file
View File

@ -0,0 +1,331 @@
@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 VMS
@chapter Using GCC on VMS
@c prevent bad page break with this line
Here is how to use GCC on VMS@.
@menu
* Include Files and VMS:: Where the preprocessor looks for the include files.
* Global Declarations:: How to do globaldef, globalref and globalvalue with
GCC.
* VMS Misc:: Misc information.
@end menu
@node Include Files and VMS
@section Include Files and VMS
@cindex include files and VMS
@cindex VMS and include files
@cindex header files and VMS
Due to the differences between the filesystems of Unix and VMS, GCC
attempts to translate file names in @samp{#include} into names that VMS
will understand. The basic strategy is to prepend a prefix to the
specification of the include file, convert the whole filename to a VMS
filename, and then try to open the file. GCC tries various prefixes
one by one until one of them succeeds:
@enumerate
@item
The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
where GNU C header files are traditionally stored. If you wish to store
header files in non-standard locations, then you can assign the logical
@samp{GNU_CC_INCLUDE} to be a search list, where each element of the
list is suitable for use with a rooted logical.
@item
The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
VAX-C header files are traditionally stored.
@item
If the include file specification by itself is a valid VMS filename, the
preprocessor then uses this name with no prefix in an attempt to open
the include file.
@item
If the file specification is not a valid VMS filename (i.e.@: does not
contain a device or a directory specifier, and contains a @samp{/}
character), the preprocessor tries to convert it from Unix syntax to
VMS syntax.
Conversion works like this: the first directory name becomes a device,
and the rest of the directories are converted into VMS-format directory
names. For example, the name @file{X11/foobar.h} is
translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
whichever one can be opened. This strategy allows you to assign a
logical name to point to the actual location of the header files.
@item
If none of these strategies succeeds, the @samp{#include} fails.
@end enumerate
Include directives of the form:
@example
#include foobar
@end example
@noindent
are a common source of incompatibility between VAX-C and GCC@. VAX-C
treats this much like a standard @code{#include <foobar.h>} directive.
That is incompatible with the ISO C behavior implemented by GCC: to
expand the name @code{foobar} as a macro. Macro expansion should
eventually yield one of the two standard formats for @code{#include}:
@example
#include "@var{file}"
#include <@var{file}>
@end example
If you have this problem, the best solution is to modify the source to
convert the @code{#include} directives to one of the two standard forms.
That will work with either compiler. If you want a quick and dirty fix,
define the file names as macros with the proper expansion, like this:
@example
#define stdio <stdio.h>
@end example
@noindent
This will work, as long as the name doesn't conflict with anything else
in the program.
Another source of incompatibility is that VAX-C assumes that:
@example
#include "foobar"
@end example
@noindent
is actually asking for the file @file{foobar.h}. GCC does not
make this assumption, and instead takes what you ask for literally;
it tries to read the file @file{foobar}. The best way to avoid this
problem is to always specify the desired file extension in your include
directives.
GCC for VMS is distributed with a set of include files that is
sufficient to compile most general purpose programs. Even though the
GCC distribution does not contain header files to define constants
and structures for some VMS system-specific functions, there is no
reason why you cannot use GCC with any of these functions. You first
may have to generate or create header files, either by using the public
domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
extracting the relevant modules from one of the system macro libraries,
and using an editor to construct a C header file.
A @code{#include} file name cannot contain a DECNET node name. The
preprocessor reports an I/O error if you attempt to use a node name,
whether explicitly, or implicitly via a logical name.
@node Global Declarations
@section Global Declarations and VMS
@findex GLOBALREF
@findex GLOBALDEF
@findex GLOBALVALUEDEF
@findex GLOBALVALUEREF
GCC does not provide the @code{globalref}, @code{globaldef} and
@code{globalvalue} keywords of VAX-C@. You can get the same effect with
an obscure feature of GAS, the GNU assembler. (This requires GAS
version 1.39 or later.) The following macros allow you to use this
feature in a fairly natural way:
@smallexample
#ifdef __GNUC__
#define GLOBALREF(TYPE,NAME) \
TYPE NAME \
asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
#define GLOBALDEF(TYPE,NAME,VALUE) \
TYPE NAME \
asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
= VALUE
#define GLOBALVALUEREF(TYPE,NAME) \
const TYPE NAME[1] \
asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
const TYPE NAME[1] \
asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
= @{VALUE@}
#else
#define GLOBALREF(TYPE,NAME) \
globalref TYPE NAME
#define GLOBALDEF(TYPE,NAME,VALUE) \
globaldef TYPE NAME = VALUE
#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
globalvalue TYPE NAME = VALUE
#define GLOBALVALUEREF(TYPE,NAME) \
globalvalue TYPE NAME
#endif
@end smallexample
@noindent
(The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
name is removed by the assembler, after it has modified the attributes
of the symbol). These macros are provided in the VMS binaries
distribution in a header file @file{GNU_HACKS.H}. An example of the
usage is:
@example
GLOBALREF (int, ijk);
GLOBALDEF (int, jkl, 0);
@end example
The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
straightforwardly for arrays, since there is no way to insert the array
dimension into the declaration at the right place. However, you can
declare an array with these macros if you first define a typedef for the
array type, like this:
@example
typedef int intvector[10];
GLOBALREF (intvector, foo);
@end example
Array and structure initializers will also break the macros; you can
define the initializer to be a macro of its own, or you can expand the
@code{GLOBALDEF} macro by hand. You may find a case where you wish to
use the @code{GLOBALDEF} macro with a large array, but you are not
interested in explicitly initializing each element of the array. In
such cases you can use an initializer like: @code{@{0,@}}, which will
initialize the entire array to @code{0}.
A shortcoming of this implementation is that a variable declared with
@code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
example, the declaration:
@example
GLOBALVALUEREF(int, ijk);
@end example
@noindent
declares the variable @code{ijk} as an array of type @code{int [1]}.
This is done because a globalvalue is actually a constant; its ``value''
is what the linker would normally consider an address. That is not how
an integer value works in C, but it is how an array works. So treating
the symbol as an array name gives consistent results---with the
exception that the value seems to have the wrong type. @strong{Don't
try to access an element of the array.} It doesn't have any elements.
The array ``address'' may not be the address of actual storage.
The fact that the symbol is an array may lead to warnings where the
variable is used. Insert type casts to avoid the warnings. Here is an
example; it takes advantage of the ISO C feature allowing macros that
expand to use the same name as the macro itself.
@example
GLOBALVALUEREF (int, ss$_normal);
GLOBALVALUEDEF (int, xyzzy,123);
#ifdef __GNUC__
#define ss$_normal ((int) ss$_normal)
#define xyzzy ((int) xyzzy)
#endif
@end example
Don't use @code{globaldef} or @code{globalref} with a variable whose
type is an enumeration type; this is not implemented. Instead, make the
variable an integer, and use a @code{globalvaluedef} for each of the
enumeration values. An example of this would be:
@example
#ifdef __GNUC__
GLOBALDEF (int, color, 0);
GLOBALVALUEDEF (int, RED, 0);
GLOBALVALUEDEF (int, BLUE, 1);
GLOBALVALUEDEF (int, GREEN, 3);
#else
enum globaldef color @{RED, BLUE, GREEN = 3@};
#endif
@end example
@node VMS Misc
@section Other VMS Issues
@cindex exit status and VMS
@cindex return value of @code{main}
@cindex @code{main} and the exit status
GCC automatically arranges for @code{main} to return 1 by default if
you fail to specify an explicit return value. This will be interpreted
by VMS as a status code indicating a normal successful completion.
Version 1 of GCC did not provide this default.
GCC on VMS works only with the GNU assembler, GAS@. You need version
1.37 or later of GAS in order to produce value debugging information for
the VMS debugger. Use the ordinary VMS linker with the object files
produced by GAS@.
@cindex shared VMS run time system
@cindex @file{VAXCRTL}
Under previous versions of GCC, the generated code would occasionally
give strange results when linked to the sharable @file{VAXCRTL} library.
Now this should work.
A caveat for use of @code{const} global variables: the @code{const}
modifier must be specified in every external declaration of the variable
in all of the source files that use that variable. Otherwise the linker
will issue warnings about conflicting attributes for the variable. Your
program will still work despite the warnings, but the variable will be
placed in writable storage.
@cindex name augmentation
@cindex case sensitivity and VMS
@cindex VMS and case sensitivity
Although the VMS linker does distinguish between upper and lower case
letters in global symbols, most VMS compilers convert all such symbols
into upper case and most run-time library routines also have upper case
names. To be able to reliably call such routines, GCC (by means of
the assembler GAS) converts global symbols into upper case like other
VMS compilers. However, since the usual practice in C is to distinguish
case, GCC (via GAS) tries to preserve usual C behavior by augmenting
each name that is not all lower case. This means truncating the name
to at most 23 characters and then adding more characters at the end
which encode the case pattern of those 23. Names which contain at
least one dollar sign are an exception; they are converted directly into
upper case without augmentation.
Name augmentation yields bad results for programs that use precompiled
libraries (such as Xlib) which were generated by another compiler. You
can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
it makes external C functions and variables case-independent as is usual
on VMS@. Alternatively, you could write all references to the functions
and variables in such libraries using lower case; this will work on VMS,
but is not portable to other systems. The compiler option @samp{/NAMES}
also provides control over global name handling.
Function and variable names are handled somewhat differently with G++.
The GNU C++ compiler performs @dfn{name mangling} on function
names, which means that it adds information to the function name to
describe the data types of the arguments that the function takes. One
result of this is that the name of a function can become very long.
Since the VMS linker only recognizes the first 31 characters in a name,
special action is taken to ensure that each function and variable has a
unique name that can be represented in 31 characters.
If the name (plus a name augmentation, if required) is less than 32
characters in length, then no special action is performed. If the name
is longer than 31 characters, the assembler (GAS) will generate a
hash string based upon the function name, truncate the function name to
23 characters, and append the hash string to the truncated name. If the
@samp{/VERBOSE} compiler option is used, the assembler will print both
the full and truncated names of each symbol that is truncated.
The @samp{/NOCASE_HACK} compiler option should not be used when you are
compiling programs that use libg++. libg++ has several instances of
objects (i.e. @code{Filebuf} and @code{filebuf}) which become
indistinguishable in a case-insensitive environment. This leads to
cases where you need to inhibit augmentation selectively (if you were
using libg++ and Xlib in the same program, for example). There is no
special feature for doing this, but you can get the result by defining a
macro for each mixed case symbol for which you wish to inhibit
augmentation. The macro should expand into the lower case equivalent of
itself. For example:
@example
#define StuDlyCapS studlycaps
@end example
These macro definitions can be placed in a header file to minimize the
number of changes to your source code.