[Bug testsuite/114384] New: Use of `target c++98/c++11/c++20` etc. is not documented

[Bug testsuite/114384] New: Use of `target c++98/c++11/c++20` etc. is not documented

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114384

            Bug ID: 114384
           Summary: Use of `target c++98/c++11/c++20` etc. is not
                    documented
           Product: gcc
           Version: 14.0
            Status: UNCONFIRMED
          Keywords: documentation
          Severity: trivial
          Priority: P3
         Component: testsuite
          Assignee: unassigned at gcc dot gnu.org
          Reporter: pinskia at gcc dot gnu.org
  Target Milestone: ---

While trying to understand how to use `{ target c++20 }` option to dg-do I
noticed it is not documented in the internals manual (sourcebuild.texi) while
all other target support options are there.

It would be useful to have this documented because the rules seems to get
complex if you have a testcase which says works one way for C++11 to C++14 but
works another way for C++98 and C++17+.

Where is it valid to place these targets and even how to describe the above
would be very useful. Do we need 3 testcases, one for pre C++11, one for
C++11/C++14 and one for C++17+ ?

[Bug testsuite/114384] Use of `target c++98/c++11/c++20` etc. is not documented

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114384

--- Comment #1 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Oh and how it interacts with -std=gnu++17 vs -std=c++17 (etc.).

[Bug testsuite/114384] Use of `target c++98/c++11/c++20` etc. is not documented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114384

--- Comment #2 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Andrew Pinski from comment #0)
> While trying to understand how to use `{ target c++20 }` option to dg-do I
> noticed it is not documented in the internals manual (sourcebuild.texi)
> while all other target support options are there.
> 
> It would be useful to have this documented because the rules seems to get
> complex if you have a testcase which says works one way for C++11 to C++14
> but works another way for C++98 and C++17+.

That seems extremely unlikely in practice :-)

> 
> Where is it valid to place these targets

It's an effective-target keyword, so you can use it anywhere those are used.

> and even how to describe the above
> would be very useful. Do we need 3 testcases, one for pre C++11, one for
> C++11/C++14 and one for C++17+ ?

No, you could use { target { c++11 && c++14_down } }


c++NN means that standard and later

c++NN_down means that standard and earlier

c++NN_only means exactly what it says

The current test flags are inspected to see which -std is in effect for the
test, and if no -std is present, it assumes the default set by:
set cxx_default "c++17"

Those effective target keywords check the -std option in effect and decide
whether the test should be run or skipped.


By default, each g++ test is run multiple times with different -std options,
which will get compared to the effective-target keywords each time. The set of
tests to run is controllable by the user via:

set gpp_compile_options ""
# Allow gpp_std_list to be set in configuration files, e.g., ~/.dejagnurc
if ![info exists gpp_std_list] {
    set gpp_std_list { }
}
# Allow gpp_std_list to be set from the environment.
if [info exists env(GXX_TESTSUITE_STDS)] {
    set gpp_std_list [split $env(GXX_TESTSUITE_STDS) ","]
}

That gpp_std_list is used by g++-dg-runtest in g++-dg.exp, and if the list is
empty, the default set depends on the test:

            # See g++.exp for the initial value of this list.
            global gpp_std_list
            if { [llength $gpp_std_list] > 0 } {
                set std_list $gpp_std_list
            } else {
                # If the test requires a newer C++ version than which
                # is tested by default, use that C++ version for that
                # single test.  Or if a test checks behavior specifically for
                # one C++ version, include that version in the default list.
                # These should be adjusted whenever the default std_list is
                # updated or newer C++ effective target is added.
                if [search_for $test "\{ dg-do * \{ target c++23"] {
                    set std_list { 23 26 }
                } elseif [search_for $test "\{ dg-do * \{ target c++26"] {
                    set std_list { 26 }
                } elseif [search_for $test "c++11_only"] {
                    set std_list { 98 11 14 20 }
                } else {
                    set std_list { 98 14 17 20 }
                }
            }


(In reply to Andrew Pinski from comment #1)
> Oh and how it interacts with -std=gnu++17 vs -std=c++17 (etc.).

For g++ that seems to be controlled by the presence of any dg-options
directive:

            if [search_for $test "dg-options"] {
                set std_prefix "-std=gnu++"
            } else {
                set std_prefix "-std=c++"
            }

[Bug testsuite/114384] Use of `target c++98/c++11/c++20` etc. is not documented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114384

--- Comment #3 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Jonathan Wakely from comment #2)
> (In reply to Andrew Pinski from comment #0)
> > and even how to describe the above
> > would be very useful. Do we need 3 testcases, one for pre C++11, one for
> > C++11/C++14 and one for C++17+ ?
> 
> No, you could use { target { c++11 && c++14_down } }

And this should be equivalent:  { target c++11_only c++14_only }

[Bug testsuite/114384] Use of `target c++98/c++11/c++20` etc. is not documented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114384

--- Comment #4 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Libstdc++ uses the same effective-target keywords, but uses its own variables
to override the defaults:

# Allow v3_std_list to be set in configuration files, e.g., ~/.dejagnurc
if ![info exists v3_std_list] {
    set v3_std_list { }
}
# Allow v3_std_list to be set from the environment.
if [info exists env(GLIBCXX_TESTSUITE_STDS)] {
    set v3_std_list [split $env(GLIBCXX_TESTSUITE_STDS) ","]
}

and defaults to -std=gnu++NN unless { dg-add-options strict_std } is present:

        # If the testcase specifies a standard, use that one.
        # If not, run it under several standards, allowing GNU extensions
        # unless strict_std is requested.
        if ![search_for $test "// \{ dg-*options*-std=*++"] {
            if [search_for $test "{ dg-add-options strict_std }"] {
                set std_prefix "-std=c++"
            } else {
                set std_prefix "-std=gnu++"
            }

            # See above for the initial value of this list.
            global v3_std_list
            if { [llength $v3_std_list] > 0 } {
                set std_list $v3_std_list
            } else {
                # If the test requires a newer C++ version than which
                # is tested by default, use that C++ version for that
                # single test.
                # These should be adjusted whenever the default -std is
                # updated or newer C++ effective target is added.
                set default_std 17
                set max_std 26
                set min_std [v3-minimum-std $test $default_std $max_std]
                if { $min_std > $default_std } {
                    set std_list $min_std
                    if { $min_std != $max_std } {
                        # Also test the latest version.
                        lappend std_list "$max_std"
                    }
                } else {
                    # Only run each test once with the default -std option.
                    # This avoids increasing the run time for most testers.
                    # Libstdc++ developers can override this with v3_std_list.
                    set std_list $default_std
                }
            }

For libstdc++ this is covered (briefly) in
https://gcc.gnu.org/onlinedocs/libstdc++/manual/test.html#test.run.permutations
and https://gcc.gnu.org/onlinedocs/libstdc++/manual/test.html#test.new_tests