-@c Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc.
+@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008 Free Software Foundation,
+@c Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
needs fixing, @file{syslimits.h} is the fixed copy.
+GCC can also install @code{<tgmath.h>}. It will do this when
+@file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
+
@node Documentation
@subsection Building Documentation
The main GCC documentation is in the form of manuals in Texinfo
-format. These are installed in Info format, and DVI versions may be
-generated by @samp{make dvi}. In addition, some man pages are
+format. These are installed in Info format; DVI versions may be
+generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
+HTML versions by @command{make html}. In addition, some man pages are
generated from the Texinfo manuals, there are some other text files
with miscellaneous documentation, and runtime libraries have their own
documentation outside the @file{gcc} directory. FIXME: document the
@item gcc-common.texi
Common definitions for manuals.
@item gpl.texi
+@itemx gpl_v3.texi
The GNU General Public License.
@item texinfo.tex
A copy of @file{texinfo.tex} known to work with the GCC manuals.
@end table
-DVI formatted manuals are generated by @samp{make dvi}, which uses
-@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info
+DVI-formatted manuals are generated by @samp{make dvi}, which uses
+@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).
+PDF-formatted manuals are generated by @samp{make pdf}, which uses
+@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML
+formatted manuals are generated by @command{make html}. Info
manuals are generated by @samp{make info} (which is run as part of
a bootstrap); this generates the manuals in the source directory,
using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
more than once in the source tree.) The manual file
@file{@var{name}.texi} should only include other files in its own
directory or in @file{doc/include}. HTML manuals will be generated by
-@samp{makeinfo --html} and PostScript manuals by @command{texi2dvi}
-and @command{dvips}. All Texinfo files that are parts of manuals must
-be checked into CVS, even if they are generated files, for the
+@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
+and @command{dvips}, and PDF manuals by @command{texi2pdf}.
+All Texinfo files that are parts of manuals must
+be checked into SVN, even if they are generated files, for the
generation of online manuals to work.
The installation manual, @file{doc/install.texi}, is also provided on
@item README.Portability
Information about portability issues when writing code in GCC@. FIXME:
why isn't this part of this manual or of the GCC Coding Conventions?
-@item SERVICE
-A pointer to the GNU Service Directory.
@end table
FIXME: document such files in subdirectories, at least @file{config},
@file{gcc/doc/sourcebuild.texi}.
@end itemize
-If the front end is added to the official GCC CVS repository, the
+If the front end is added to the official GCC source repository, the
following are also necessary:
@itemize @bullet
If this front end includes its own version files that include the
current date, @file{maintainer-scripts/update_version} should be
updated accordingly.
-@item
-@file{CVSROOT/modules} in the GCC CVS repository should be updated.
@end itemize
@menu
values of @code{@var{hook}}, and any other Makefile rules required to
build those targets (which may if necessary use other Makefiles
specified in @code{outputs} in @file{config-lang.in}, although this is
-deprecated). Some hooks are defined by using a double-colon rule for
-@code{@var{hook}}, rather than by using a target of form
-@code{@var{lang}.@var{hook}}. These hooks are called ``double-colon
-hooks'' below. It also adds any testsuite targets that can use the
+deprecated). It also adds any testsuite targets that can use the
standard rule in @file{gcc/Makefile.in} to the variable
@code{lang_checks}.
@table @code
-@item all.build
@itemx all.cross
@itemx start.encap
@itemx rest.encap
Build DVI documentation for the front end, in the build directory.
This should be done using @code{$(TEXI2DVI)}, with appropriate
@option{-I} arguments pointing to directories of included files.
-This hook is a double-colon hook.
+@item pdf
+Build PDF documentation for the front end, in the build directory.
+This should be done using @code{$(TEXI2PDF)}, with appropriate
+@option{-I} arguments pointing to directories of included files.
+@item html
+Build HTML documentation for the front end, in the build directory.
@item man
Build generated man pages for the front end from Texinfo manuals
(@pxref{Man Page Generation}), in the build directory. This target
is only called if the necessary tools are available, but should ignore
errors so as not to stop the build if errors occur; man pages are
optional and the tools involved may be installed in a broken way.
-@item install-normal
-FIXME: what is this target for?
@item install-common
Install everything that is part of the front end, apart from the
compiler executables listed in @code{compilers} in
@item install-info
Install info documentation for the front end, if it is present in the
source directory. This target should have dependencies on info files
-that should be installed. This hook is a double-colon hook.
+that should be installed.
@item install-man
Install man pages for the front end. This target should ignore
errors.
targets. For GCC, @code{maintainer-clean} should delete
all generated files in the source directory that are not checked into
CVS, but should not delete anything checked into CVS@.
-@item stage1
-@itemx stage2
-@itemx stage3
-@itemx stage4
-@itemx stageprofile
-@itemx stagefeedback
-Move to the stage directory files not included in @code{stagestuff} in
-@file{config-lang.in} or otherwise moved by the main @file{Makefile}.
@end table
@item lang.opt
This file registers the set of switches that the front end accepts on
-the command line, and their @option{--help} text. The file format is
-documented in the file @file{c.opt}. These files are processed by the
-script @file{opts.sh}.
+the command line, and their @option{--help} text. @xref{Options}.
@item lang-specs.h
This file provides entries for @code{default_compilers} in
@file{gcc.c} which override the default of giving an error that a
names given being their @code{language} settings). For example, the
Java front end depends on the C++ front end, so sets
@samp{lang_requires=c++}.
+@item subdir_requires
+If defined, this variable lists (space-separated) front end directories
+other than C that this front end requires to be present. For example,
+the Objective-C++ front end uses source files from the C++ and
+Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
@item target_libs
If defined, this variable lists (space-separated) targets in the top
level @file{Makefile} to build the runtime libraries for this
If defined, a space-separated list of compiler executables that will
be run by the driver. The names here will each end
with @samp{\$(exeext)}.
-@item stagestuff
-If defined, a space-separated list of files that should be moved to
-the @file{stage@var{n}} directories in each stage of bootstrap.
@item outputs
If defined, a space-separated list of files that should be generated
by @file{configure} substituting values in them. This mechanism can
gengtype.c to generate the garbage collection tables and routines for
this language. This excludes the files that are common to all front
ends. @xref{Type Information}.
-@item need_gmp
-If defined to @samp{yes}, this frontend requires the GMP library.
-Enables configure tests for GMP, which set @code{GMPLIBS} and
-@code{GMPINC} appropriately.
@end table
@file{@var{machine}} directory, containing additional machine modes to
represent condition codes. @xref{Condition Code}, for further details.
@item
+An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
+directory, containing a list of target-specific options. You can also
+add other option files using the @code{extra_options} variable in
+@file{config.gcc}. @xref{Options}.
+@item
Entries in @file{config.gcc} (@pxref{System Config, , The
@file{config.gcc} File}) for the systems with this target
architecture.
chapter of this manual.
@end itemize
-If the back end is added to the official GCC CVS repository, the
+If the back end is added to the official GCC source repository, the
following are also necessary:
@itemize @bullet
@menu
* Test Idioms:: Idioms used in testsuite code.
+* Test Directives:: Directives used within DejaGnu tests.
* Ada Tests:: The Ada language testsuites.
* C Tests:: The C language testsuites.
* libgcj Tests:: The Java library testsuites.
@node Test Idioms
@subsection Idioms Used in Testsuite Code
-In general C testcases have a trailing @file{-@var{n}.c}, starting
+In general, C testcases have a trailing @file{-@var{n}.c}, starting
with @file{-1.c}, in case other testcases with similar names are added
later. If the test is a test of some well-defined feature, it should
have a name referring to that feature such as
FIXME: discuss non-C testsuites here.
+@node Test Directives
+@subsection Directives used within DejaGnu tests
+
+Test directives appear within comments in a test source file and begin
+with @code{dg-}. Some of these are defined within DejaGnu and others
+are local to the GCC testsuite.
+
+The order in which test directives appear in a test can be important:
+directives local to GCC sometimes override information used by the
+DejaGnu directives, which know nothing about the GCC directives, so the
+DejaGnu directives must precede GCC directives.
+
+Several test directives include selectors which are usually preceded by
+the keyword @code{target} or @code{xfail}. A selector is: one or more
+target triplets, possibly including wildcard characters; a single
+effective-target keyword; or a logical expression. Depending on the
+context, the selector specifies whether a test is skipped and reported
+as unsupported or is expected to fail. Use @samp{*-*-*} to match any
+target.
+Effective-target keywords are defined in @file{target-supports.exp} in
+the GCC testsuite.
+
+A selector expression appears within curly braces and uses a single
+logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
+operand is another selector expression, an effective-target keyword,
+a single target triplet, or a list of target triplets within quotes or
+curly braces. For example:
+
+@smallexample
+@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
+@{ target @{ powerpc*-*-* && lp64 @} @}
+@{ xfail @{ lp64 || vect_no_align @} @}
+@end smallexample
+
+@table @code
+@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
+@var{do-what-keyword} specifies how the test is compiled and whether
+it is executed. It is one of:
+
+@table @code
+@item preprocess
+Compile with @option{-E} to run only the preprocessor.
+@item compile
+Compile with @option{-S} to produce an assembly code file.
+@item assemble
+Compile with @option{-c} to produce a relocatable object file.
+@item link
+Compile, assemble, and link to produce an executable file.
+@item run
+Produce and run an executable file, which is expected to return
+an exit code of 0.
+@end table
+
+The default is @code{compile}. That can be overridden for a set of
+tests by redefining @code{dg-do-what-default} within the @code{.exp}
+file for those tests.
+
+If the directive includes the optional @samp{@{ target @var{selector} @}}
+then the test is skipped unless the target system is included in the
+list of target triplets or matches the effective-target keyword.
+
+If @samp{do-what-keyword} is @code{run} and the directive includes
+the optional @samp{@{ xfail @var{selector} @}} and the selector is met
+then the test is expected to fail. The @code{xfail} clause is ignored
+for other values of @samp{do-what-keyword}; those tests can use
+directive @code{dg-xfail-if}.
+
+@item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
+This DejaGnu directive provides a list of compiler options, to be used
+if the target system matches @var{selector}, that replace the default
+options used for this set of tests.
+
+@item @{ dg-add-options @var{feature} @dots{} @}
+Add any compiler options that are needed to access certain features.
+This directive does nothing on targets that enable the features by
+default, or that don't provide them at all. It must come after
+all @code{dg-options} directives.
+
+The supported values of @var{feature} are:
+@table @code
+@item c99_runtime
+The target's C99 runtime (both headers and libraries).
+
+@item mips16_attribute
+@code{mips16} function attributes. Only MIPS targets support this feature,
+and only then in certain modes.
+@end table
+
+@item @{ dg-skip-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
+Skip the test if the test system is included in @var{selector} and if
+each of the options in @var{include-opts} is in the set of options with
+which the test would be compiled and if none of the options in
+@var{exclude-opts} is in the set of options with which the test would be
+compiled.
+
+Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for
+an empty @var{exclude-opts} list.
+
+@item @{ dg-xfail-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
+Expect the test to fail if the conditions (which are the same as for
+@code{dg-skip-if}) are met.
+
+@item @{ dg-require-@var{support} args @}
+Skip the test if the target does not provide the required support;
+see @file{gcc-dg.exp} in the GCC testsuite for the actual directives.
+These directives must appear after any @code{dg-do} directive in the test
+and before any @code{dg-additional-sources} directive.
+They require at least one argument, which can be an empty string if the
+specific procedure does not examine the argument.
+
+@item @{ dg-require-effective-target @var{keyword} @}
+Skip the test if the test target, including current multilib flags,
+is not covered by the effective-target keyword.
+This directive must appear after any @code{dg-do} directive in the test
+and before any @code{dg-additional-sources} directive.
+
+@item @{ dg-shouldfail @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
+Expect the test executable to return a nonzero exit status if the
+conditions (which are the same as for @code{dg-skip-if}) are met.
+
+@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+This DejaGnu directive appears on a source line that is expected to get
+an error message, or else specifies the source line associated with the
+message. If there is no message for that line or if the text of that
+message is not matched by @var{regexp} then the check fails and
+@var{comment} is included in the @code{FAIL} message. The check does
+not look for the string @samp{"error"} unless it is part of @var{regexp}.
+
+@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+This DejaGnu directive appears on a source line that is expected to get
+a warning message, or else specifies the source line associated with the
+message. If there is no message for that line or if the text of that
+message is not matched by @var{regexp} then the check fails and
+@var{comment} is included in the @code{FAIL} message. The check does
+not look for the string @samp{"warning"} unless it is part of @var{regexp}.
+
+@item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+The line is expected to get a message other than an error or warning.
+If there is no message for that line or if the text of that message is
+not matched by @var{regexp} then the check fails and @var{comment} is
+included in the @code{FAIL} message.
+
+@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+This DejaGnu directive appears on a source line that should not get a
+message matching @var{regexp}, or else specifies the source line
+associated with the bogus message. It is usually used with @samp{xfail}
+to indicate that the message is a known problem for a particular set of
+targets.
+
+@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
+This DejaGnu directive indicates that the test is expected to fail due
+to compiler messages that are not handled by @samp{dg-error},
+@samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail}
+has the same effect as @samp{target}.
+
+@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
+This DejaGnu directive compares @var{regexp} to the combined output
+that the test executable writes to @file{stdout} and @file{stderr}.
+
+@item @{ dg-prune-output @var{regexp} @}
+Prune messages matching @var{regexp} from test output.
+
+@item @{ dg-additional-files "@var{filelist}" @}
+Specify additional files, other than source files, that must be copied
+to the system where the compiler runs.
+
+@item @{ dg-additional-sources "@var{filelist}" @}
+Specify additional source files to appear in the compile line
+following the main test file.
+
+@item @{ dg-final @{ @var{local-directive} @} @}
+This DejaGnu directive is placed within a comment anywhere in the
+source file and is processed after the test has been compiled and run.
+Multiple @samp{dg-final} commands are processed in the order in which
+they appear in the source file.
+
+The GCC testsuite defines the following directives to be used within
+@code{dg-final}.
+
+@table @code
+@item cleanup-coverage-files
+Removes coverage data files generated for this test.
+
+@item cleanup-repo-files
+Removes files generated for this test for @option{-frepo}.
+
+@item cleanup-rtl-dump @var{suffix}
+Removes RTL dump files generated for this test.
+
+@item cleanup-tree-dump @var{suffix}
+Removes tree dump files matching @var{suffix} which were generated for
+this test.
+
+@item cleanup-saved-temps
+Removes files for the current test which were kept for @option{--save-temps}.
+
+@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
+Passes if @var{regexp} matches text in @var{filename}.
+
+@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
+Passes if @var{regexp} does not match text in @var{filename}.
+
+@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
+Passes if @var{symbol} is defined as a hidden symbol in the test's
+assembly output.
+
+@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
+Passes if @var{symbol} is not defined as a hidden symbol in the test's
+assembly output.
+
+@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} is matched exactly @var{num} times in the test's
+assembler output.
+
+@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches text in the test's assembler output.
+
+@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match text in the test's assembler output.
+
+@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches text in the test's demangled assembler output.
+
+@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match text in the test's demangled assembler
+output.
+
+@item scan-tree-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} is found exactly @var{num} times in the dump file
+with suffix @var{suffix}.
+
+@item scan-tree-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
+
+@item scan-tree-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match text in the dump file with suffix
+@var{suffix}.
+
+@item scan-tree-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches demangled text in the dump file with
+suffix @var{suffix}.
+
+@item scan-tree-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match demangled text in the dump file with
+suffix @var{suffix}.
+
+@item output-exists [@{ target/xfail @var{selector} @}]
+Passes if compiler output file exists.
+
+@item output-exists-not [@{ target/xfail @var{selector} @}]
+Passes if compiler output file does not exist.
+
+@item run-gcov @var{sourcefile}
+Check line counts in @command{gcov} tests.
+
+@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
+Check branch and/or call counts, in addition to line counts, in
+@command{gcov} tests.
+@end table
+@end table
+
@node Ada Tests
@subsection Ada Language Testsuites
tree. Additional runtime tests can be checked into this testsuite.
Regression testing of the core packages in libgcj is also covered by the
-Mauve testsuite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project}
+Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project}
develops tests for the Java Class Libraries. These tests are run as part
of libgcj testing by placing the Mauve tree within the libjava testsuite
sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
Update this file when adding new failing tests to Mauve, or when fixing
bugs in libgcj that had caused Mauve test failures.
-The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,,
-Jacks} project provides a testsuite for Java compilers that can be used
-to test changes that affect the GCJ front end. This testsuite is run as
-part of Java testing by placing the Jacks tree within the the libjava
-testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}.
-
-We encourage developers to contribute test cases to Mauve and Jacks.
+We encourage developers to contribute test cases to Mauve.
@node gcov Testing
@subsection Support for testing @command{gcov}
the end of a range without starting a new one. For example:
@smallexample
-if (i > 10 && j > i && j < 20) /* branch(27 50 75) */
- /* branch(end) */
+if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
+ /* @r{branch(end)} */
foo (i, j);
@end smallexample
@smallexample
COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
- ...[list @{@var{tstn}@} @{@var{altn}@}]]"
+ @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
@end smallexample
where @var{tsti} and @var{alti} are lists of options, with @var{tsti}