Re: [doc patch] describe test directives in internals manual

[Gerald Pfeifer <gerald at pfeifer dot com>]

On Tue, 11 Jan 2005, Janis Johnson wrote:
> 2005-01-11  Janis Johnson  <janis187@us.ibm.com>
> 	    Giovanni Bajo  <giovannibajo@gcc.gnu.org>
> 
> 	* doc/sourcebuild.texi (Test Directives): New.

I believe Mark already approved this, so I just provide a comment or two.

> Index: doc/sourcebuild.texi
> ===================================================================
> +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, or else a
> +single effective-target keyword.  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 or, in the case of unusual effective targets that are
> +used only for a limited number of tests, in local @file{.exp} files.

"local" here means "in the current directory"?

> +@table @code
> +@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
> +This DejaGnu directive must appear before test directives that are
> +defined within the GCC test framework.

Isn't this redundant with the general rule of having DejaGnu directives
before GCC directives?

> +Produce and run an executable file, expected to exit with 0.

"expected to terminate with exit code 0" or "return an exit code of 0",
or something along these lines?

> +@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
> +each of the options in @var{include-opts} will be used to compile the
> +test and none of the options in @var{exclude-opts} will be used to
> +compile the test.

I'm afraid I don't understand this one.  How is the relation between
selector and include-opts/exclude-opts?  

"would" instead of "will", perhaps?

> +@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
> +This DejaGnu directive indicates that error messages not specified by
> +other directives are expected somewhere in the test.

That is, they need to occur?  Or is this a weaker condition, and they
may occur and will be ignored in this case?

Gerald