[PATCH] PR69699 document why __GLIBCXX__ macro is useless
Jonathan Wakely
jwakely@redhat.com
Tue Jan 17 15:36:00 GMT 2017
The closest thing we have to a version macro in libstdc++ is
__GLIBCXX__ which holds the valid of gcc/DATESTAMP from the source
tree. That's useless for version checking or feature testing because
snapshots have arbitrary values and there's no total order across
branches (a later date does not mean a "better" release with more
features implemented). This updates the docs to point out it isn't
very useful. I've also removed the list of release dates, linking to
the online release timeline instead, so we don't have to keep adding
to the list. This means the information is not included in the sources
and you need to be online to find a date, but since the dates are not
very useful anyway I don't think this is a problem.
PR libstdc++/69699
* doc/xml/manual/abi.xml (abi.versioning.history): Explain why the
_GLIBCXX__ macro is not useful. Remove redundant date information
and link to the GCC release timeline.
(abi.versioning.active): Move partial sentence into the previous
paragraph.
* doc/html/*: Regenerate.
Committed to trunk.
-------------- next part --------------
commit 5087726efb1165d835c745fe6bd693d73aa0f389
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Tue Jan 17 15:15:55 2017 +0000
PR69699 document why __GLIBCXX__ macro is useless
PR libstdc++/69699
* doc/xml/manual/abi.xml (abi.versioning.history): Explain why the
_GLIBCXX__ macro is not useful. Remove redundant date information
and link to the GCC release timeline.
(abi.versioning.active): Move partial sentence into the previous
paragraph.
* doc/html/*: Regenerate.
diff --git a/libstdc++-v3/doc/xml/manual/abi.xml b/libstdc++-v3/doc/xml/manual/abi.xml
index 8e4a3fa..c818bd8 100644
--- a/libstdc++-v3/doc/xml/manual/abi.xml
+++ b/libstdc++-v3/doc/xml/manual/abi.xml
@@ -393,10 +393,32 @@ compatible.
<para>
This macro is defined in the file "c++config" in the
- "libstdc++-v3/include/bits" directory. (Up to GCC 4.1.0, it was
- changed every night by an automated script. Since GCC 4.1.0, it is
- the same value as gcc/DATESTAMP.)
+ "libstdc++-v3/include/bits" directory. Up to GCC 4.1.0, it was
+ changed every night by an automated script. Since GCC 4.1.0 it is set
+ during configuration to the same value as
+ <filename>gcc/DATESTAMP</filename>, so for an official release its value
+ is the same as the date of the release, which is given in the <link
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC Release
+ Timeline</link>.
</para>
+
+ <para>
+ This macro is not useful for determining whether a particular feature is
+ supported by the version of libstdc++ you are using. The date of a release
+ might be after a feature was added to the development trunk, but the
+ release could be from an older branch. For example, in the 5.4.0 release
+ the macro has the value 20160603 which is greater than the 20160427 value
+ of the macro in the 6.1.0 release, but there are features supported in the
+ 6.1.0 release that are not supported in 5.4.0 release.
+ You also can't test for the the exact values listed below to try and
+ identify a release, because a snapshot taken from the gcc-5-branch on
+ 2016-04-27 would have the same value for the macro as the 6.1.0 release
+ despite being a different version.
+ Many GNU/Linux distributions build their GCC packages from snapshots, so
+ the macro can have dates that doesn't correspond to official releases.
+ </para>
+
<para>
It is versioned as follows:
</para>
@@ -427,41 +449,12 @@ compatible.
<listitem><para>GCC 4.0.1: 20050707</para></listitem>
<listitem><para>GCC 4.0.2: 20050921</para></listitem>
<listitem><para>GCC 4.0.3: 20060309</para></listitem>
- <listitem><para>GCC 4.1.0: 20060228</para></listitem>
- <listitem><para>GCC 4.1.1: 20060524</para></listitem>
- <listitem><para>GCC 4.1.2: 20070214</para></listitem>
- <listitem><para>GCC 4.2.0: 20070514</para></listitem>
- <listitem><para>GCC 4.2.1: 20070719</para></listitem>
- <listitem><para>GCC 4.2.2: 20071007</para></listitem>
- <listitem><para>GCC 4.2.3: 20080201</para></listitem>
- <listitem><para>GCC 4.2.4: 20080519</para></listitem>
- <listitem><para>GCC 4.3.0: 20080306</para></listitem>
- <listitem><para>GCC 4.3.1: 20080606</para></listitem>
- <listitem><para>GCC 4.3.2: 20080827</para></listitem>
- <listitem><para>GCC 4.3.3: 20090124</para></listitem>
- <listitem><para>GCC 4.3.4: 20090804</para></listitem>
- <listitem><para>GCC 4.3.5: 20100522</para></listitem>
- <listitem><para>GCC 4.3.6: 20110627</para></listitem>
- <listitem><para>GCC 4.4.0: 20090421</para></listitem>
- <listitem><para>GCC 4.4.1: 20090722</para></listitem>
- <listitem><para>GCC 4.4.2: 20091015</para></listitem>
- <listitem><para>GCC 4.4.3: 20100121</para></listitem>
- <listitem><para>GCC 4.4.4: 20100429</para></listitem>
- <listitem><para>GCC 4.4.5: 20101001</para></listitem>
- <listitem><para>GCC 4.4.6: 20110416</para></listitem>
- <listitem><para>GCC 4.4.7: 20120313</para></listitem>
- <listitem><para>GCC 4.5.0: 20100414</para></listitem>
- <listitem><para>GCC 4.5.1: 20100731</para></listitem>
- <listitem><para>GCC 4.5.2: 20101216</para></listitem>
- <listitem><para>GCC 4.5.3: 20110428</para></listitem>
- <listitem><para>GCC 4.5.4: 20120702</para></listitem>
- <listitem><para>GCC 4.6.0: 20110325</para></listitem>
- <listitem><para>GCC 4.6.1: 20110627</para></listitem>
- <listitem><para>GCC 4.6.2: 20111026</para></listitem>
- <listitem><para>GCC 4.6.3: 20120301</para></listitem>
- <listitem><para>GCC 4.7.0: 20120322</para></listitem>
- <listitem><para>GCC 4.7.1: 20120614</para></listitem>
- <listitem><para>GCC 4.7.2: 20120920</para></listitem>
+ <listitem><para>
+ GCC 4.1.0 and later: the GCC release date, as shown in the
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC
+ Release Timeline</link>
+ </para></listitem>
</itemizedlist>
<para/>
</listitem>
@@ -619,7 +612,7 @@ compatible.
<para>
When the GNU C++ library is being built with symbol versioning
on, you should see the following at configure time for
- libstdc++:
+ libstdc++ (showing either 'gnu' or another of the supported styles):
</para>
<screen>
@@ -629,7 +622,6 @@ compatible.
</screen>
<para>
- or another of the supported styles.
If you don't see this line in the configure output, or if this line
appears but the last word is 'no', then you are out of luck.
</para>
More information about the Gcc-patches
mailing list