WonderTrader Ubuntu 22.04依赖编译与CMake避坑

简介：WonderTrader 依赖库面向在 Ubuntu 环境下编译 WonderTrader 的 C++ 开发者与量化交易系统搭建者，针对 GCC 11.4.0 工具链下常见的第三方依赖缺失、头文件路径分散及 CMake 配置易出错等问题，提供可直接复用的依赖集合。压缩包为 tgz 格式，共约 2000 个文件，其中 1856 个 .hpp、144 个 .h，以 C++ 头文件为主，整体约 14.5MB，涵盖 JSON 解析、格式化输出、核心工具等常用组件，目录组织便于按组件查阅和引用，适合离线集成与本地编译。资源说明中给出通过环境变量 MyDependsGcc 指向依赖根目录、并在 CMakeLists.txt 中替换 MyDeps 路径的做法，可减少硬编码路径带来的迁移成本，方便在不同机器、构建目录或容器中快速切换依赖位置。已有 242 人学习，适合需要搭建 WonderTrader 编译环境、排查依赖路径问题、补齐头文件依赖或统一团队编译环境的中高级 C++ 开发者参考。对需要复现实验环境、快速接入 WonderTrader 项目的读者也更具参考价值。

1. 依赖装不全，WonderTrader 的头一关是 boost

上周在一台空白的 Ubuntu 22.04 机器上跑 WonderTrader 的依赖编译，第一次cmake ..直接卡在Could NOT find Boost。补上 boost 之后再跑，这次换成 OpenSSL 找不到。第三次是 zlib，第四次是 curl。这段断断续续的编译体验，干过 C++ 项目的人应该都懂——它不是难，是烦，每停一次你都得回去翻一眼日志，猜下一个缺的是什么。

WonderTrader 这套量化框架的依赖库就是这么个组合：git 把源码拉下来，boost 负责文件系统、日期时间、线程池和 asio 网络这一层，再叠上 OpenSSL、zlib、curl、sqlite3，以及 Python 绑定层用到的 dev 头和 swig。少装一个就编译不过，版本对不上还会在模板展开阶段给你抛一堆看不懂的报错。这篇记录的是我在这台机器上从系统确认、apt 装依赖、git 拉代码、cmake 配置到装完验证的完整路径，适合手里有源码、准备在本机或者服务器上把 WonderTrader 编译起来的开发者，新手照着走能跑通，熟手可以直接看版本对照和参数取舍。

2. 定版本：Ubuntu 20.04/22.04 与 Boost、OpenSSL 的搭配

2.1 先确认你手上是哪个 Ubuntu 和哪个 gcc

Ubuntu 上编译 WonderTrader，系统版本基本决定了你能从 apt 源里拿到的默认 Boost 和 OpenSSL 大版本，这不是玄学，是源里写死的东西。20.04 默认给 Boost 1.71、OpenSSL 1.1.1；22.04 给 Boost 1.74、OpenSSL 3.0；24.04 给 Boost 1.83。这三个组合我都跑过，理论上都编得过，但 1.71 时代的部分组件接口和后面的差异不小，如果源码里用了较新的 asio 写法，低版本 boost 会在编译期直接报no matching function，而不是链接期才暴露。

所以装之前先花三十秒把三件事确认掉：系统是哪个 LTS、g++ 主版本是多少、默认 boost 装没装。

# 系统版本，确认是 20.04 / 22.04 / 24.04 lsb_release -a # 编译器版本，WonderTrader 的 C++ 部分建议 g++ 9 以上 g++ --version gcc --version # 默认 boost 版本和 apt 里可选的版本 dpkg -l | grep -i boost apt-cache policy libboost-dev

lsb_release -a里的Release字段就是后面选依赖清单的依据；g++ --version看主版本号，低于 9 的话建议先升级工具链，C++14/17 的部分特性在 gcc 7 上会有兼容问题；apt-cache policy能直接告诉你源里默认的 boost 版本号，不用猜。如果dpkg -l已经有输出，说明这台机器以前装过 boost，那就要留意后面可能出现的路径冲突，这一点在避坑那章会展开。

2.2 Boost 装 apt 版还是源码版，一张表说清

下面这张表是我自己整理的对照，左边是系统，中间是默认组件版本，右边是我一般会怎么选。它不是绝对答案，但能帮你少查几次文档。

