[Bug libstdc++/126675] Document std::__format::__do_vformat_to or make the explicit instantiation extern

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

--- Comment #8 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Right, we have committed to a stable ABI for C++20 mode. If you compile with
C++20 then you get a reference to the explicit instantiations, and use the
definition in libstdc++.so.

If you compile with C++23 then you don't get a reference to that explicit
instantiation, because the explicit instantiation declarations are hidden by
the #if condition. And so you get implicit instantiations in your object files,
and it compiles slower.

We are not going to document the __do_vformat_to symbol. It's an implementation
detail and the explicit instantiation is used exactly when we intend it to be
used, i.e. when using C++20 which has a stable ABI.


What we could do is something like:

--- a/libstdc++-v3/include/std/format
+++ b/libstdc++-v3/include/std/format
@@ -5416,7 +5416,8 @@ namespace __format
 // instantiates formatters for types stored in basic_format_arg, we can
 // support only single encoding, in this case unicode. This should cover
 // most common use cases.
-#if __cplusplus <= 202002L && _GLIBCXX_EXTERN_TEMPLATE
+#if _GLIBCXX_EXTERN_TEMPLATE \
+    && (__cplusplus <= 202002L || _GLIBCXX_UNSTABLE_BUT_I_DO_NOT_CARE)
     extern template _Sink_iter<char>
       __do_vformat_to<char, 1>(_Sink_iter<char>, string_view,
                               format_context&);


This would give an opt-in to the benefits of the explicit instantiation,
requiring users to explicitly choose something that might not work in future if
we change how std::format works for C++23 mode.