gcc/doc/gccint/testsuites/directives-used-within-dejagnu-tests/selecting-targets-to-which-a-test-applies.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 .. _selectors:
   7
   8 Selecting targets to which a test applies
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 Several test directives include :samp:`{selector}` s to limit the targets
  12 for which a test is run or to declare that a test is expected to fail
  13 on particular targets.
  14
  15 A selector is:
  16
  17 * one or more target triplets, possibly including wildcard characters;
  18   use :samp:`*-*-*` to match any target
  19
  20 * a single effective-target keyword (see :ref:`effective-target-keywords`)
  21
  22 * a list of compiler options that should be included or excluded
  23   (as described in more detail below)
  24
  25 * a logical expression
  26
  27 Depending on the context, the selector specifies whether a test is
  28 skipped and reported as unsupported or is expected to fail.  A context
  29 that allows either :samp:`target` or :samp:`xfail` also allows
  30 :samp:`{ target {selector1} xfail {selector2} }`
  31 to skip the test for targets that don't match :samp:`{selector1}` and the
  32 test to fail for targets that match :samp:`{selector2}`.
  33
  34 A selector expression appears within curly braces and uses a single
  35 logical operator: one of :samp:`!`, :samp:`&&`, or :samp:`||`.  An
  36 operand is one of the following:
  37
  38 * another selector expression, in curly braces
  39
  40 * an effective-target keyword, such as ``lp64``
  41
  42 * a single target triplet
  43
  44 * a list of target triplets within quotes or curly braces
  45
  46 * one of the following:
  47
  48   :samp:`{ any-opts {opt1} ... {optn} }`
  49     Each of :samp:`{opt1}` to :samp:`{optn}` is a space-separated list of option globs.
  50     The selector expression evaluates to true if, for one of these strings,
  51     every glob in the string matches an option that was passed to the compiler.
  52     For example:
  53
  54     .. code-block:: c++
  55
  56       { any-opts "-O3 -flto" "-O[2g]" }
  57
  58     is true if any of the following are true:
  59
  60     * :option:`-O2` was passed to the compiler
  61
  62     * :option:`-Og` was passed to the compiler
  63
  64     * both :option:`-O3` and :option:`-flto` were passed to the compiler
  65
  66     This kind of selector can only be used within ``dg-final`` directives.
  67     Use ``dg-skip-if``, ``dg-xfail-if`` or ``dg-xfail-run-if`` to
  68     skip whole tests based on options, or to mark them as expected to fail
  69     with certain options.
  70
  71   :samp:`{ no-opts {opt1} ... {optn} }`
  72     As for ``any-opts`` above, each of :samp:`{opt1}` to :samp:`{optn}` is a
  73     space-separated list of option globs.  The selector expression
  74     evaluates to true if, for all of these strings, there is at least
  75     one glob that does not match an option that was passed to the compiler.
  76     It is shorthand for:
  77
  78     .. code-block:: c++
  79
  80       { ! { any-opts opt1 ... optn } }
  81
  82     For example:
  83
  84     .. code-block:: c++
  85
  86       { no-opts "-O3 -flto" "-O[2g]" }
  87
  88     is true if all of the following are true:
  89
  90     * :option:`-O2` was not passed to the compiler
  91
  92     * :option:`-Og` was not passed to the compiler
  93
  94     * at least one of :option:`-O3` or :option:`-flto` was not passed to the compiler
  95
  96     Like ``any-opts``, this kind of selector can only be used within
  97     ``dg-final`` directives.
  98
  99 Here are some examples of full target selectors:
 100
 101 .. code-block:: c++
 102
 103   { target { ! "hppa*-*-* ia64*-*-*" } }
 104   { target { powerpc*-*-* && lp64 } }
 105   { xfail { lp64 || vect_no_align } }
 106   { xfail { aarch64*-*-* && { any-opts "-O2" } } }