[v3] update abi docs

Benjamin Kosnik bkoz@redhat.com
Fri Sep 6 12:52:00 GMT 2002


Marks some of the new versioning info, as well as adds more status on testing.

2002-09-06  Benjamin Kosnik  <bkoz@redhat.com>

	* include/bits/localefwd.h: Tweak formatting.
	* docs/html/abi.txt: Add.

Index: docs/html/abi.txt
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/abi.txt,v
retrieving revision 1.5
diff -c -p -r1.5 abi.txt
*** docs/html/abi.txt	2 Aug 2002 16:04:15 -0000	1.5
--- docs/html/abi.txt	6 Sep 2002 19:50:23 -0000
*************** document exists, why it's incomplete, an
*** 6,12 ****
  
  ===========================
  
! 2002-07-30 Benjamin Kosnik
  
  Description of the libstdc++ ABI.
  
--- 6,12 ----
  
  ===========================
  
! 2002-09-06 Benjamin Kosnik
  
  Description of the libstdc++ ABI.
  
*************** I. What is an ABI? What's covered? What'
*** 131,137 ****
      gcc-3.0.4: 20020220
      gcc-3.1.0: 20020514
      gcc-3.1.1: 20020725
!     gcc-3.2.0: (20020731)
  
  
    - Incremental bumping of a library pre-defined macro,
--- 131,137 ----
      gcc-3.0.4: 20020220
      gcc-3.1.0: 20020514
      gcc-3.1.1: 20020725
!     gcc-3.2.0: 20020814
  
  
    - Incremental bumping of a library pre-defined macro,
*************** I. What is an ABI? What's covered? What'
*** 152,158 ****
      gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")
      gcc-3.1.0: "3.1.0"
      gcc-3.1.1: "3.1.1"
!     gcc-3.2.0: ("3.2.0")
  
  
    - Matching each specific C++ compiler release to a specific set of
--- 152,158 ----
      gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")
      gcc-3.1.0: "3.1.0"
      gcc-3.1.1: "3.1.1"
!     gcc-3.2.0: "3.2"
  
  
    - Matching each specific C++ compiler release to a specific set of
*************** III. Versioning
*** 281,320 ****
  
  IV. Testing ABI changes
  
! Currently, there is no formal testing for changes in the libstdc++
! ABI. It would be in the best interest of GNU C++ users everywhere to
! have such a test, and work to develop this test is ongoing.
  
  There is a formal method for checking the compiler parts of the C++
  ABI, donated by Intel. More information can be obtained
  <a href="http://developer.intel.com/software/products/opensource/">here.</a>
  
! To test the library, the following two ideas have been suggested:
  
  One. 
  (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, 
  one with a new compiler and an old library, and the other with an old
  compiler and a new library, and look for testsuite regressions)
  
  Two.  
! Have the libstdc++ testsuite proactive check the library ABI. Probably
! a couple of items would be covered, although perhaps not all would
! need to be done at once for this to be useful. Compute the list of
! names exported in the shared version of libstdc++ binary. Then, save
! this list of names. Have this list of names re-computed for each new
! binary of the same version. Next, use sizeof, alignof, and offset to
! compute offsets for each structure and type in the standard library,
! saving to another datafile. Then, compute this for new binaries, and
! look for differences.
! 
! An example of a way to compute the list of names exported by the
! shared libstdc++ binary is:
! 
! nm --extern-only --portability libstdc++.so.5.0.0 | awk '{ print $1 $2}'
! 
! The thought is to choose one or both of these approaches, and to use a
! Makefile hook, perhaps 'make check-abi', to add this capability to the
! libstdc++ testsuite.
  
  Perhaps there are other Library ABI checkers. If so, please notify us.
  
--- 281,333 ----
  
  IV. Testing ABI changes
  
! Currently, there are formal tests for changes in the libstdc++ ABI,
! and in addition informal testing procedures. Work to develop these
! tests is ongoing.
  
  There is a formal method for checking the compiler parts of the C++
  ABI, donated by Intel. More information can be obtained
  <a href="http://developer.intel.com/software/products/opensource/">here.</a>
  
! Also, it seems as if some members of the open source community are
! working on C++ ABI testers for the compiler. It is yet unspecified if
! these tools will be freely available, and able to be included in a GNU
! project. Please contact Mark Mitchell (mark@codesoucery.com) for more
! details, and current status.
! 
! 
! To test the library, there are two methods:
  
  One. 
  (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, 
  one with a new compiler and an old library, and the other with an old
  compiler and a new library, and look for testsuite regressions)
  
+ Details on how to set this kind of test up can be found here:
+ http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
+ 
  Two.  
! Use the 'make check-abi' rule in the libstdc++-v3 Makefile. 
! 
! This is a proactive check the library ABI. Currently, exported symbol
! names are checked against a last known good baseline. Currently, this
! baseline is keyed off of 3.2.0 binaries, as this was the last time the
! .so number was incremented. In addition, all exported names are
! demangled, and the exported objects are checked to make sure they are
! the same size as the same object in the baseline.
! 
! In the future, more tests should be added. In particular, vtable
! information, offsets of data members in class objects, and other
! layout information should be checked.
! 
! It should be possible to use sizeof, alignof, and offset to compute
! offsets for each structure and type in the standard library, saving to
! another datafile. Then, compute this for new binaries, and look for
! differences.
! 
! Another approach might be to use the -fdump-class-hierarchy flag to
! get information.
! (See g++/7470 on how this was used to find bugs.)
  
  Perhaps there are other Library ABI checkers. If so, please notify us.
  
*************** V. Issues not directly addressed, and po
*** 327,333 ****
  
    --enable-version-specific-runtime-libs
  
!   - Alexandre Oliva proposal to have extended name attributes, modify ld
   
    - directory-level versioning
  
--- 340,346 ----
  
    --enable-version-specific-runtime-libs
  
!   - Alexandre Olva proposal to have extended name attributes, modify ld
   
    - directory-level versioning
  
Index: include/bits/localefwd.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/localefwd.h,v
retrieving revision 1.29
diff -c -p -r1.29 localefwd.h
*** include/bits/localefwd.h	18 Apr 2002 23:47:46 -0000	1.29
--- include/bits/localefwd.h	6 Sep 2002 19:50:23 -0000
*************** namespace std
*** 387,398 ****
      friend class locale;
      friend class locale::_Impl;
  
!     _Atomic_word _M_references;
  
    protected:
      // Contains data from the underlying "C" library for default "C"
      // or "POSIX" locale.
!     static __c_locale		     _S_c_locale;
      
      explicit 
      facet(size_t __refs = 0) throw();
--- 387,398 ----
      friend class locale;
      friend class locale::_Impl;
  
!     _Atomic_word 			_M_references;
  
    protected:
      // Contains data from the underlying "C" library for default "C"
      // or "POSIX" locale.
!     static __c_locale		     	_S_c_locale;
      
      explicit 
      facet(size_t __refs = 0) throw();



More information about the Gcc-patches mailing list