C++符号名与libtorrent库不一致会导致链接失败吗？如何解决？

问题场景 #

测试代码 #

#include <libtorrent/add_torrent_params.hpp>
#include <libtorrent/magnet_uri.hpp>

int main(int argc, char const* argv[])
{
    lt::add_torrent_params atp = lt::parse_magnet_uri(argv[1]);
}

编译命令与错误 #

编译命令：

cl /EHsc /Fefoo.exe /I<snip>\vcpkg\installed\x86-windows\include main.cpp torrent-rasterbar.lib /link /LIBPATH:<snip>\vcpkg\installed\x86-windows\lib

链接阶段报错：

Microsoft (R) C/C++ Optimizing Compiler Version 19.34.31937 for x86
Copyright (C) Microsoft Corporation.  All rights reserved.

main.cpp
Microsoft (R) Incremental Linker Version 14.34.31937.0
Copyright (C) Microsoft Corporation.  All rights reserved.

/out:foo.exe
/LIBPATH:C:\Users\rages\code\vcpkg\installed\x86-windows\lib
main.obj
torrent-rasterbar.lib
main.obj : error LNK2019: unresolved external symbol "public: __thiscall libtorrent::add_torrent_params::~add_torrent_params(void)" (??1add_torrent_params@libtorrent@@QAE@XZ) referenced in function _main
main.obj : error LNK2019: unresolved external symbol "struct libtorrent::add_torrent_params __cdecl libtorrent::parse_magnet_uri(class boost::basic_string_view<char,struct std::char_traits<char> >)" (?parse_magnet_uri@libtorrent@@YA?AUadd_torrent_params@1@V?$basic_string_view@DU?$char_traits@D@std@@@boost@@@Z) referenced in function _main
foo.exe : fatal error LNK1120: 2 unresolved externals

符号排查结果 #

使用dumpbin /exports查看torrent-rasterbar.lib中的符号，发现目标符号位于libtorrent::v2子命名空间：

??1add_torrent_params@v2@libtorrent@@QAE@XZ (public: __thiscall libtorrent::v2::add_torrent_params::~add_torrent_params(void))

而代码中引用的是libtorrent顶层命名空间的符号，两者不匹配导致链接失败。

解决方法 #

• 直接修改代码使用v2命名空间
  可以将代码中的lt::替换为lt::v2::，或者添加命名空间别名简化代码：

  #include <libtorrent/add_torrent_params.hpp>
  #include <libtorrent/magnet_uri.hpp>
  
  namespace lt = libtorrent::v2;
  
  int main(int argc, char const* argv[])
  {
      lt::add_torrent_params atp = lt::parse_magnet_uri(argv[1]);
  }
  

• 编译时定义宏自动映射命名空间
  libtorrent提供了LIBTORRENT_USE_V2_NAMESPACE宏，定义后顶层命名空间的符号会自动指向v2子命名空间。修改编译命令，添加该宏定义参数：

  cl /EHsc /DLIBTORRENT_USE_V2_NAMESPACE /Fefoo.exe /I<snip>\vcpkg\installed\x86-windows\include main.cpp torrent-rasterbar.lib /link /LIBPATH:<snip>\vcpkg\installed\x86-windows\lib
  

  此方法无需修改代码即可实现符号匹配。

• 确认头文件与库版本一致
  检查vcpkg安装的libtorrent库版本是否和头文件版本匹配。若头文件是旧版本（未引入v2命名空间）但库是新版本，也会出现该问题。可重新安装对应版本的库：

  vcpkg install libtorrent-rasterbar:x86-windows
  

内容的提问来源于stack exchange，提问作者Ragesh