-@c Copyright (C) 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c Copyright (C) 2002, 2003, 2004, 2005, 2007 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@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} and HTML versions may be generated by
-@command{make html}. 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
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)}). HTML
+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,
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
+@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 CVS, even if they are generated files, for the
generation of online manuals to work.
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}.
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
@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
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
@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
@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 DegaGnu and others
+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:
is not covered by the effective-target keyword.
This directive must appear after any @code{dg-do} directive in the test.
+@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
@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}.
+@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
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.
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://sources.redhat.com/mauve/jacks.html,,
-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 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}