gccint: Test Idioms

1 
1 7.1 Idioms Used in Testsuite Code
1 =================================
1 
1 In general, C testcases have a trailing '-N.c', starting with '-1.c', in
1 case other testcases with similar names are added later.  If the test is
1 a test of some well-defined feature, it should have a name referring to
1 that feature such as 'FEATURE-1.c'.  If it does not test a well-defined
1 feature but just happens to exercise a bug somewhere in the compiler,
1 and a bug report has been filed for this bug in the GCC bug database,
1 'prBUG-NUMBER-1.c' is the appropriate form of name.  Otherwise (for
1 miscellaneous bugs not filed in the GCC bug database), and previously
1 more generally, test cases are named after the date on which they were
1 added.  This allows people to tell at a glance whether a test failure is
1 because of a recently found bug that has not yet been fixed, or whether
1 it may be a regression, but does not give any other information about
1 the bug or where discussion of it may be found.  Some other language
1 testsuites follow similar conventions.
1 
1  In the 'gcc.dg' testsuite, it is often necessary to test that an error
1 is indeed a hard error and not just a warning--for example, where it is
1 a constraint violation in the C standard, which must become an error
1 with '-pedantic-errors'.  The following idiom, where the first line
1 shown is line LINE of the file and the line that generates the error, is
1 used for this:
1 
1      /* { dg-bogus "warning" "warning in place of error" } */
1      /* { dg-error "REGEXP" "MESSAGE" { target *-*-* } LINE } */
1 
1  It may be necessary to check that an expression is an integer constant
1 expression and has a certain value.  To check that 'E' has value 'V', an
1 idiom similar to the following is used:
1 
1      char x[((E) == (V) ? 1 : -1)];
1 
1  In 'gcc.dg' tests, '__typeof__' is sometimes used to make assertions
1 about the types of expressions.  See, for example,
1 'gcc.dg/c99-condexpr-1.c'.  The more subtle uses depend on the exact
1 rules for the types of conditional expressions in the C standard; see,
1 for example, 'gcc.dg/c99-intconst-1.c'.
1 
1  It is useful to be able to test that optimizations are being made
1 properly.  This cannot be done in all cases, but it can be done where
1 the optimization will lead to code being optimized away (for example,
1 where flow analysis or alias analysis should show that certain code
1 cannot be called) or to functions not being called because they have
1 been expanded as built-in functions.  Such tests go in
1 'gcc.c-torture/execute'.  Where code should be optimized away, a call to
1 a nonexistent function such as 'link_failure ()' may be inserted; a
1 definition
1 
1      #ifndef __OPTIMIZE__
1      void
1      link_failure (void)
1      {
1        abort ();
1      }
1      #endif
1 
1 will also be needed so that linking still succeeds when the test is run
1 without optimization.  When all calls to a built-in function should have
1 been optimized and no calls to the non-built-in version of the function
1 should remain, that function may be defined as 'static' to call 'abort
1 ()' (although redeclaring a function as static may not work on all
1 targets).
1 
1  All testcases must be portable.  Target-specific testcases must have
1 appropriate code to avoid causing failures on unsupported systems;
1 unfortunately, the mechanisms for this differ by directory.
1 
1  FIXME: discuss non-C testsuites here.
1