gcc/doc/install/testing.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 .. index:: Testing, Testing, Testsuite
   7
   8 .. _testing:
   9
  10 Testing
  11 -------
  12
  13 Before you install GCC, we encourage you to run the testsuites and to
  14 compare your results with results from a similar configuration that have
  15 been submitted to the
  16 `gcc-testresults mailing list <https://gcc.gnu.org/ml/gcc-testresults/>`_.
  17 Some of these archived results are linked from the build status lists
  18 at https://gcc.gnu.org/buildstat.html, although not everyone who
  19 reports a successful build runs the testsuites and submits the results.
  20 This step is optional and may require you to download additional software,
  21 but it can give you confidence in your new GCC installation or point out
  22 problems before you install and start using your new GCC.
  23
  24 First, you must have :ref:`downloaded the testsuites <downloading-the-source>`.
  25 These are part of the full distribution, but if you downloaded the
  26 'core' compiler plus any front ends, you must download the testsuites
  27 separately.
  28
  29 Second, you must have the testing tools installed.  This includes
  30 `DejaGnu <https://www.gnu.org/software/dejagnu/>`_, Tcl, and Expect;
  31 the DejaGnu site has links to these.
  32 Some optional tests also require Python3 and pytest module.
  33
  34 If the directories where :command:`runtest` and :command:`expect` were
  35 installed are not in the :envvar:`PATH`, you may need to set the following
  36 environment variables appropriately, as in the following example (which
  37 assumes that DejaGnu has been installed under :samp:`/usr/local`):
  38
  39 .. code-block:: bash
  40
  41   TCL_LIBRARY = /usr/local/share/tcl8.0
  42   DEJAGNULIBS = /usr/local/share/dejagnu
  43
  44 (On systems such as Cygwin, these paths are required to be actual
  45 paths, not mounts or links; presumably this is due to some lack of
  46 portability in the DejaGnu code.)
  47
  48 Finally, you can run the testsuite (which may take a long time):
  49
  50 .. code-block:: bash
  51
  52   cd objdir; make -k check
  53
  54 This will test various components of GCC, such as compiler
  55 front ends and runtime libraries.  While running the testsuite, DejaGnu
  56 might emit some harmless messages resembling
  57 :samp:`WARNING: Couldn't find the global config file.` or
  58 :samp:`WARNING: Couldn't find tool init file` that can be ignored.
  59
  60 If you are testing a cross-compiler, you may want to run the testsuite
  61 on a simulator as described at https://gcc.gnu.org/simtest-howto.html.
  62
  63 .. toctree::
  64   :maxdepth: 2
  65
  66   how-can-you-run-the-testsuite-on-selected-tests
  67   passing-options-and-running-multiple-testsuites
  68   how-to-interpret-test-results
  69   submitting-test-results