升级驱动程序版本
概述
本页面描述了在升级到新版本的C++驱动程序时,您必须对应用程序进行的更改。
升级前,请执行以下操作
确保新的C++驱动程序版本与您的应用程序连接的MongoDB服务器版本以及您的应用程序编译的C++标准版本兼容。有关版本兼容性信息,请参阅C++驱动程序兼容性页面。
解决驱动程序版本与您计划升级的版本之间的任何破坏性更改,请参阅破坏性更改部分。
提示
为确保在升级驱动程序版本时跨MongoDB服务器版本的兼容性,请使用稳定API。
破坏性更改的定义
注意
该C++驱动程序遵循语义版本控制。 驱动程序在任何版本中都可能破坏构建系统或软件包兼容性。补丁版本可能会撤销意外破坏API的更改。
有关更多信息,请参阅API和ABI版本控制。
破坏性更改是指从驱动程序的特定版本开始更改约定或行为。如果不在升级驱动程序之前解决此类更改,则可能导致您的应用程序无法正常工作。
本节中的破坏性更改按引入它们的驱动程序版本进行分类。在升级驱动程序版本时,解决当前版本和升级版本之间的所有破坏性更改。
示例
升级到版本4.0
如果您正在将C++驱动程序从3.x版本升级到4.0版本,请解决列出的3.x版本及更高版本的所有破坏性更改
破坏性更改的类型
C++驱动程序的新版本可能会引入以下类型的破坏性更改
API更改涉及C++驱动程序库的API。这些更改伴随着API主版本的提升。您可能需要编辑项目中C++源代码以解决这些更改。
示例
移除了函数的声明
v1::func()。(定义仍提供以保持ABI兼容性。)移除了内联函数
v_noabi::func()。移除了
v_noabi::func()。将
bsoncxx::foo的重新声明从v1::foo更改为v2::foo。要继续使用旧接口,请将bsoncxx::foo指定为bsoncxx::v1::foo。
ABI 变更涉及 C++ 驱动库的 ABI。这些变更伴随着 ABI 版本号的增加,也可能伴随着 API 主版本号的增加。您可能需要重新构建项目或编辑 C++ 源代码以应对这些变更。
不 支持对
v_noabi命名空间中声明的实体对应的符号的 ABI 稳定性。此类符号的破坏性变更不一定伴随着 ABI 版本号的增加。示例
删除了导出的符号
v_noabi::func()。删除了导出的符号
v1::func()。删除了
v1::type的导出符号。
构建系统 变更涉及 C++ 驱动库的构建系统或打包。这些变更不一定伴随着 API 主版本号或 ABI 版本号的增加。为了应对这些变更,您可能需要修改构建系统配置或更新项目包或依赖管理设置。您还可能需要修改或重新构建 C++ 源代码。
示例
删除了配置变量
ENABLE_FOO。将配置变量
ENABLE_BAR的默认值从OFF更改为ON。取消支持平台 A、编译器 B 或架构 C。
破坏性变更
以下各节描述了每个驱动版本发布引入的破坏性变更。
版本 4.0
4.0版本构建系统重大更改
4.0版本驱动程序对构建系统引入了以下重大更改
不再支持Boost和MNMLSTC/core外部polyfill库。您不能再设置以下配置选项
ENABLE_BSONCXX_POLY_USE_IMPLS。此选项默认设置为ON。BSONCXX_POLY_USE_MNMLSTC.BSONCXX_POLY_USE_SYSTEM_MNMLSTC.BSONCXX_POLY_USE_BOOST.
不再支持
MONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX配置选项。现在默认尊重CMake的CMAKE_INSTALL_PREFIX行为。默认将
ENABLE_TESTS配置选项设置为OFF。要重新启用构建测试目标,必须将ENABLE_TESTS设置为ON。要包括测试目标在“all”目标中,还必须将BUILD_TESTING选项设置为ON。
4.0版本API重大更改
4.0版本驱动程序对API引入了以下重大更改
不再支持将
bsoncxx::stdx::string_view和bsoncxx::stdx::optional<T>配置为Boost或MNMLSTC/core库等价物的别名。有关上下文,请参阅构建系统重大更改部分。删除以下头文件
<bsoncxx/stdx/make_unique.hpp><bsoncxx/types/value.hpp><bsoncxx/util/functor.hpp><mongocxx/options/create_collection.hpp>
删除以下过时的
utf8类型和函数,这些函数有等效的string类型从
bsoncxx::v_noabi::type类中删除k_utf8。相反,使用k_string。从
bsoncxx::v_noabi::types类中移除b_utf8。相反,使用b_string。从
bsoncxx::v_noabi::document::element、bsoncxx::v_noabi::array::element和bsoncxx::v_noabi::types::bson_value::view类中移除get_utf8()。相反,使用get_string()。从
bsoncxx::v_noabi::exception::error_code类中移除k_cannot_append_utf8。相反,使用k_cannot_append_string。从
bsoncxx::v_noabi::exception::error_code类中移除k_need_element_type_k_utf8。相反,使用k_need_element_type_k_string。
移除
mongocxx::stdx命名空间。请在您的代码中替换以下类型mongocxx::stdx::optional<T>。相反,使用bsoncxx::stdx::optional<T>。mongocxx::stdx::string_view。相反,使用bsoncxx::stdx::string_view。
移除以下未记录的
using指令和声明从
<bsoncxx/builder/list.hpp>头文件中移除bsoncxx::builder::types。相反,使用<bsoncxx/types.hpp>中的bsoncxx::types。从
<bsoncxx/builder/stream/helpers.hpp>头文件中移除bsoncxx::builder::stream::concatenate。相反,使用<bsoncxx/builder/concatenate.hpp>中的bsoncxx::builder::concatenate。从
<mongocxx/events/topology_description.hpp>头文件中移除mongocxx::events::read_preference。相反,使用<mongocxx/read_preference.hpp>中的mongocxx::read_preference。
第 4.0 版本的 ABI 破坏性更改
第 4.0 版本驱动程序对 ABI 引入了以下破坏性更改
第 3.11 版本
版本3.11中构建系统的重大变更
版本3.11驱动程序对构建系统引入以下重大变更
取消对MongoDB Server v3.6的支持。
需要MongoDB C驱动程序v1.28.0或更高版本。
版本3.11中的ABI重大变更
版本3.11驱动程序对ABI引入以下重大变更
在bsoncxx ABI中删除以下私有成员函数的导出
bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*, uint32_t, uint32_t, uint32_t)bsoncxx::v_noabi::types::bson_value::view::_init(void*)bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*, uint32_t, uint32_t, uint32_t)bsoncxx::v_noabi::types::bson_value::view::view(void*)
在mongocxx ABI中删除以下私有成员函数的导出
mongocxx::v_noabi::options::change_stream::as_bson()mongocxx::v_noabi::options::aggregate::append( bsoncxx::v_noabi::builder::basic::document&)mongocxx::v_noabi::options::index::storage_options()
使用MSVC编译时,所有导出的函数符号均声明为
__cdecl。如果您在构建项目时使用替代默认调用约定,则这是一个破坏ABI的变更。
版本 3.10
版本 3.10 中构建系统的破坏性变更
版本 3.10 的驱动程序对构建系统引入了以下破坏性变更
弃用了对调用
find_package(libbsoncxx)和find_package(libmongocxx)的支持。请使用find_package(bsoncxx)和find_package(mongocxx)代替。弃用了由旧版 CMake 软件包配置文件提供的
LIBBSONCXX_*和LIBMONGOCXX_*CMake 变量。请使用mongo::bsoncxx_*和mongo::mongocxx_*CMake 目标代替。删除了
BSONCXX_POLY_USE_STD_EXPERIMENTALCMake 选项,并弃用了选择实验性 C++ 标准库作为填充选项的支持。
版本 3.9
3.9 版本构建系统破坏性更改
3.9 驱动引入以下破坏性更改
从 CMake 项目构建树中删除了对导出目标的支持
放弃了对 macOS 10.14、macOS 10.15 和 Ubuntu 14.04 的支持
需要 MongoDB C 驱动程序 v1.25.0 或更高版本
需要 CMake v3.15 或更高版本以支持
FetchContent模块
版本 3.8 及更早版本
对于 3.8 版本及更早的驱动程序版本,请参阅每个版本的发布说明和相关 JIRA 工单,详情请访问 GitHub.