Add BOOST_CLASS_TEMPLATE_VERSION for versioning class templates

`BOOST_CLASS_VERSION` writes a full specialization of the version trait,
so it can only version a concrete class. A class template needs a
partial specialization, which users previously had to write by hand and
which neither the tutorial nor version.hpp explained.

`BOOST_CLASS_TEMPLATE_VERSION` writes that partial specialization.

Closes issue #179.

doc/traits.html

@@ -92,6 +92,21 @@ so that instead of the above, we could write:
 BOOST_CLASS_VERSION(my_class, 2)
 </code></pre>
 which expands to the code above.
+<p>
+<code style="white-space: normal">BOOST_CLASS_VERSION</code> writes a full
+specialization, so it applies to a concrete class.  To assign a version to a
+class <i>template</i> a partial specialization is needed instead, which
+<code style="white-space: normal">BOOST_CLASS_TEMPLATE_VERSION</code>
+provides.  The template parameter list and the specialized type are each
+passed parenthesized, as they normally contain commas:
+<pre><code>
+BOOST_CLASS_TEMPLATE_VERSION((class T, class U), (my_class&lt;T, U&gt;), 2)
+</code></pre>
+This assigns version 2 to every instantiation of
+<code style="white-space: normal">my_class</code>.  Non-type template
+parameters are written the same way, for example
+<code style="white-space: normal">(class T, std::size_t N)</code> paired with
+<code style="white-space: normal">(my_class&lt;T, N&gt;)</code>.
 
 <h3><a name="level">Implementation Level</a></h3>
 In the same manner as the above, the "level" of implementation of serialization is

include/boost/serialization/optional.hpp

@@ -1,6 +1,7 @@
 /////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
 
 // (C) Copyright 2002-4 Pavel Vozenilek .
+// Copyright 2026 Gennaro Prota.
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
@@ -21,13 +22,16 @@
 #endif
 
 #include <boost/move/utility_core.hpp>
+#include <boost/core/addressof.hpp>
+#include <boost/utility/enable_if.hpp>
 #include <boost/serialization/item_version_type.hpp>
 #include <boost/serialization/library_version_type.hpp>
 #include <boost/serialization/version.hpp>
 #include <boost/serialization/split_free.hpp>
 #include <boost/serialization/nvp.hpp>
-#include <boost/type_traits/is_pointer.hpp>
+#include <boost/serialization/serialization.hpp>
 #include <boost/serialization/detail/is_default_constructible.hpp>
+#include <boost/serialization/detail/stack_constructor.hpp>
 
 // function specializations must be defined in the appropriate
 // namespace - boost::serialization