只有在两种情况下我才建议从源码编 Boost：一是源码明确要求某个比你系统更新的版本，二是 apt 的libboost-all-dev里缺了你要的那个 Python 绑定模块名。除此之外，源码编 Boost 的代价是十几分钟编译加上一个容易忘掉的--prefix路径，后面 cmake 找不到库时排查成本翻倍。常见做法是能用 apt 就别源码编，真需要源码编就把--prefix定到一个固定目录，比如/opt/boost，后面 cmake 里显式指过去，不要往/usr/local里塞，避免和系统包混在一起。

2.3 一份可以直接抄的 apt 依赖清单

确认完版本，把下面这条命令整段贴进终端就行。我按功能把它拆成几组，方便你理解每个包是干什么的。如果你只想快速跑通，直接整段执行。

sudo apt update sudo apt install -y \ build-essential cmake git pkg-config \ autoconf automake libtool \ libboost-all-dev \ libssl-dev zlib1g-dev \ libcurl4-openssl-dev libsqlite3-dev \ libpython3-dev python3-dev swig

逐组解释一下：build-essential cmake git pkg-config是编译工具链，cmake 负责生成构建文件，pkg-config 在部分依赖探测时会用到；autoconf automake libtool是给那些要从源码编译的第三方库准备的，现在不装，后面补编时会用到；libboost-all-dev一次性把 boost 的头文件和所有已编译组件装上，这是最省心的做法，代价是占几百 MB 磁盘，但比缺一个补一个强；libssl-dev和zlib1g-dev对应 OpenSSL 和 zlib 的编译头文件，注意libssl-dev和运行时包libssl3是两回事，只装运行时是编不过的；libcurl4-openssl-dev是 curl 的 libcurl 开发包，注意别装成libcurl4-nss-dev，两者会冲突；libsqlite3-dev给本地数据存储用；最后一组libpython3-dev python3-dev swig是 Python 绑定层要的，如果暂时不需要 Python 接口可以省，但建议一次装齐，省得回头补。

提示：装完libboost-all-dev后用dpkg -L libboost-dev | head扫一眼头文件安装位置，正常应在/usr/include/boost，如果不在，说明系统里还有另一份 boost，后面 cmake 要显式指定路径。

3. git 拉取与依赖落地：子模块和编译期依赖

3.1 git clone 一定要带 --recursive

WonderTrader 这类项目通常把核心库拆成主仓库加若干子模块，子模块里放的可能就是某个网络库或序列化库。直接git clone不带--recursive，拉下来的只是主仓库，子模块目录是空的，cmake 阶段会报某个 include 找不到，而你翻遍主仓库都找不到那个头文件——因为它根本不在主仓库里。

# 一次性把主仓库和子模块都拉下来 git clone --recursive <你的 WonderTrader 仓库地址> WonderTrader # 如果已经 clone 过但忘了带 --recursive，进目录后补这两步 cd WonderTrader git submodule update --init --recursive # 检查子模块是否都到位，输出里每个模块前面不应有 '-' 号 git submodule status

--recursive的含义是递归拉取所有层级的子模块，子模块里再嵌套子模块也能一次拉全；git submodule update --init --recursive是补救命令，--init负责把.gitmodules里声明的模块注册进来，--recursive负责递归；git submodule status的输出里，行首是-表示该模块还没初始化，是+表示本地提交和主仓库记录的不一致，两种都要处理后再继续。我一般会在 clone 完先跑一遍 status，确认全是空格开头才往下走，这样可以避免在 cmake 阶段才发现少东西。

3.2 从 apt 补装编译期依赖的顺序

依赖不要一次性全装然后指望一次编过，我习惯按编译报错的顺序补，这样每次补完都知道自己在解决什么。第一轮先装工具链和 boost，第二轮补 OpenSSL、zlib、curl，第三轮再补 Python 相关。下面是分轮执行的命令，你可以一口气跑完，也可以按报错逐轮跑。

# 第一轮：工具链 + boost，解决 CMakeLists 里 find_package(Boost) 失败 sudo apt install -y build-essential cmake git libboost-all-dev # 第二轮：OpenSSL / zlib / curl / sqlite，解决编译期头文件缺失 sudo apt install -y libssl-dev zlib1g-dev libcurl4-openssl-dev libsqlite3-dev # 第三轮：Python 绑定层的开发头文件和 swig sudo apt install -y libpython3-dev python3-dev swig # 装完刷新一下动态库缓存，避免刚装的库 ldd 找不到 sudo ldconfig

