This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]