From: Tomasz Kamiński <tkaminsk@redhat.com>
Date: Mon, 22 Dec 2025 10:53:45 +0000 (+0100)
Subject: libstdc++/doc: Document generate_canonical and variant compat macros.
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6a8b3a63089745b945bebe7ba21104060a2edbb1;p=thirdparty%2Fgcc.git

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

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.

Reviewed-by: Jonathan Wakely <jwakely@redhat.com>
Signed-off-by: Tomasz Kamiński <tkaminsk@redhat.com>
---

diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html
index c1406ec76f7..b1d05d99d76 100644
--- a/libstdc++-v3/doc/html/manual/using_macros.html
+++ b/libstdc++-v3/doc/html/manual/using_macros.html
@@ -137,4 +137,14 @@
 	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 the algorithm used prior to the 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 the non-conforming implementation used prior to the
+	<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..8adfecfe54b 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 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 the non-conforming implementation used prior to the
+	<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>