ldconfig这一步很多人会漏，它的作用是把新装到/usr/lib/x86_64-linux-gnu下的动态库刷新进系统缓存，如果你装上库之后立刻跑程序报error while loading shared libraries，八成就是没刷新缓存。libpython3-dev里的 Python 小版本号不用写死，apt 会自动选当前系统默认的 Python 3 版本，写死libpython3.10-dev之类的反而在换系统后会失效。

3.3 什么时候才需要源码编 Boost

前面说过能 apt 就别源码编，但有些场景绕不开：源码里用了boost::asio的新接口而系统 Boost 版本太低，或者 Python 绑定那块需要和本机 Python 版本严格对应的libboost_python3xx模块，而 apt 里装的模块名对不上。这时候才走源码编译，流程如下。

# 下载指定版本的 boost 源码包，换成你需要的版本号 cd /tmp wget https://archives.boost.io/release/1.83.0/source/boost_1_83_0.tar.gz tar -xzf boost_1_83_0.tar.gz cd boost_1_83_0 # 只编需要的组件，prefix 定到独立目录，避免污染系统路径 ./bootstrap.sh --prefix=/opt/boost \ --with-libraries=filesystem,system,thread,date_time,chrono,regex # -j 后面跟的是并行编译核数，机器内存小就降到 2 ./b2 -j$(nproc) link=static runtime-link=shared # 安装到 /opt/boost sudo ./b2 install

--with-libraries后面列的是要编译的组件，不写就是全编，全编大概十几分钟，只编列出来的几个组件能压到两三分钟；link=static表示生成静态库，runtime-link=shared表示 C++ 运行时用动态链接，这两个参数的取舍主要看你后面是静态链接进可执行文件还是动态加载，不确定就保持这个组合；--prefix=/opt/boost是安装路径，编完后的头文件在/opt/boost/include，库在/opt/boost/lib，后面 cmake 里要显式指过去。编完之后记得把/opt/boost/lib加进LD_LIBRARY_PATH，或者干脆在 cmake 里做 rpath 设置，不然运行时会找不到刚编的库。

4. CMake 配置：Boost 路径、编译类型和构建参数

4.1 先摸清 cmake 到底去哪找 Boost

find_package(Boost)失败是这套环境最典型的第一枪，但失败原因不止一种：可能是系统里压根没装，可能是装了但 cmake 找的是旧缓存，也可能是装了两份 boost 而 cmake 抓到了错的那份。下手之前先看 cmake 的搜索日志，不要盲猜。

# 让 cmake 打印 Boost 搜索细节，看着它到底找了哪些路径 cmake .. -DBoost_DEBUG=ON # 看看系统里 boost 头文件和库分别在哪 dpkg -L libboost-dev | grep -E 'include/boost$' dpkg -L libboost-filesystem-dev | grep -E 'libboost_filesystem' # 如果用的是源码编的 boost，手动验证那几个目录是否存在 ls /opt/boost/include/boost/version.hpp ls /opt/boost/lib | grep filesystem

-DBoost_DEBUG=ON会把 cmake 搜索 Boost 的每一个候选路径都打出来，哪一步找错了、找的是哪个版本，一眼能看出来；dpkg -L列出某个包安装了哪些文件，比盲目find / -name快得多；源码编的场景下，ls那两行是确认头文件和库文件都在位的最快方式。我一般先在干净的 build 目录里跑一次带Boost_DEBUG的配置，把搜索路径确认清楚，再去改正式参数。

4.2 正式构建的命令和每个参数的含义

路径确认完，下面是我在 wondertrader 上用的正式 cmake 命令。注意build目录一定要干净，否则换了一次 boost 路径后，cmake 缓存里还留着老路径，会出现明明库在却找不到的怪现象。

