gcc/doc/gccint/testsuites/c-language-testsuites.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _c-tests:
   7
   8 C Language Testsuites
   9 *********************
  10
  11 GCC contains the following C language testsuites, in the
  12 :samp:`gcc/testsuite` directory:
  13
  14 :samp:`gcc.dg`
  15   This contains tests of particular features of the C compiler, using the
  16   more modern :samp:`dg` harness.  Correctness tests for various compiler
  17   features should go here if possible.
  18
  19   Magic comments determine whether the file
  20   is preprocessed, compiled, linked or run.  In these tests, error and warning
  21   message texts are compared against expected texts or regular expressions
  22   given in comments.  These tests are run with the options :samp:`-ansi -pedantic`
  23   unless other options are given in the test.  Except as noted below they
  24   are not run with multiple optimization options.
  25
  26 :samp:`gcc.dg/compat`
  27   This subdirectory contains tests for binary compatibility using
  28   :samp:`lib/compat.exp`, which in turn uses the language-independent support
  29   (see :ref:`compat-testing`).
  30
  31 :samp:`gcc.dg/cpp`
  32   This subdirectory contains tests of the preprocessor.
  33
  34 :samp:`gcc.dg/debug`
  35   This subdirectory contains tests for debug formats.  Tests in this
  36   subdirectory are run for each debug format that the compiler supports.
  37
  38 :samp:`gcc.dg/format`
  39   This subdirectory contains tests of the :option:`-Wformat` format
  40   checking.  Tests in this directory are run with and without
  41   :option:`-DWIDE`.
  42
  43 :samp:`gcc.dg/noncompile`
  44   This subdirectory contains tests of code that should not compile and
  45   does not need any special compilation options.  They are run with
  46   multiple optimization options, since sometimes invalid code crashes
  47   the compiler with optimization.
  48
  49 :samp:`gcc.dg/special`
  50   .. todo:: describe this
  51
  52 :samp:`gcc.c-torture`
  53   This contains particular code fragments which have historically broken easily.
  54   These tests are run with multiple optimization options, so tests for features
  55   which only break at some optimization levels belong here.  This also contains
  56   tests to check that certain optimizations occur.  It might be worthwhile to
  57   separate the correctness tests cleanly from the code quality tests, but
  58   it hasn't been done yet.
  59
  60 :samp:`gcc.c-torture/compat`
  61   .. todo:: describe this
  62
  63   This directory should probably not be used for new tests.
  64
  65 :samp:`gcc.c-torture/compile`
  66   This testsuite contains test cases that should compile, but do not
  67   need to link or run.  These test cases are compiled with several
  68   different combinations of optimization options.  All warnings are
  69   disabled for these test cases, so this directory is not suitable if
  70   you wish to test for the presence or absence of compiler warnings.
  71   While special options can be set, and tests disabled on specific
  72   platforms, by the use of :samp:`.x` files, mostly these test cases
  73   should not contain platform dependencies.
  74
  75   .. todo:: discuss how defines such as ``STACK_SIZE`` are used
  76
  77 :samp:`gcc.c-torture/execute`
  78   This testsuite contains test cases that should compile, link and run;
  79   otherwise the same comments as for :samp:`gcc.c-torture/compile` apply.
  80
  81 :samp:`gcc.c-torture/execute/ieee`
  82   This contains tests which are specific to IEEE floating point.
  83
  84 :samp:`gcc.c-torture/unsorted`
  85   .. todo:: describe this
  86
  87   This directory should probably not be used for new tests.
  88
  89 :samp:`gcc.misc-tests`
  90   This directory contains C tests that require special handling.  Some
  91   of these tests have individual expect files, and others share
  92   special-purpose expect files:
  93
  94   :samp:`bprob*.c`
  95     Test :option:`-fbranch-probabilities` using
  96     :samp:`gcc.misc-tests/bprob.exp`, which
  97     in turn uses the generic, language-independent framework
  98     (see :ref:`profopt-testing`).
  99
 100   :samp:`gcov*.c`
 101     Test :command:`gcov` output using :samp:`gcov.exp`, which in turn uses the
 102     language-independent support (see :ref:`gcov-testing`).
 103
 104   :samp:`i386-pf-*.c`
 105     Test i386-specific support for data prefetch using :samp:`i386-prefetch.exp`.
 106
 107 :samp:`gcc.test-framework`
 108
 109   :samp:`dg-*.c`
 110     Test the testsuite itself using :samp:`gcc.test-framework/test-framework.exp`.
 111
 112 .. todo:: merge in :samp:`testsuite/README.gcc` and discuss the format of
 113   test cases and magic comments more.