@@ -35,27 +39,91 @@ namespace boost {
 namespace serialization {
 namespace detail {
 
+// The value of an optional<T> is serialized like a single element of an
+// STL container: when T is default constructible we serialize it in place,
+// otherwise we route construction through save/load_construct_data so that
+// types without a default constructor can be reconstructed on load.  The
+// default-constructible path is left untouched so that archives written by
+// earlier versions of the library keep the same layout.
+
+// save the value: T is default constructible
+template<class Archive, class OT>
+typename boost::enable_if<
+    typename detail::is_default_constructible<typename OT::value_type>,
+    void
+>::type
+save_value(Archive & ar, const OT & ot){
+    ar << boost::serialization::make_nvp("value", *ot);
+}
+
+// save the value: T is not default constructible
+template<class Archive, class OT>
+typename boost::disable_if<
+    typename detail::is_default_constructible<typename OT::value_type>,
+    void
+>::type
+save_value(Archive & ar, const OT & ot){
+    typedef typename OT::value_type value_type;
+    const value_type & v = *ot;
+    const boost::serialization::item_version_type item_version(
+        boost::serialization::version<value_type>::value
+    );
+    ar << BOOST_SERIALIZATION_NVP(item_version);
+    boost::serialization::save_construct_data_adl(
+        ar,
+        boost::addressof(v),
+        item_version
+    );
+    ar << boost::serialization::make_nvp("value", v);
+}
+
+// load the value: T is default constructible
+template<class Archive, class OT>
+typename boost::enable_if<
+    typename detail::is_default_constructible<typename OT::value_type>,
+    void
+>::type
+load_value(Archive & ar, OT & ot, const unsigned int version){
+    if(0 == version){
+        boost::serialization::item_version_type item_version(0);
+        boost::serialization::library_version_type library_version(
+            ar.get_library_version()
+        );
+        if(boost::serialization::library_version_type(3) < library_version){
+            ar >> BOOST_SERIALIZATION_NVP(item_version);
+        }
+    }
+    typename OT::value_type t;
+    ar >> boost::serialization::make_nvp("value", t);
+    ot = boost::move(t);
+}
+
+// load the value: T is not default constructible
+template<class Archive, class OT>
+typename boost::disable_if<
+    typename detail::is_default_constructible<typename OT::value_type>,
+    void
+>::type
+load_value(Archive & ar, OT & ot, const unsigned int /* version */){
+    typedef typename OT::value_type value_type;
+    boost::serialization::item_version_type item_version(0);
+    ar >> BOOST_SERIALIZATION_NVP(item_version);
+    detail::stack_construct<Archive, value_type> aux(ar, item_version);
+    ar >> boost::serialization::make_nvp("value", aux.reference());
+    ot = boost::move(aux.reference());
+    ar.reset_object_address(boost::addressof(*ot), aux.address());
+}
+
 // OT is of the form optional<T>
 template<class Archive, class OT>
 void save_impl(
     Archive & ar,
     const OT & ot
 ){
-    // It is an inherent limitation to the serialization of optional.hpp
-    // that the underlying type must be either a pointer or must have a
-    // default constructor.  It's possible that this could change sometime
-    // in the future, but for now, one will have to work around it.  This can
-    // be done by serialization the optional<T> as optional<T *>
-    #ifndef BOOST_NO_CXX11_HDR_TYPE_TRAITS
-        BOOST_STATIC_ASSERT(
-            boost::serialization::detail::is_default_constructible<typename OT::value_type>::value
-            || boost::is_pointer<typename OT::value_type>::value
-        );
-    #endif
     const bool tflag(ot);
     ar << boost::serialization::make_nvp("initialized", tflag);
     if (tflag){
-        ar << boost::serialization::make_nvp("value", *ot);
+        save_value(ar, ot);
     }
 }
 
@@ -72,19 +140,7 @@ void load_impl(
         ot.reset();
         return;
     }
-
-    if(0 == version){
-        boost::serialization::item_version_type item_version(0);
-        boost::serialization::library_version_type library_version(
-            ar.get_library_version()
-        );
-        if(boost::serialization::library_version_type(3) < library_version){
-            ar >> BOOST_SERIALIZATION_NVP(item_version);
-        }
-    }
-    typename OT::value_type t;
-    ar >> boost::serialization::make_nvp("value",t);
-    ot = boost::move(t);
+    load_value(ar, ot, version);
 }
 
 } // detail

include/boost/serialization/version.hpp

@@ -72,6 +72,7 @@ const int version<T>::value;
 
 #include <boost/mpl/less.hpp>
 #include <boost/mpl/comparison.hpp>
+#include <boost/preprocessor/punctuation/remove_parens.hpp>
 
 // specify the current version number for the class
 // version numbers limited to 8 bits !!!
@@ -102,4 +103,32 @@ struct version<T >                                                     \
 }                                                                      \
 }
 
