[PATCH] libstdc++/doc: Document generate_canonical and variant compat macros.

[Jonathan Wakely]

On Mon, 22 Dec 2025 at 11:06, Tomasz Kamiński <tkaminsk@redhat.com> wrote:
>
> The _GLIBCXX_USE_OLD_GENERATE_CANONICAL was introduced by
> r16-6177-g866bc8a9214b1d that implemented P0952R2 [1] resolution
> for LWG2524 as DR against C++20.
>
> The _GLIBCXX_USE_VARIANT_CXX17_OLD_ABI was introduced by
> r16-6301-gb3c167b61fd75f that resovled PR112591.
>
> [1] https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0952r2.html
>
> libstdc++-v3/ChangeLog:
>
>         * doc/html/manual/using_macros.html: Regenerate.
>         * doc/xml/manual/using.xml: Add entries for
>         _GLIBCXX_USE_OLD_GENERATE_CANONICAL and
>         _GLIBCXX_USE_VARIANT_CXX17_OLD_ABI.
> ---
> OK for trunk?
>
>  .../doc/html/manual/using_macros.html         | 12 +++++++++++
>  libstdc++-v3/doc/xml/manual/using.xml         | 20 +++++++++++++++++++
>  2 files changed, 32 insertions(+)
>
> diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html
> index c1406ec76f7..08649c1dfaa 100644
> --- a/libstdc++-v3/doc/html/manual/using_macros.html
> +++ b/libstdc++-v3/doc/html/manual/using_macros.html
> @@ -137,4 +137,16 @@
>         When not defined, durations, time points, and calendar types are
>         available for freestanding, but the standard clocks and the time zone
>         database are not (because they require OS support).
> +      </p></dd><dt><span class="term"><code class="code">_GLIBCXX_USE_OLD_GENERATE_CANONICAL</code></span></dt><dd><p>
> +       Undefined by default. When defined <code class="code">generate_canonical</code>
> +       reverts to algorithm used by before implementation of
> +       <a class="link" href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0952r2.html" target="_top">P0952
> +       A new specification for std::generate_canonical</a> in GCC-16.
> +      </p></dd><dt><span class="term"><code class="code">_GLIBCXX_USE_VARIANT_CXX17_OLD_ABI</code></span></dt><dd><p>
> +       Undefined by default. When defined <code class="code">variant</code> in C++17
> +       mode will revert to non-conforming implementation used prior
> +       resolution of
> +       <a class="link" href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=112591" target="_top">PR112591</a>
> +       in GCC-16.
> +       Has no impact for C++20 or later modes.
>        </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_dual_abi.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Headers </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Dual ABI</td></tr></table></div></body></html>
> \ No newline at end of file
> diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
> index bec5419d587..0a9f9f6e46c 100644
> --- a/libstdc++-v3/doc/xml/manual/using.xml
> +++ b/libstdc++-v3/doc/xml/manual/using.xml
> @@ -1343,6 +1343,26 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
>         database are not (because they require OS support).
>        </para>
>      </listitem></varlistentry>
> +    <varlistentry><term><code>_GLIBCXX_USE_OLD_GENERATE_CANONICAL</code></term>
> +    <listitem>
> +      <para>
> +       Undefined by default. When defined <code>generate_canonical</code>
> +       reverts to algorithm used by before implementation of

"reverts to the algorithm used prior to the implementation of"

> +       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0952r2.html">P0952
> +       A new specification for std::generate_canonical</link> in GCC-16.
> +      </para>
> +    </listitem></varlistentry>
> +    <varlistentry><term><code>_GLIBCXX_USE_VARIANT_CXX17_OLD_ABI</code></term>
> +    <listitem>
> +      <para>
> +       Undefined by default. When defined <code>variant</code> in C++17
> +       mode will revert to non-conforming implementation used prior

"mode will revert to the non-conforming implementation used prior to the"

OK with those two changes (and don't forget to regenerate the HTML).
Thanks for updating the docs with this.

> +       resolution of
> +       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=112591">PR112591</link>
> +       in GCC-16.
> +       Has no impact for C++20 or later modes.
> +      </para>
> +    </listitem></varlistentry>
>      </variablelist>
>
>    </section>
> --
> 2.52.0
>