简介面向Linux平台源码编译AFSim2.9.0仿真工具集的实操指南由作者依据自身完整编译经验整理适合需要在Ubuntu等环境下搭建AFSim的仿真开发与研究人员参考。文档为单个PDF文件体积约694KB核心内容涵盖编译环境要求Ubuntu 22.04.4 LTS、gcc/g4.8.5、CMake 3.22.1与Qt5.15、推荐编译目录及资源说明、库环境变量配置、依赖安装、CMake配置编译步骤以及编译后运行测试与排错建议。文档还系统性介绍了源码目录、官方案例、第三方库、网页版手册、辅助工具和培训资料等资源的用途便于读者快速弄清仿真工具集整体结构硬件配置建议与常见注意事项也有明确交代。已有2547人学习下载尤其适合初次尝试AFSim源码编译、希望避免踩坑的开发者也可作为参考手册随时查阅。1. Linux 平台下编译 AFSim2.9.0源码、依赖与编译流程的一次完整走通不少从业者拿到 AFSim 2.9.0 的 Linux 源码包后第一反应是“我都按 Readme 配了怎么还是编译不过”。这个被广泛用于仿真开发与研究的工具集编译本身并不复杂但坑全藏在环境变量、第三方库版本和 CMake 缓存这三处。我基于自己在 Ubuntu 22.04.4 LTS 上的一次完整复现整理了这份 Linux 编译指南的落地笔记从资源结构讲到最后的运行验证把每一步背后为什么这么干也一并说清楚。如果你准备在 Linux 下从源码构建 AFSim并想避开权限、路径、依赖顺序这几类经典翻车点这份内容值得对着敲一遍。2. 编译前的三件事目录结构、环境版本与 LD_LIBRARY_PATH2.1 资源里到底有什么六个目录的边界AFSim 源码包不是单一工程而是按“源码、案例、依赖、工具、培训”拆开的整套生态。我的建议是拿到压缩包后先不要急着编译把这六个目录的边界搞清楚后面定位问题会省很多时间。我编译时目录结构如下目录内容在编译中的作用afsim/仿真工具集主源码被 CMake 读取的顶层源码树demos/官方示例与仿真案例验证安装结果的素材dependencies/3rd_party/编译所需第三方库提供 tiff、sqlite、sdl、openssl 等预编译库dependencies/resources/编译所需 vtk、数据资源等CMake 运行时读取的资源路径dependencies/tools.rar编译工具包解压后含 cmake、脚本等dependencies/gcc-g.rarC 编译器环境资源包提供 gcc-4.8.5 / g-4.8.5tools/辅助工具含 python 等部分后处理脚本依赖training/开发者与用户培训资料文档参考注意 dependencies 目录下同时存在 3rd_party 和 resources前者解决“链接库从哪来”后者解决“数据文件从哪来”。很多人只配了前者的路径结果 CMake 配置时报找不到 vtk 数据就是忽略了 resources 在编译期的参与。2.2 环境选型为什么是 Ubuntu 22.04、gcc-4.8.5 和 CMake 3.22这份文档推荐的环境组合是操作系统 Ubuntu 22.04.4 LTS构建工具 cmake-3.22.1-linux-x86_64 加 cmake-qt-gui对应 Qt 5.15编译器 gcc-4.8.5 和 g-4.8.5硬件建议 16G 内存上下。先说一个最容易困惑的点Ubuntu 22.04 系统自带的 gcc 是 11.x文档要求 gcc-4.8.5。我按文档走的时候是先解压 gcc-g.rar再通过 update-alternatives 把系统默认的 gcc/g 切到 4.8.5同时把 4.8.5 的路径放到 PATH 最前面否则 CMake 探测编译器时会抓到 11.x导致后续链接阶段出现 ABI 不兼容问题。cmake 版本同理Ubuntu 22.04 自带的是 cmake 3.22.1正好符合要求。如果你的系统是 20.04自带 cmake 3.16建议直接使用文档给的 cmake-3.22.1-linux-x86_64 二进制包不要用 apt 自带的旧版因为旧版对 osgEarth 等第三方库的 find_package 配置支持不完全。2.3 目录约定的意义路径不一致是后期最大的风险源文档要求编译目录固定为/home/sma/AFSIMSrc/根目录下分 afsim、dependencies、tools、training 等子目录。这里不是随意规定而是 AFSim 的构建脚本中存在大量相对路径引用。我测试过如果换到别的路径最典型的报错是 CMake 阶段找不到dependencies/resources/下的 vtk 数据或者 make 阶段出现 “No such file or directory” 指向一个看起来不该存在的路径。提示如果不想使用/home/sma可以创建软链接例如把实际目录软链到/home/sma/AFSIMSrc这样既不破坏约定又保留了自定义空间。3. 配置环境变量与安装编译环境从 bashrc 到 myenv_temp.sh3.1 AFSIM_HOME 与 AFSIM_3RDPARTY_PATH 的写法编译前第一步是配置库环境变量。文档要求在/root/.bashrc末尾追加以下内容export AFSIM_HOME/home/sma/AFSIMSrc/afsim export AFSIM_3RDPARTY_PATH/home/sma/AFSIMSrc/dependencies/3rd_party这两个变量是整个编译期的“根锚点”。AFSIM_HOME 指向源码根目录CMake 用它定位顶层 CMakeLists.txtAFSIM_3RDPARTY_PATH 指向预编译第三方库的根目录后续 LD_LIBRARY_PATH 里所有库路径都以它为前缀展开。如果这两个变量写错后面配置 CMake 时会出现 “AFSIM_HOME not found” 或 3rd_party 内库路径失效的连锁报错。设置完记得执行source ~/.bashrc我一般会顺手用echo $AFSIM_HOME验证一下变量是否生效避免在子 shell 里调试半天发现是环境变量没刷新的低级问题。3.2 LD_LIBRARY_PATH 里每一段是干什么的文档给了一长串路径追加到 LD_LIBRARY_PATHexport LD_LIBRARY_PATH${AFSIM_3RDPARTY_PATH}/tiff-4.4.0-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/sqlite-3.32.3-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/sdl-2.0.16-x64-lnx/lib64:${AFSIM_3RDPARTY_PATH}/tinyxml2-7.1.0-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/gtest-1.8.0-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/openssl-3.1.1-x64-lnx/lib64:${AFSIM_3RDPARTY_PATH}/curl-8.2.0-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/proj-8.1.1-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/geos-3.5.1-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/gdal-3.3.2-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/zlib-1.2.11-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/libpng-1.6.37-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/ffmpeg-4.2.4-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/libjpeg-turbo-2.1.2-x64-lnx/lib:${AFSIM_3RDPARTY_PATH}/osg-3.6.3-x64-lnx/lib64:${AFSIM_3RDPARTY_PATH}/osgEarth-2.10.1-x64-lnx/lib64:${AFSIM_3RDPARTY_PATH}/qt-5.12.11-x64-lnx/lib:${LD_LIBRARY_PATH}这一大段不是凑数的tiff 提供图像读写sqlite 负责场景数据库存储tinyxml2 用于 XML 场景解析gtest 是测试框架openssl 和 curl 支撑网络与加密组件proj/geos/gdal 构成地理坐标转换链路osg 与 osgEarth 负责三维渲染qt 提供 GUI 框架。它们之间有隐式依赖关系比如 gdal 依赖 proj 和 geos如果只追加 gdal 的 lib 而不追加前两者运行时就会报libproj.so.22: cannot open shared object file。这里的路径附带x64-lnx和lib64后缀是因为预编译库同时存在 32/64 位或 lib/lib64 两种布局。如果你的机器是 ARM 架构这套路径需要整体替换不能直接套用 x64 版本。3.3 myenv_temp.sh 脚本的作用与一次执行通过的方法环境变量写完进入依赖目录安装编译环境cd /home/sma/AFSIMSrc/dependencies chmod x myenv_temp.sh ./myenv_temp.sh这个脚本通常做两件事一是解压 dependencies 下预置的第三方库压缩包把它们展开到 3rd_party 对应目录二是补充安装系统级的编译依赖比如 build-essential、libx11-dev 等。如果脚本中途报错我踩过的经验是先把报错信息里的缺失包名记下来用 apt 补上后再重跑脚本不要反复执行整个脚本因为脚本里没有做幂等保护重复执行可能重复解压并覆盖已有文件。执行脚本前确认当前用户对/home/sma/AFSIMSrc/有写权限。文档里说后续指令在 root 下执行但这条脚本我建议在能写 dependencies 目录的用户下跑否则解压动作会因权限失败。4. 通过 cmake-gui 配置工程Cache、Configure、Generate 三步的真正含义4.1 Qt 5.12.11 的 bin 目录与权限处理第三方库配置完成后文档要求先进入 qt 的 bin 目录cd /home/sma/AFSIMSrc/dependencies/3rd_party/qt-5.12.11-x64-lnx/bin chmod x ./*这里把 bin 下所有文件加执行权限是为下一步启动 cmake-gui 准备 Qt 运行时环境。cmake-gui 本身依赖 Qt 的 XCB 插件如果 bin 目录下部分动态库或辅助工具没有执行权限GUI 界面可能起不来或异常闪退。我实际执行时还遇到过缺少libxcb-xinerama0的情况需要先apt install libxcb-xinerama0这是 Ubuntu 22.04 上比较常见的隐藏依赖。4.2 切换编译用户与 cmake-gui 路径填写文档特别强调su sma切换为编译时使用的普通用户再sudo cmake-gui。这里有个细节AFSim 的构建脚本在 configure 阶段会探测当前用户并将部分生成文件的属主设置为该用户。如果直接用 root 配置后续 make 阶段可能出现权限错乱尤其是make install向系统目录写文件时。cmake-gui 打开后需要填两处关键路径字段填写值Where is the source code/home/sma/AFSIMSrc/afsimWhere to build the binaries/home/sma/AFSIMSrc/afsim/buildbuild 目录如果不存在cmake-gui 会提示是否创建选是即可。这个 build 目录是编译产物的集中地后续 make、make install 后的 wsf_install 都从这里生成。4.3 Cache、Configure、Generate 的顺序问题与常见报错cmake-gui 左侧有一堆 Cache 变量第一次打开时是空的。点击 Configure 后CMake 会自动加载依赖探测结果生成 CMakeCache.txt。如果读取的内容不完整文档提示需要执行File | Reload Cache重新加载。Configure 阶段最常见的报错是找不到 Qt 组件比如Could not find a package configuration file provided by Qt5。这个时候不要盲目改 CMakeLists先检查环境变量里的CMAKE_PREFIX_PATH是否指向 qt-5.12.11-x64-lnx/lib/cmake。文档的路径配置里没有显式写这个变量但 configure 可以通过 LD_LIBRARY_PATH 里的 qt lib 路径反推。如果反推失败我一般在 cmake-gui 里手动添加一条 Cache 变量CMAKE_PREFIX_PATH/home/sma/AFSIMSrc/dependencies/3rd_party/qt-5.12.11-x64-lnx配置完成后点击 Generate这一步生成 Makefile 工程文件。Generate 报错通常和 CMake 版本或路径格式有关比如路径含有空格或特殊符号。检查确认源码路径和 build 路径都不含空格后重新 Generate 就能通过。注意Configure 和 Generate 是两个独立动作每次修改了 Cache 变量都需要重新 Configure然后再 Generate。只点 Generate 不点 Configure修改不会生效。5. 编译与安装make -j4、make install 与 wsf_install 产物5.1 make -j4 的并行度选择与编译耗时预期Generate 成功生成 Makefile 后切回终端执行su root cd /home/sma/AFSIMSrc/afsim/build make -j4-j4表示同时用 4 个编译任务并行处理。文档的编译机是 i7-13700H16G 内存这个并行度是稳的。我实际试过-j8编译速度确实更快但内存占用峰值明显升高16G 内存下会出现 swap 抖动所以文档给-j4不是保守是平衡了内存和 CPU 之后的合理选择。编译过程如果中途卡住不要急着 CtrlC先看最后几条日志是哪个源文件报错。AFSim 的编译过程是按模块推进的先编译基础库再编译 wsf最后编译 wizard 等可执行程序日志尾部会标明当前编译目标。如果出现internal compiler error多半是编译器版本切换没做彻底此时检查which gcc和gcc --version。5.2 make install 与 mil-std2525d 目录的必要性编译跑到 100% 并回到命令行后执行安装make install mkdir -p ${AFSIM_HOME}/build/wsf_install/resources/site/mil-std2525dmake install 会把编译生成的可执行文件、共享库、默认资源放到build/wsf_install下。最后一条 mkdir 命令是很多人容易忽略的它创建的是美军标 MIL-STD-2525D 符号资源的站点目录。AFSim 在运行 wizard 或渲染仿真场景时会从这个目录读取战术符号如果缺失图形界面能起来但地图上的军标符号全部显示为空白或异常。我测试过不加这行目录的后果wizard 启动后加载场景时日志报Unable to find site resource path场景能打开但符号系统不可用。加上目录后问题消失。5.3 wsf_install 目录结构与验证编译成败的快速方法安装完成后/home/sma/AFSIMSrc/afsim/build/wsf_install下会出现 bin 和 resources 两个核心目录。bin 里放着 wizard、afsim、mission 等可执行程序resources 里是运行时需要的图标、字体、符号数据。验证编译是否成功有两个档位第一档是检查可执行文件是否齐全比如ls /home/sma/AFSIMSrc/afsim/build/wsf_install/bin第二档是动态链接检查用ldd看主要可执行文件的依赖能否全部解析ldd /home/sma/AFSIMSrc/afsim/build/wsf_install/bin/wizard | grep not found如果输出为空说明所有第三方库链接正常这一步才是真正确认环境变量配置成功的关键依据。6. 避坑与常见问题排查路径、编译器、缓存三类问题的定位方法6.1 权限报错configure 阶段提示无法写入 build 目录现象cmake-gui 点击 Configure 后弹出红色错误提示Error in configuration process底部日志出现Permission denied。原因build 目录创建时属主是 sma但 cmake-gui 是以 sudo 权限启动的CMake 生成的临时文件写入 build 目录时发生属主冲突或者反过来以 root 创建 build 目录后切换到普通用户 configure 时无法写入。解决统一身份。文档的做法是先su sma再sudo cmake-gui这保证 configure 时 CMake 进程有 root 权限但工作目录属主是 sma。如果已经出现权限混乱我一般直接清理 build 目录重建rm -rf /home/sma/AFSIMSrc/afsim/build mkdir -p /home/sma/AFSIMSrc/afsim/build chown -R sma:sma /home/sma/AFSIMSrc/afsim/build6.2 环境变量不生效sudo 模式丢变量现象make 阶段报错找不到libosgEarth.so但echo $LD_LIBRARY_PATH里明明有这个路径。原因sudo默认不会保留当前用户的 LD_LIBRARY_PATH环境变量在 sudo 会话里被重置了。解决文档要求在 root 下执行 make所以我是在su root之后再执行一次source ~/.bashrc。如果用了 sudo可以用sudo -E make -j4-E参数保留当前环境变量。不过最省心的做法是把环境变量写入/etc/environment或/root/.bashrc让 root 登录后自动加载。6.3 编译器版本错乱gcc 11 与 gcc 4.8 混用现象编译到某个 C 文件时报undefined reference to __cxa_throw_bad_array_new_length或类似的 ABI 不匹配错误。原因CMake 探测到的是系统默认 gcc 11但第三方预编译库是用 gcc 4.8 编译的两套标准库实现存在 ABI 差异。解决用 alternatives 把编译器切换到 4.8.5并确认 CMake 重新探测update-alternatives --install /usr/bin/gcc gcc /usr/local/gcc-4.8.5/bin/gcc 100 update-alternatives --install /usr/bin/g g /usr/local/gcc-4.8.5/bin/g 100 update-alternatives --config gcc update-alternatives --config g切换后必须删掉 build 目录下的 CMakeCache.txt让 CMake 重新探测编译器否则缓存里还是 gcc 11 的路径。6.4 CMake 缓存残留修改环境变量后行为不变现象export 了新路径后重新 Configure但 CMake 依然找不到某个库日志里出现的还是旧的探测路径。原因CMakeCache.txt 里缓存了第一次 configure 时探测到的绝对路径比如TIFF_LIBRARY、GDAL_LIBRARY环境变量更新后这些缓存值不会自动刷新。解决在 cmake-gui 上点击File | Delete Cache或在命令行删除缓存后重新 configurerm -f /home/sma/AFSIMSrc/afsim/build/CMakeCache.txt rm -rf /home/sma/AFSIMSrc/afsim/build/CMakeFiles然后再打开 cmake-gui 走完整的 Configure 和 Generate 流程。6.5 make 阶段内存不足卡在 osgEarth 编译时被 kill现象编译过程中终端突然输出Killed然后进程退出dmesg 显示 OOM。原因osgEarth 等三维渲染库的编译单元很大单文件编译内存占用高-j8并行时内存峰值超过物理内存。解决回到-j4或者更保守地用-j2。同时确认系统没有其他高内存占用进程。如果机器只有 8G 内存建议增加 swap 空间后再编译不要硬扛。7. 运行测试用 wizard 拉起平台验证编译产物的最后一步编译安装完成后真正的验证是运行 wizard。在终端切换到安装目录的 bin 下cd /home/sma/AFSIMSrc/afsim/build/wsf_install/bin ./wizardwizard 启动后界面能正常加载、地图能缩放、左侧面板能展示内置场景列表就说明从第三方库链接到资源路径整条链路都是通的。如果启动即闪退优先看终端输出里的动态库报错比如libQt5XcbQpa.so.5找不到这就是典型的 Qt 环境问题回到 qt-5.12.11-x64-lnx/lib 路径确认是否被正确追加到 LD_LIBRARY_PATH。第一次启动 wizard 时如果看不到任何场景临时从 demos 目录导入一个官方示例就能区分是安装问题还是资源路径问题。我的习惯是直接用 demos 下的一个基础场景做冒烟测试而不是打开空工程这样能同时验证可执行程序、资源路径和第三方库三者的配合是否正常。整个编译过程中最让我印象深刻的教训是不要相信“上一次 configure 成功过”的缓存状态。不管哪一步报错先确认编译器版本、环境变量、CMakeCache 三者是干净的再往下走。从那以后我每次编译 AFSim 都会强制走一遍清理缓存、验证编译器、确认环境变量的三步流程这也恰好是这份文档里最容易被跳过的部分。希望这份实战记录能帮你在 Linux 上顺利跑起 AFSim少走我走过的弯路。本文还有配套的精品资源点击获取