+// Specify the current version number for a class template.  Unlike
+// BOOST_CLASS_VERSION, which writes a full specialization, this writes a
+// partial one, so it works for a template rather than a concrete class.
+// The template parameter list and the specialized type are each passed
+// parenthesized (they usually contain commas):
+//
+//     BOOST_CLASS_TEMPLATE_VERSION((class T, class U), (my_class<T, U>), 2)
+//
+// version numbers limited to 8 bits !!!
+#define BOOST_CLASS_TEMPLATE_VERSION(TEMPLATE_PARAMETERS, TYPE, N)     \
+namespace boost {                                                      \
+namespace serialization {                                              \
+template< BOOST_PP_REMOVE_PARENS(TEMPLATE_PARAMETERS) >                \
+struct version< BOOST_PP_REMOVE_PARENS(TYPE) >                         \
+{                                                                      \
+    typedef mpl::int_<N> type;                                         \
+    typedef mpl::integral_c_tag tag;                                   \
+    BOOST_STATIC_CONSTANT(int, value = version::type::value);          \
+    BOOST_MPL_ASSERT((                                                 \
+        boost::mpl::less<                                              \
+            boost::mpl::int_<N>,                                       \
+            boost::mpl::int_<256>                                      \
+        >                                                              \
+    ));                                                                \
+};                                                                     \
+}                                                                      \
+}
+
 #endif // BOOST_SERIALIZATION_VERSION_HPP

test/Jamfile.v2

@@ -64,6 +64,7 @@ test-suite "serialization" :
      [ test-bsl-run_files test_binary ]
      [ test-bsl-run_files test_class_info_save ]
      [ test-bsl-run_files test_class_info_load ]
+     [ test-bsl-run_files test_class_template_version ]
      [ test-bsl-run_files test_bitset ]
      [ test-bsl-run_files test_complex ]
      [ test-bsl-run_files test_contained_class : A ]
