This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [doc] Fixes to testsuite chapter in sourcebuild.texi
Janis Johnson <janis.marie.johnson@gmail.com> writes:
>> I checked in smaller changes a couple of days. ago. ?Here's a much bigger
>> patch with the Test Directives section broken up into smaller pieces and
>> new subsections for the things that Rainer wanted to see documented,
>> including effective-target keywords. ?Rainer, how does this look to you?
Great, thanks for doing this. While checking it, I've fixed a couple of
nits (mostly markup), plus:
* The reference to lib/gcc-dg.exp is superfluous now that all
dg-require-<support> directives are explained.
* I've clarified the dg-require-{iconv, profiling, visibility}
explanations. The arguments used in the testsuite are just examples.
* dg-require-compat-dfp and dg-final scan-module were missing, just as
the lto-specific dg-extra-ld-options and dg-suppress-ld-options, and
profile-related dg-final-generate and dg-final-use.
The combined patch passes make doc/gccint.info and make doc/gccint.dvi
and looks reasonable. I haven't updated the ChangeLog entry, not sure
how detailed that needs to be here.
Rainer
--
-----------------------------------------------------------------------------
Rainer Orth, Center for Biotechnology, Bielefeld University
--- sourcebuild.texi.base Sat Mar 20 18:33:15 2010
+++ sourcebuild.texi Sat Mar 20 22:54:06 2010
@@ -1012,7 +1012,7 @@
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.
-For supported values of @var{feature} @xref{Add Options, ,}.
+For supported values of @var{feature} see @ref{Add Options, ,}.
@end table
@subsubsection Modify the test timeout value
@@ -1081,7 +1081,7 @@
/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
@end smallexample
-To skip a test unless option @code{-OS} is present:
+To skip a test unless option @code{-Os} is present:
@smallexample
/* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
@@ -1102,8 +1102,7 @@
@xref{Effective-Target Keywords, , }.
@item @{ dg-require-@var{support} args @}
-Skip the test if the target does not provide the required support;
-see @file{lib/gcc-dg.exp} in the GCC testsuite for the actual directives.
+Skip the test if the target does not provide the required support.
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
@@ -1140,7 +1139,7 @@
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}.
+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
@@ -1148,7 +1147,7 @@
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}.
+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.
@@ -1207,7 +1206,7 @@
@node Selectors
@subsection Selecting targets to which a test applies
-Several test directives include @samp{selectors} to limit the targets
+Several test directives include @var{selector}s to limit the targets
for which a test is run or to declare that a test is expected to fail
on particular targets.
@@ -1298,13 +1297,13 @@
@table @code
@item fortran_integer_16
-Target supports Fortran @code{integer} that is 16 bits or longer.
+Target supports Fortran @code{integer} that is 16 bytes or longer.
@item fortran_large_int
-Target supports Fortran integer kinds larger than @code{integer(8)}.
+Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
@item fortran_large_real
-Target supports Fortran real kinds larger than @code{real(8)}.
+Target supports Fortran @code{real} kinds larger than @code{real(8)}.
@end table
@subsubsection Vector-specific attributes
@@ -1365,7 +1364,7 @@
@item vect_extract_even_odd_wide
Target supports vector even/odd element extraction of vectors with elements
-SImode or larger.
+@code{SImode} or larger.
@item vect_interleave
Target supports vector interleaving.
@@ -1471,7 +1470,7 @@
test system can execute decimal floating point tests.
@item hard_dfp
-Target generates DFP instructions with current options.
+Target generates decimal floating point instructions with current options.
@end table
@subsubsection ARM-specific attributes
@@ -1604,8 +1603,8 @@
@item ultrasparc_hw
Test environment appears to run executables on a simulator that
-accepts only EM_SPARC executables and chokes on EM_SPARC32PLUS
-or EM_SPARCV9 executables.
+accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
+or @code{EM_SPARCV9} executables.
@item vect_cmdline_needed
Target requires a command line argument to enable a SIMD instruction set.
@@ -1671,7 +1670,7 @@
@item stdint_types
Target has the basic signed and unsigned C types in @code{stdint.h}.
-This will be obsolete when GCC ensures a working @code{stdint.h} or
+This will be obsolete when GCC ensures a working @code{stdint.h} for
all targets.
@item trampolines
@@ -1763,7 +1762,7 @@
Target supports @option{-static}.
@item static_libgfortran
-Target supports statically linking libgfortran.
+Target supports statically linking @samp{libgfortran}.
@item string_merging
Target supports merging string constants at link time.
@@ -1826,7 +1825,14 @@
Target supports compiling @code{xop} instructions.
@end table
-@subsubsection Local to tests in @code{gcc.target-supports}
+@subsubsection Local to tests in @code{gcc.target/spu/ea}
+
+@table @code
+@item ealib
+Target @code{__ea} library functions are available.
+@end table
+
+@subsubsection Local to tests in @code{gcc.test-framework}
@table @code
@item no
@@ -1836,13 +1842,6 @@
Always returns 1.
@end table
-@subsubsection Local to tests in @code{gcc.target/spu/ea}
-
-@table @code
-@item ealib
-Target @code{__ea} library functions are available.
-@end table
-
@node Add Options
@subsection Features for @code{dg-add-options}
@@ -1872,18 +1871,18 @@
A few of the @code{dg-require} directives take arguments.
@table @code
-@item dg-require-iconv @var{arg}
-Skip the test if the target does not support iconv. @var{arg} is
-one of "@code{IBM1047}", "@code{ISO-8859-1}", or "@code{ISO-8859-2}".
-
-@item dg-require-profiling @var{arg}
-Skip the test if the target does not support profiling. @var{arg} is one
-of "@code{-p}", "@code{-pg}", "@code{-fprofile-arcs}",
-or "@code{-fprofile-generate=.}".
-
-@item dg-require-visibility @var{arg}
-Skip the test if the target does not support the @samp{visibility} attribute.
-@var{arg} is one of "@code{internal}", "@code{protected}", or "".
+@item dg-require-iconv @var{codeset}
+Skip the test if the target does not support iconv. @var{codeset} is
+the codeset to convert to.
+
+@item dg-require-profiling @var{profopt}
+Skip the test if the target does not support profiling with option
+@var{profopt}.
+
+@item dg-require-visibility @var{vis}
+Skip the test if the target does not support the @code{visibility} attribute.
+If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
+checked, for @code{visibility("@var{vis}")} otherwise.
@end table
The original @code{dg-require} directives were defined before there
@@ -1894,12 +1893,16 @@
@item dg-require-alias ""
Skip the test if the target does not support the @samp{alias} attribute.
+@item dg-require-compat-dfp ""
+Skip this test unless both compilers in a @file{compat} testsuite
+support decimal floating point.
+
@item dg-require-cxa-atexit ""
Skip the test if the target does not support @code{__cxa_atexit}.
-This is equivalent to "@code{dg-require-effective-target cxa_atexit}".
+This is equivalent to @code{dg-require-effective-target cxa_atexit}.
@item dg-require-dll ""
-Skip the test if the targes dos not support DLL attributes.
+Skip the test if the target does not support DLL attributes.
@item dg-require-fork ""
Skip the test if the target does not support @code{fork}.
@@ -1907,7 +1910,7 @@
@item dg-require-gc-sections ""
Skip the test if the target's linker does not support the
@code{--gc-sections} flags.
-This is equivalent to "@code{dg-require-effective-target gc-sections}".
+This is equivalent to @code{dg-require-effective-target gc-sections}.
@item dg-require-host-local ""
Skip the test if the host is remote, rather than the same as the build
@@ -1920,7 +1923,7 @@
@item dg-require-named-sections ""
Skip the test is the target does not support named sections.
-This is equivalent to "@code{dg-require-effective-target named_sections}".
+This is equivalent to @code{dg-require-effective-target named_sections}.
@item dg-require-weak ""
Skip the test if the target does not support weak symbols.
@@ -1942,6 +1945,8 @@
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-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
+Passes if @var{regexp} matches in Fortran module @var{module}.
@end table
@subsubsection Scan the assembly output
@@ -2013,7 +2018,7 @@
@table @code
@item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
-Pases if the pattern is present in the final executable.
+Passes if the pattern is present in the final executable.
@end table
@subsubsection Checks for @command{gcov} tests
@@ -2049,7 +2054,7 @@
Removes RTL dump files generated for this test.
@item cleanup-saved-temps
-Removes files for the current test which were kept for @option{--save-temps}.
+Removes files for the current test which were kept for @option{-save-temps}.
@item cleanup-tree-dump @var{suffix}
Removes tree dump files matching @var{suffix} which were generated for
@@ -2064,7 +2069,7 @@
@uref{http://www.adaic.org/compilers/acats/2.5}.
These tests are integrated in the GCC testsuite in the
-@file{gcc/testsuite/ada/acats} directory, and
+@file{ada/acats} directory, and
enabled automatically when running @code{make check}, assuming
the Ada language has been enabled when configuring GCC@.
@@ -2251,6 +2256,12 @@
This directive provides a list of one or more sets of compiler options
to override @var{LTO_OPTIONS}. Each test will be compiled and run with
each of these sets of options.
+
+@item @{ dg-extra-ld-options @var{options} @}
+This directive adds @var{options} to the linker options used.
+
+@item @{ dg-suppress-ld-options @var{options} @}
+This directive removes @var{options} from the set of linker options used.
@end table
@node gcov Testing
@@ -2356,6 +2367,14 @@
@item PROFOPT_OPTIONS
list of options with which to run each test, similar to the lists for
torture tests
+
+@item @{ dg-final-generate @{ @var{local-directive} @} @}
+This directive is similar to @code{dg-final}, but the
+@var{local-directive} is run after the generation of profile data.
+
+@item @{ dg-final-use @{ @var{local-directive} @} @}
+The @var{local-directive} is run after the profile data have been
+used.
@end table
@node compat Testing