# 进项目根目录，从干净的 build 目录开始 cd WonderTrader rm -rf build && mkdir -p build && cd build # 生成构建文件，Release 优化、显式指定 Boost 路径、指定 Python 解释器 cmake .. \ -DCMAKE_BUILD_TYPE=Release \ -DBOOST_ROOT=/opt/boost \ -DBoost_NO_SYSTEM_PATHS=ON \ -DCMAKE_INSTALL_PREFIX=/opt/wondertrader \ -DPYTHON_EXECUTABLE=$(which python3) # 并行编译，核数按内存来定 make -j$(nproc) 2>&1 | tee build.log

-DCMAKE_BUILD_TYPE=Release是优化级别，量化框架对性能敏感，别用默认的空值，空值时编译器不开优化，跑回测会慢得让你怀疑人生；-DBOOST_ROOT=/opt/boost只在你源码编过 boost、并且装在非系统路径时才需要，用 apt 装的就删掉这两行，让 cmake 走系统默认搜索；-DBoost_NO_SYSTEM_PATHS=ON让它忽略系统路径只认BOOST_ROOT，这是为了避免系统里同时存在 apt 版和源码版时抓错；-DCMAKE_INSTALL_PREFIX是make install的安装位置，不跑 install 的话这行可省；-DPYTHON_EXECUTABLE指定 Python 解释器，主要是给后面 Python 绑定层用的，不指定时 cmake 可能抓到系统里另一个 Python，编出来的模块 import 就报版本不匹配。

make -j$(nproc)里的$(nproc)是 CPU 核数，-j后面跟多少就用多少核并行编译。这里有个血泪经验：核数不是越多越好，内存不够的时候多核并行会把系统拖进 OOM，编译进程直接被杀，日志里只留下一个Killed，看上去像玄学，实际是内存不够。规则是每核预留 2GB 内存，16G 的机器-j8比较稳，8G 的机器-j2，再少就老老实实单线程。2>&1 | tee build.log是把标准错误也合并到标准输出，同时写进日志文件，编挂了之后可以直接翻日志找第一个error:，不用在滚屏里往回找。

4.3 Python 绑定层的依赖补装

如果你的构建目标里带 Python 模块，cmake 过了之后链接阶段还可能卡住。典型报错是cannot find -lboost_python3xx或者链接上了但 import 时报undefined symbol。原因是 Python 绑定这块对 boost 的 Python 组件版本和 Python 本机版本匹配要求高，apt 里的模块名和源码里Boost::python的探测逻辑经常对不上。

# 确认系统里到底提供了哪个版本的 boost python 模块 ls /usr/lib/x86_64-linux-gnu/ | grep boost_python # 如果源码编过 boost，同时编上 python 组件 cd /tmp/boost_1_83_0 ./bootstrap.sh --prefix=/opt/boost --with-python=$(which python3) \ --with-libraries=python,filesystem,system,thread sudo ./b2 -j4 install # 如果是模块名对不上，常见做法是建个软链接把名字对齐，别直接改名 sudo ln -s /usr/lib/x86_64-linux-gnu/libboost_python3xx.so \ /usr/lib/x86_64-linux-gnu/libboost_python3.so

第一行ls是为了看清系统实际给你的模块名，3xx那两位数字随 Python 小版本变化，这就是对不上的根源；源码编的时候--with-python=$(which python3)把本机 Python 传给 bootstrap，编出来的模块名就会和本机版本严格对应；软链接是应急手段，只在确认模块本身存在、纯粹是名字对不上时用，改名前先用ldd确认目标文件真实存在，否则链接出来的还是断的。这一步做完记得再sudo ldconfig一次，然后重新跑一遍 cmake 和 make。

5. 避坑：五处依赖问题我踩过

5.1 报 boost 头文件缺失，实际只装了一半

现象：fatal error: boost/asio.hpp: No such file or directory，但dpkg -l | grep boost明明有输出。

原因：只装了libboost-dev（基础头文件），没装libboost-all-dev，asio、filesystem 这些分组件头文件在独立包里。

解决：直接补sudo apt install -y libboost-all-dev，装完再编。不要一个个组件去补，一次装全比反复试错省时间。

5.2 链接期 undefined reference，库顺序问题

现象：编译通过，链接阶段一堆undefined reference to boost::system::...。

原因：头文件到了但库没链上，或者-l参数的顺序在依赖它的目标后面。

解决：cmake 里用target_link_libraries把 boost 组件放在依赖它的目标后面，手动 g++ 命令的话，-lboost_system放在源文件之后。链接顺序是从右往左解析，被依赖的放右边。

