update LTO test harness README

update LTO test harness README

[Martin Sebor]

[-- Attachment #1: Type: text/plain, Size: 531 bytes --]

I was excited to find out about the recent enhancement to
the LTO test harness to support the new dg-lto-warning and
dg-lto-message directives (thanks, David).

To make them easier to find and use (there is a C++ LTO test
that uses them but no C tests yet) the attached patch updates
the README to document them.  While I was at it I made a few
minor cosmetic improvements to the README as well.

Let me know if I didn't get something quite right or if there
is something else that might be worth mentioning in the README.

Martin

[-- Attachment #2: gcc-lto-README.diff --]
[-- Type: text/x-patch, Size: 2163 bytes --]

gcc/testsuite/ChangeLog:

	* gcc.dg/lto/README (dg-lto-warning, dg-lto-message): Document new
	directives.	

Index: gcc/testsuite/gcc.dg/lto/README
===================================================================
--- gcc/testsuite/gcc.dg/lto/README	(revision 257664)
+++ gcc/testsuite/gcc.dg/lto/README	(working copy)
@@ -1,4 +1,20 @@
 This directory contains tests for link-time optimization (LTO).
+
+=== Directives ===
+
+The LTO harness recognizes the following special DejaGnu directives:
+ *  dg-lto-do - the equivalent of dg-do with a limited set of supported
+      arguments (see below),
+ *  dg-lto-options - the equivalent of dg-options with additional syntax
+      to support different sets of options for different files compiled
+      as part of the same test case,
+ *  dg-lto-warning - the equivalent of dg-warning for diagnostics expected
+      to be emitted at LTO link time,
+ *  dg-lto-message - the equivakent of dg-message for informational notes
+      expected to be emitted at LTO link time.
+
+=== Test Names ===
+
 Tests in this directory may span multiple files, so the naming of
 the files is significant.
 
@@ -9,8 +25,8 @@ executable.
 
 By default, each set of files will be compiled with list of
 options listed in LTO_OPTIONS (../../lib/lto.exp), which can be
-overwritten in the shell environment or using the 'dg-lto-options'
-command in the main file of the set (i.e., the file with _0
+overridden in the shell environment or using the 'dg-lto-options'
+directive in the main file of the set (i.e., the file with _0
 suffix).
 
 For example, given the files a_0.C a_1.C a_2.C, they will be
@@ -24,7 +40,9 @@ $ g++ -o <executable> a_0.o a_1.o a_2.o
 Tests that do not need more than one file are a special case
 where there is a single file named 'foo_0.C'.
 
-The only supported dg-lto-do option are 'assemble', 'run' and 'link'.
+=== The dg-lto-do Directive ==
+
+The only supported dg-lto-do options are 'assemble', 'run' and 'link'.
 Additionally, these can only be used in the main file.  If
 'assemble' is used, only the individual object files are
 generated.  If 'link' is used, the final executable is generated

Re: update LTO test harness README

[Richard Biener]

On Wed, 14 Feb 2018, Martin Sebor wrote:

> I was excited to find out about the recent enhancement to
> the LTO test harness to support the new dg-lto-warning and
> dg-lto-message directives (thanks, David).
> 
> To make them easier to find and use (there is a C++ LTO test
> that uses them but no C tests yet) the attached patch updates
> the README to document them.  While I was at it I made a few
> minor cosmetic improvements to the README as well.
> 
> Let me know if I didn't get something quite right or if there
> is something else that might be worth mentioning in the README.

Looks good to me.

Btw, do the new dg-lto-warning/message directives handle
fat LTO objects correctly where diagnostics usually appear twice,
once for the fat part generation and once for the ltrans part?

I wonder if we can build upon those new directives to finally
add scan-lto-tree-dump for dg-final as well... (the complication
here is to get at the dump file name but if we know the link
stage is executed we can provide a prefix to the driver IIRC).

Richard.

Re: update LTO test harness README

[David Malcolm]

On Thu, 2018-02-15 at 10:54 +0100, Richard Biener wrote:
> On Wed, 14 Feb 2018, Martin Sebor wrote:
> 
> > I was excited to find out about the recent enhancement to
> > the LTO test harness to support the new dg-lto-warning and
> > dg-lto-message directives (thanks, David).
> > 
> > To make them easier to find and use (there is a C++ LTO test
> > that uses them but no C tests yet) the attached patch updates
> > the README to document them.  While I was at it I made a few
> > minor cosmetic improvements to the README as well.
> > 
> > Let me know if I didn't get something quite right or if there
> > is something else that might be worth mentioning in the README.
> 
> Looks good to me.
> 
> Btw, do the new dg-lto-warning/message directives handle
> fat LTO objects correctly where diagnostics usually appear twice,
> once for the fat part generation and once for the ltrans part?

I didn't implement any logic for that, so I suspect not.

> I wonder if we can build upon those new directives to finally
> add scan-lto-tree-dump for dg-final as well... (the complication
> here is to get at the dump file name but if we know the link
> stage is executed we can provide a prefix to the driver IIRC).
> 
> Richard.