@@ -146,6 +147,7 @@ if ! $(BOOST_ARCHIVE_LIST) {
         # we suppress tests of our dlls when using static libraries
 
         [ test-bsl-run test_dll_simple   : : dll_a :  <link>static:<build>no ]
+        [ test-bsl-run test_dll_base_pointer : : dll_polymorphic_base dll_polymorphic_derived2 : <link>static:<build>no ]
         # [ test-bsl-run test_dll_plugin : : dll_derived2 : <link>static:<build>no <target-os>linux:<linkflags>-ldl ]
 
         [ test-bsl-run test_private_ctor ]

test/test_class_template_version.cpp

@@ -0,0 +1,102 @@
+/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
+// test_class_template_version.cpp
+
+// Copyright 2026 Gennaro Prota
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt or copy at
+// https://www.boost.org/LICENSE_1_0.txt)
+
+// Tests BOOST_CLASS_TEMPLATE_VERSION, which assigns a serialization version
+// to a class template through a partial specialization of the version trait.
+
+#include <cstddef>
+#include <cstdio>
+#include <fstream>
+
+#include <boost/config.hpp>
+
+#if defined(BOOST_NO_STDC_NAMESPACE)
+namespace std{
+    using ::remove;
+}
+#endif
+
+#include <boost/static_assert.hpp>
+#include <boost/serialization/nvp.hpp>
+#include <boost/serialization/version.hpp>
+#include "test_tools.hpp"
+
+// a class template with two type parameters; serialize records the version
+// it is given on load so the round trip can be checked
+template<class T, class U>
+struct pair_holder {
+    T first;
+    U second;
+    unsigned int loaded_version;
+    pair_holder() : first(), second(), loaded_version(0) {}
+    pair_holder(T f, U s) : first(f), second(s), loaded_version(0) {}
+    template<class Archive>
+    void serialize(Archive & ar, const unsigned int version){
+        loaded_version = version;
+        ar & boost::serialization::make_nvp("first", first);
+        ar & boost::serialization::make_nvp("second", second);
+    }
+};
+
+BOOST_CLASS_TEMPLATE_VERSION((class T, class U), (pair_holder<T, U>), 5)
+
+// a class template mixing a type parameter and a non-type parameter
+template<class T, std::size_t N>
+struct sized_holder {
+    T value;
+};
+
+BOOST_CLASS_TEMPLATE_VERSION((class T, std::size_t N), (sized_holder<T, N>), 3)
+
+// a template we do not version, to confirm the default is still 0
+template<class T>
+struct unversioned {
+    T value;
+};
+
+int test_main(int /* argc */, char * /* argv */[]){
+    // the macro must set the compile time version for every instantiation of
+    // the template, regardless of the actual arguments
+    BOOST_STATIC_ASSERT(
+        (boost::serialization::version<pair_holder<int, double> >::value == 5)
+    );
+    BOOST_STATIC_ASSERT(
+        (boost::serialization::version<pair_holder<char, long> >::value == 5)
+    );
+    // works for a non-type parameter too
+    BOOST_STATIC_ASSERT(
+        (boost::serialization::version<sized_holder<int, 4> >::value == 3)
+    );
+    // an unversioned template still defaults to 0
+    BOOST_STATIC_ASSERT(
+        (boost::serialization::version<unversioned<int> >::value == 0)
+    );
+
+    const char * testfile = boost::archive::tmpnam(NULL);
+    BOOST_REQUIRE(NULL != testfile);
+
+    const pair_holder<int, double> saved(7, 2.5);
+    {
+        test_ostream os(testfile, TEST_STREAM_FLAGS);
+        test_oarchive oa(os, TEST_ARCHIVE_FLAGS);
+        oa << boost::serialization::make_nvp("ph", saved);
+    }
+    pair_holder<int, double> loaded;
+    {
+        test_istream is(testfile, TEST_STREAM_FLAGS);
+        test_iarchive ia(is, TEST_ARCHIVE_FLAGS);
+        ia >> boost::serialization::make_nvp("ph", loaded);
+    }
+    BOOST_CHECK(loaded.first == saved.first);
+    BOOST_CHECK(loaded.second == saved.second);
+    // the version set by the macro must be delivered to serialize on load
+    BOOST_CHECK(loaded.loaded_version == 5);
+
+    std::remove(testfile);
+    return EXIT_SUCCESS;
+}

test/test_dll_base_pointer.cpp

@@ -0,0 +1,75 @@
+/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
+// test_dll_base_pointer.cpp
+
+// Copyright 2026 Gennaro Prota
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt or copy at
+// https://www.boost.org/LICENSE_1_0.txt)
+
+// Regression test for issue #117.  A derived class defined in a shared
+// library is serialized and deserialized through a pointer to its abstract
+// base, from an executable built with hidden symbol visibility.
+// Historically this failed on GCC/ELF: the per type serializer singletons
+// were duplicated across the shared library boundary, so the reader could not
+// map the class id back to the derived type.  The round trip must recover an
+// object of the derived type.
+
+#include <fstream>
+#include <cstdio>
+#include <typeinfo>
+
+#include <boost/config.hpp>
+
+#include "test_tools.hpp"
+
+#ifndef BOOST_NO_CXX11_SMART_PTR
+
+#include <boost/archive/polymorphic_binary_oarchive.hpp>
+#include <boost/archive/polymorphic_binary_iarchive.hpp>
+#include <boost/archive/tmpdir.hpp>
+
+#include <boost/smart_ptr/make_unique.hpp>
+#include <boost/serialization/unique_ptr.hpp>
+#include <boost/serialization/nvp.hpp>
+
+// polymorphic_derived2 (and its base, polymorphic_base) live in the shared
+// library this test links against
+#define POLYMORPHIC_DERIVED2_IMPORT
+#include "polymorphic_derived2.hpp"
+
+int test_main(int /* argc */, char * /* argv */ []){
+    const char * testfile = boost::archive::tmpnam(NULL);
+    BOOST_REQUIRE(NULL != testfile);
+
+    std::unique_ptr<polymorphic_base> saved =
+        boost::make_unique<polymorphic_derived2>();
+    {
+        std::ofstream os(testfile, std::ios::binary);
+        boost::archive::polymorphic_binary_oarchive oa(os);
+        boost::archive::polymorphic_oarchive & poa = oa;
+        poa << boost::serialization::make_nvp("ptr", saved);
+    }
+
+    std::unique_ptr<polymorphic_base> loaded;
+    {
+        std::ifstream is(testfile, std::ios::binary);
+        boost::archive::polymorphic_binary_iarchive ia(is);
+        boost::archive::polymorphic_iarchive & pia = ia;
+        pia >> boost::serialization::make_nvp("ptr", loaded);
+    }
+
+    BOOST_CHECK(0 != loaded.get());
+    // the object recovered through the base pointer must be the derived type
+    BOOST_CHECK(0 != dynamic_cast<polymorphic_derived2 *>(loaded.get()));
+
+    std::remove(testfile);
+    return EXIT_SUCCESS;
+}
+
+#else
+
+int test_main(int /* argc */, char * /* argv */ []){
+    return EXIT_SUCCESS;
+}
+
+#endif // BOOST_NO_CXX11_SMART_PTR

test/test_optional.cpp

@@ -146,6 +146,77 @@ int test_move_only(){
 }
 #endif // move-only support available
 
+// A type without a default constructor.  It is reconstructed on load through
+// save_construct_data / load_construct_data, which is exactly what an
+// optional<ND> now relies on (see issue #121).  m_i is the constructor
+// argument, m_x is ordinary serialized state.
+struct ND {
+    int m_i;
+    int m_x;
+    ND(int i, int x) : m_i(i), m_x(x) {}
+    explicit ND(int i) : m_i(i), m_x(0) {}
+    template<class Archive>
+    void serialize(Archive & ar, const unsigned int /* version */){
+        ar & boost::serialization::make_nvp("x", m_x);
+    }
+    bool operator==(const ND & rhs) const {
+        return m_i == rhs.m_i && m_x == rhs.m_x;
+    }
+};
+
+namespace boost {
+namespace serialization {
+
+template<class Archive>
+void save_construct_data(
+    Archive & ar, const ND * p, const unsigned int /* version */
+){
+    ar << boost::serialization::make_nvp("i", p->m_i);
+}
+
+template<class Archive>
+void load_construct_data(
+    Archive & ar, ND * p, const unsigned int /* version */
+){
+    int i;
+    ar >> boost::serialization::make_nvp("i", i);
+    ::new(p) ND(i);
+}
+
+} // serialization
+} // boost
+
+template<template<class> class Optional>
+int test_non_default_ctor(){
+    const char * testfile = boost::archive::tmpnam(NULL);
+    BOOST_REQUIRE(NULL != testfile);
+
+    const Optional<ND> o_empty;
+    const Optional<ND> o_value(ND(7, 42));
+    {
+        test_ostream os(testfile, TEST_STREAM_FLAGS);
+        test_oarchive oa(os, TEST_ARCHIVE_FLAGS);
+        oa << boost::serialization::make_nvp("o_empty", o_empty);
+        oa << boost::serialization::make_nvp("o_value", o_value);
+    }
+    // start each target in the opposite state, so load must both reset and
+    // reconstruct
+    Optional<ND> o_empty_a(ND(1, 1));
+    Optional<ND> o_value_a;
+    {
+        test_istream is(testfile, TEST_STREAM_FLAGS);
+        test_iarchive ia(is, TEST_ARCHIVE_FLAGS);
+        ia >> boost::serialization::make_nvp("o_empty", o_empty_a);
+        ia >> boost::serialization::make_nvp("o_value", o_value_a);
+    }
+    BOOST_CHECK(! o_empty_a);
+    BOOST_CHECK(static_cast<bool>(o_value_a));
+    BOOST_CHECK(o_value_a && *o_value == *o_value_a);
+
+    std::remove(testfile);
+    return EXIT_SUCCESS;
+}
+
 #include <boost/serialization/optional.hpp>
 #ifndef BOOST_NO_CXX17_HDR_OPTIONAL
 #include <optional>
@@ -162,5 +233,9 @@ int test_main( int /* argc */, char* /* argv */[] ){
     test_move_only<std::optional>();
     #endif
     #endif
+    test_non_default_ctor<boost::optional>();
+    #ifndef BOOST_NO_CXX17_HDR_OPTIONAL
+    test_non_default_ctor<std::optional>();
+    #endif
     return EXIT_SUCCESS;
 }