gcc/doc/install/passing-options-and-running-multiple-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 Passing options and running multiple testsuites
   7 ***********************************************
   8
   9 You can pass multiple options to the testsuite using the
  10 :samp:`--target_board` option of DejaGNU, either passed as part of
  11 :samp:`RUNTESTFLAGS`, or directly to :command:`runtest` if you prefer to
  12 work outside the makefiles.  For example,
  13
  14 .. code-block:: bash
  15
  16   make check-g++ RUNTESTFLAGS="--target_board=unix/-O3/-fmerge-constants"
  17
  18 will run the standard :command:`g++` testsuites ('unix' is the target name
  19 for a standard native testsuite situation), passing
  20 :samp:`-O3 -fmerge-constants` to the compiler on every test, i.e.,
  21 slashes separate options.
  22
  23 You can run the testsuites multiple times using combinations of options
  24 with a syntax similar to the brace expansion of popular shells:
  25
  26 .. code-block:: bash
  27
  28   ..."--target_board=arm-sim\{-mhard-float,-msoft-float\}\{-O1,-O2,-O3,\}"
  29
  30 (Note the empty option caused by the trailing comma in the final group.)
  31 The following will run each testsuite eight times using the :samp:`arm-sim`
  32 target, as if you had specified all possible combinations yourself:
  33
  34 .. code-block:: bash
  35
  36   --target_board='arm-sim/-mhard-float/-O1 \
  37                   arm -sim/-mhard-float/-O2 \
  38                   arm -sim/-mhard-float/-O3 \
  39                   arm -sim/-mhard-float \
  40                   arm -sim/-msoft-float/-O1 \
  41                   arm -sim/-msoft-float/-O2 \
  42                   arm -sim/-msoft-float/-O3 \
  43                   arm -sim/-msoft-float'
  44
  45 They can be combined as many times as you wish, in arbitrary ways.  This
  46 list:
  47
  48 .. code-block:: bash
  49
  50   ..."--target_board=unix/-Wextra\{-O3,-fno-strength\}\{-fomit-frame,\}"
  51
  52 will generate four combinations, all involving :samp:`-Wextra`.
  53
  54 The disadvantage to this method is that the testsuites are run in serial,
  55 which is a waste on multiprocessor systems.  For users with GNU Make and
  56 a shell which performs brace expansion, you can run the testsuites in
  57 parallel by having the shell perform the combinations and :command:`make`
  58 do the parallel runs.  Instead of using :samp:`--target_board`, use a
  59 special makefile target:
  60
  61 .. code-block:: bash
  62
  63   make -jN check-testsuite//test-target/option1/option2/...
  64
  65 For example,
  66
  67 .. code-block:: bash
  68
  69   make -j3 check-gcc//sh-hms-sim/{-m1,-m2,-m3,-m3e,-m4}/{,-nofpu}
  70
  71 will run three concurrent 'make-gcc' testsuites, eventually testing all
  72 ten combinations as described above.  Note that this is currently only
  73 supported in the :samp:`gcc` subdirectory.  (To see how this works, try
  74 typing :command:`echo` before the example given here.)