5.3 CMake 抓到了 /usr/local 下的旧 boost

现象：find_package(Boost)报找到的版本和你dpkg查到的不一致。

原因：这台机器以前源码编过 boost 并装到/usr/local，cmake 的搜索顺序里/usr/local优先于/usr。

解决：要么在 cmake 里显式-DBOOST_ROOT=/usr -DBoost_NO_SYSTEM_PATHS=ON把路径钉死，要么清理/usr/local/include/boost和/usr/local/lib/libboost_*。我一般选前者，不删文件，改配置更安全。

5.4 编译进程被 Killed，不是代码问题是内存

现象：make -j16跑到一半，日志突然结束，只有一行Killed。

原因：并行核数超过内存承受范围，OOM killer 把编译进程干掉了。

解决：先降-j到 2 或者直接不带-j，内存实在紧的机器临时加 swap：

# 临时加 4G swap 应急，重启后失效 sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

5.5 Python 模块导入报 undefined symbol

现象：Python 里import wtpy报undefined symbol: _ZN5boost6python...。

原因：编译链接时的 boost python 库版本和运行环境里的 Python 版本不一致，最常见是编译用 Python 3.10，运行用 3.8。

解决：确认-DPYTHON_EXECUTABLE指的和运行环境是同一个解释器，python3 -c "import sys; print(sys.version)"和cmake里指定的路径对一遍；对不上就清 build 目录重新 cmake。

6. 装完怎么验证：从 ldd 到最小可运行程序

编完不等于跑得起来，这一步是最容易省也最不该省的。我一般按三层来验：静态链接检查、动态库解析、最小运行。

第一层，编译产物存在性和链接依赖。用ldd看可执行文件依赖的动态库是不是全都能解析到，not found的一条都不该有。

# 找到编译出来的主程序，替换成你实际的产物名 file ./bin/WonderTrader # 检查动态库依赖，关注输出里的 not found ldd ./bin/WonderTrader | grep -i "not found" # 如果上面有输出，用 ldconfig 刷新缓存后再看一次 sudo ldconfig ldd ./bin/WonderTrader | grep -i "not found"

file确认产物架构和链接方式，ldd的输出里每行是库名 => 实际路径，出现not found说明运行环境里缺这个库或者路径没进缓存。注意源码编过 boost 的情况，LD_LIBRARY_PATH要包含/opt/boost/lib，或者用patchelf --set-rpath把路径写进可执行文件，后者更稳，不依赖环境变量。

第二层，跑一个最小可执行的入口。很多项目带一个--help或者版本号参数，能打出版本信息说明进程能起来、依赖能加载完。

# 版本或帮助入口，最轻量的一次运行验证 ./bin/WonderTrader --version || ./bin/WonderTrader --help # 看看退出码，0 才算正常 echo $?

这一步能过，说明动态库加载链路是通的。如果卡在这里，回到上一层的ldd输出逐条排查，别急着去看业务代码。

第三层，也是最容易被忽略的一层：用一个最小的配置跑一次加载。WonderTrader 启动要读配置文件，配置文件里涉及的插件和路径如果配错，程序会在初始化阶段退出。试运行的日志要完整看一遍，别只看最后一行。

# 用一个最小配置跑一次，日志同时存文件 ./bin/WonderTrader -c ./config/minimal.yaml > run.log 2>&1 tail -n 50 run.log # 检查日志里有没有加载失败的插件或库 grep -iE "error|fail|not found|undefined" run.log

第三层过了，才算真正把这套依赖装明白了。下面这张表是我验证时常用的对照，出现问题时按列去定位比拍脑袋快。

那次在这台 22.04 上装完，我最大的教训是：别信“编译通过就完事”的错觉。第一次ldd扫出三个not found，全是源码编 boost 之后没刷新缓存导致，编译阶段一切正常，运行阶段直接崩。从那以后我每次装完依赖都强制走一遍“ldd 扫一遍、最小入口跑一遍、日志 grep 一遍”这三步，花不了两分钟，但能把后面几个小时的环境排错挡在前面。这套依赖清单和配置片段我整理在一起了，照着上面的顺序走一遍基本能复现，希望帮到你。

本文还有配套的精品资源，点击获取