Gate 8.0 核医学仿真环境搭建：Geant4 10.3 与 ROOT 6 编译避坑

简介面向核医学仿真入门者与Linux科研环境搭建人员的GATE安装流程文档聚焦开源核医学仿真软件GATE在Ubuntu平台部署前的依赖核查、系统包准备以及Geant4、ROOT等关键组件的版本匹配与配置要点适合需要独立完成仿真环境搭建的研究生、工程师和实验人员参考。资源以单个PDF文件交付压缩包约1.09MB篇幅精炼便于本地查阅、打印标注和按章节对照。内容围绕GATE 8.0等常见版本的Geant4版本对应、ROOT二进制包选择及依赖库差异展开梳理安装顺序、必备包清单和常见报错排查思路可帮助读者减少因系统版本、库依赖不一致而产生的反复试错快速定位环境搭建中的关键环节。已有1053人学习可作为核医学仿真平台部署时的流程索引与排错参照。1. 版本先对齐Gate 8.0 锁 Geant4 10.3ROOT 选 6.x 就够核医学仿真软件GATE安装最容易出问题的节点之一是版本对齐。Gate 8.0 官方指定 Geant4 10.3有人图省事装了 Geant4 11编译到一半报 API 不兼容也有人在新版 Ubuntu 上直接 apt 装 qt4源里根本没有这个包。这套环境在核医学蒙卡仿真里很常见装不好整个项目卡在编译阶段连 benchmark 都跑不起来。这篇记录按 Gate 8.0 Geant4 10.3 ROOT 6 的组合走一遍适合刚接触 GATE、手上只有一台 Ubuntu 机器的开发者。2. 编译工具链与系统依赖gcc、cmake 和那串 qt4 包怎么装才不打架2.1 先查 gcc 与 cmake版本底线在哪Gate 8.0 的编译链要求不算高gcc 4.8 以上、cmake 3.x 以上就能开工。原文里那台机器 gcc 是 7.3.0比官方标注的区间上限还高照样能编——版本检查的重点是「不低于下限」不是「必须落在某个区间里」。这一点容易误会有人看到 [4.8-6.2] 就以为 7.x 不能用回头去降级 gcc反而把系统搞乱。# 三条命令分别看 C 编译器、C 编译器和构建工具 gcc --version g --version cmake --version输出第一行就是版本号。如果提示 command not found说明没装往下走 2.2。g 单独查一次是因为 build-essential 没装全的时候gcc 在、g 缺编译 Geant4 的 C 源码时才会报错不如提前发现。2.2 build-essential 和 cmake 的安装顺序# 先更新包索引避免装到旧清单 sudo apt-get update # build-essential 是元包把 gcc、g、make、libc-dev 一起拉下来 sudo apt-get install -y build-essential # cmake-curses-gui 提供 ccmake 这个带界面的配置工具 sudo apt-get install -y cmake cmake-curses-guibuild-essential比单独装 gcc 省事它把编译 C/C 需要的一整套都带上了。cmake-curses-gui是我特意单列的一条Gate 和 Geant4 的配置都靠 ccmake 的终端界面完成只装 cmake 的话命令行里敲 ccmake 会提示找不到。-y是自动确认写进脚本时用手动敲可以不加看一眼包列表再回车。顺序上先 update 再 install。有人跳过 update 直接装遇到源里包版本旧、依赖对不上报一堆 held broken packages回头还得重来。2.3 按 Ubuntu 版本对号入座装依赖包原文给了三套包清单对应 18.04、16.04、14.04/12.04。核心差异在 Qt 版本16.04 配 qt418.04 之后逐步转 qt5。Gate 8.0 配 Geant4 10.3 是 16.04 时代的组合所以按 qt4 那套走。系统版本对应组合Qt 包备注Ubuntu 16.04Gate 8.0 Geant4 10.3libqt4-dev、qt4-qmake这篇记录的主线Ubuntu 18.04Gate 8.2 Geant4 10.5libqt5-default包名换了不能照抄Ubuntu 14.04/12.04Gate 7.x Geant4 9.6/10.1libqt4-core 等老组合包更碎# 16.04 主线qt4 这套逐行装也行一次装完也行 sudo apt-get install -y cmake cmake-curses-gui build-essential \ libqt4-opengl-dev qt4-qmake libqt4-dev \ libx11-dev libxmu-dev libxpm-dev libxft-dev逐个说libqt4-opengl-dev给 Qt 的 OpenGL 支持Geant4 的可视化界面要用qt4-qmake是 Qt 的构建工具libx11-dev、libxmu-dev、libxpm-dev、libxft-dev是 X11 开发头文件Geant4 的图形驱动编译时依赖它们。少一个ccmake 配置阶段可能不报make 到一半才缺头文件。原文「必须的包」那行写了cmake-curses-gui、libqt5-default、libxmu-dev注意这里 qt5 和 qt4 混着写容易让人困惑。16.04 上装libqt5-default不解决 qt4 的问题反而可能把 qt4 的依赖搞乱。我的做法是系统版本和 Gate 版本先对齐再照抄对应那一行的包清单不跨版本混装。2.4 libxml2-dev 与可选包GATE_USE_OPTICAL 的前置如果后面 ccmake 里要把 GATE_USE_OPTICAL 打开或者 Geant4 配置里 GDML 相关选项要开得先装 libxml2-dev# XML 解析头文件GDML 几何和光学光子追踪都靠它 sudo apt-get install -y libxml2-dev不装的话ccmake 按 c 会在这一项报错或者编译到 GDML 相关源文件时缺头文件。原文在 16.04 那段单独提了这条说明它是可选项但一旦要开光学功能就是硬依赖。Gate 还有几个可选包ECAT7、ITK、LMF分别对应 ECAT 格式、ITK 图像读写、LMF 列表模式数据。这些要在编译 Gate 之前装好装完再回头补得重新 ccmake 和 make。普通仿真用不到先跳过ccmake 里保持 OFF 就行。动手前建议建一个统一目录把 ROOT、Geant4、Gate 的源码、build、install 都放进去# 统一栈目录后面环境脚本里的路径都指向这里 sudo mkdir -p /opt/gate-stack sudo chown -R $USER:$USER /opt/gate-stack路径统一后面换机器、写文档都省事。chown是把目录所有权给当前用户不然 make install 时要 sudo装出来的文件归 root后面编辑 gate_env.sh 还得再提权。这个细节原文没写但踩过一次就知道麻烦。3. ROOT 与 Geant4 10.3源码软件的两块地基怎么编译3.1 ROOT 优先用二进制包省掉一小时编译Gate 本身就是源码软件没有现成二进制包必须自己编译但它依赖的 ROOT 有官方预编译包解压即用没必要也从源码编。ROOT 自己编译要一两个小时还得配一堆依赖对装 Gate 这件事来说是额外风险。cd /opt/gate-stack # 文件名里的 gcc 版本别比系统 gcc 高太多ubuntu16 对应 gcc5.4 tar -xzf root_v6.12.06.Linux-ubuntu16-x86_64-gcc5.4.tar.gz # 解压出来默认叫 root改成带版本号的名字多版本共存不打架 mv root root_v6.12.06 # 设置 ROOT 的 PATH、LD_LIBRARY_PATH、ROOTSYS source /opt/gate-stack/root_v6.12.06/bin/thisroot.sh # -b 批处理-q 退出用来验证安装 root -b -qthisroot.sh是 ROOT 自带的环境脚本source 完root命令就能用。root -b -q是批处理模式启动再退出能正常返回就说明库路径没问题。不加-b -q会进交互界面得手动.q退出。注意source 只在当前终端有效。换一个终端窗口root命令又找不到了。这是后面很多问题的源头先记住。3.2 Geant4 10.3 解压与 build/install 目录规划版本必须对上Gate 8.0 要 Geant4 10.3。原文写到 10.3.p03 的补丁版下载时认准 10.3 系列别拿 10.4、10.5 凑合。cd /opt/gate-stack # 解压源码 tar -xzf geant4.10.03.p03.tar.gz # 源码、build、install 三个目录分开CMake 的标准做法 mkdir -p geant4.10.03-build geant4.10.03-install cd geant4.10.03-build # 用 ccmake 打开配置界面指向源码目录 ccmake ../geant4.10.03.p03源码目录、build 目录、install 目录三者分开好处是 build 里全是中间文件install 里是最终的头文件、库和脚本删 build 不影响安装。有人图省事在源码目录里直接 cmake编完源码目录一团糟想重编还得重新解压。3.3 ccmake 里四个必须改的选项ccmake 界面操作方向键移动回车编辑按c配置按e退出信息页按g生成并退出。第一次按 c 会刷一屏检测信息正常按 e 回去继续看选项。选项建议值原因CMAKE_INSTALL_PREFIX/opt/gate-stack/geant4.10.03-install绝对路径相对路径容易配错GEANT4_INSTALL_DATAON自动下载 G4EMLOW 等数据包不装后面跑不了GEANT4_USE_SYSTEM_CLHEPOFF用 Geant4 集成 CLHEP不单独装GEANT4_BUILD_MULTITHREADEDON多线程Gate 后面也能用上GEANT4_USE_QTON可视化界面GEANT4_USE_OPENGL_X11ONX11 图形驱动GEANT4_USE_SYSTEM_CLHEP这一项值得多说两句。早期 Gate 要单独装 CLHEP 2.3.x后来 Geant4 自带一份Gate 7.0 之后就不需要额外装了。设成 OFF 就是用 Geant4 内部那份少一个依赖也少一个版本对不上的风险。原文提到「如果想手动安装则需要安装对应 Geant4 正确的版本不推荐」理由就在这里。GEANT4_INSTALL_DATA打开后make install 阶段会联网下载数据包网络不稳会卡住。常见做法是先把数据包下好放到指定目录或者断了重跑 make install它会接着下。改完按c再配置一次没问题按g生成并退出。生成完 build 目录里会出现 Makefile。3.4 make -jN 的并发数和内存账# N 是处理器核数4 核就 -j4用 nproc 查 make -j4 # 安装到 CMAKE_INSTALL_PREFIX 指定的目录 make installGeant4 编译吃内存每个编译单元几百 MB4 核 8G 内存够用16G 更稳。内存小就-j2别硬上-j8容易被系统 OOM killer 杀掉终端只显示一个 Killed不知道的还以为是源码问题。make install会把东西拷到 install 目录因为目录已经归当前用户这一步不需要 sudo。如果前面没 chown这里就得 sudo make install装出来的脚本归 root后面 source 没问题但想改就费劲。3.5 geant4.sh 只在当前终端生效# 设置 G4 相关环境变量和 PATH source /opt/gate-stack/geant4.10.03-install/bin/geant4.sh # 验证一下应该有输出 echo $G4INSTALL同样换终端就失效。这一步和 ROOT 的 thisroot.sh 一样后面会统一写进 gate_env.sh不用每次手动敲。4. 编译 Gate 8.0ccmake 配置、make 和环境变量文件4.1 下载解压与目录规划Gate 8.0 的源码包从官网下载文件名可能是gate_8.0.tar.gz解压出来的目录名各版本不太一样统一改个名后面路径好写。cd /opt/gate-stack # 解压源码 tar -xzf gate_8.0.tar.gz # 源码目录加 -src 后缀和 build/install 区分开 mv gate_v8.0 gate_v8.0-src mkdir -p gate_v8.0-build gate_v8.0-install原文这里有个容易混的地方标题写 Gate 8.0命令里出现过Gate-8.2.tar.gz、gate_v8.2-install。这是拿 8.2 的示例套 8.0 的流程照抄会路径对不上。装哪个版本目录名就用哪个版本别混。4.2 编译前必须重新 source 两个环境脚本# 前面 source 的只对那个终端有效新终端要重来 source /opt/gate-stack/root_v6.12.06/bin/thisroot.sh source /opt/gate-stack/geant4.10.03-install/bin/geant4.sh # 两个变量都有输出再往下走 echo $ROOTSYS $G4INSTALL cd /opt/gate-stack/gate_v8.0-build ccmake ../gate_v8.0-src这是最高频的出错点。新开终端时前面 source 全丢了ccmake 找不到 Geant4 和 ROOT就会在Geant4_DIR和ROOTCINT_EXECUTABLE上显示 NOTFOUND。有人不看这两个变量直接按 c 按 gmake 的时候报一堆头文件找不到回头查半天。4.3 ccmake 里盯紧 Geant4_DIR 和 ROOTCINT_EXECUTABLE选项建议值说明CMAKE_INSTALL_PREFIX/opt/gate-stack/gate_v8.0-install安装路径绝对路径Geant4_DIR.../geant4.10.03-install/lib/Geant4-10.3.3指向 install 下的 lib不是源码ROOTCINT_EXECUTABLE.../root_v6.12.06/bin/rootcintROOT 的 bin 下GATE_USE_OPTICALOFF要开先装 libxml2-devGATE_USE_ECAT7 / ITK / LMFOFF可选包普通仿真不用按c配置第一次会有大量输出按e退出信息页再看选项。Geant4_DIR指向的是 install 目录下的lib/Geant4-10.3.x不是源码目录也不是 build 目录——这一点最容易填错。ROOTCINT_EXECUTABLE在 ROOT 的 bin 下source 对了会自动填上。如果这两项和你装的路径不匹配手动改成绝对路径。改完再按c确认没有新的 NOTFOUND按g生成。4.4 make -jN 与 make install# 编译核数按机器来 make -j4 # 安装到 gate_v8.0-install make installGate 本身代码量比 Geant4 小编译快一些但依赖链长前面路径不对会在这里集中报错。make install完gate_v8.0-install/bin下应该有Gate可执行文件可以先ls看一眼再往下走。4.5 gate_env.sh 怎么写、怎么挂到 .bashrc在gate_v8.0-install/bin下新建gate_env.sh#!/bin/sh # ROOT 环境 source /opt/gate-stack/root_v6.12.06/bin/thisroot.sh # Geant4 环境 source /opt/gate-stack/geant4.10.03-install/bin/geant4.sh # Gate 可执行文件路径 export PATH$PATH:/opt/gate-stack/gate_v8.0-install/bin # 没装外部 CLHEP原文那三行 CLHEP 的 export 注释掉不写进来三行分别对应 ROOT、Geant4、Gate把前面手动 source 的东西固化到一个文件里。原文最后三行 CLHEP 的 export 是给手动装 CLHEP 的人用的这里没装注释掉或者不写。# 给执行权限 chmod x /opt/gate-stack/gate_v8.0-install/bin/gate_env.sh # 当前终端先 source 一次验证 source /opt/gate-stack/gate_v8.0-install/bin/gate_env.sh which Gate # 追加到 .bashrc新终端自动加载用 不用 别覆盖原文件 cp ~/.bashrc ~/.bashrc.bak echo source /opt/gate-stack/gate_v8.0-install/bin/gate_env.sh ~/.bashrcwhich Gate应该输出 install/bin/Gate。.bashrc在交互式终端打开前执行桌面终端一开就自动加载。注意 ssh 执行单条非交互命令时不会加载那种场景要手动 source。追加前先备份一份改坏了还能救回来。5. 排查与避坑source 失效、路径写错和依赖打架5.1 现象ccmake 报 Could NOT find Geant4现象在gate_v8.0-build里跑 ccmakeGeant4_DIR显示 NOTFOUND按 c 之后仍然找不到终端里能看到 Could NOT find Geant4 的提示。原因当前终端没 sourcegeant4.sh或者 source 的是另一个 Geant4 版本G4INSTALL指向的不是 10.3。还有一种情况是 source 了但顺序不对先 source Gate 再 source Geant4ccmake 缓存里还是旧的 NOTFOUND。解决# 重新 source确认变量指向 10.3 source /opt/gate-stack/geant4.10.03-install/bin/geant4.sh echo $G4INSTALL # 确认这个路径真实存在 ls /opt/gate-stack/geant4.10.03-install/lib/Geant4-10.3.3/路径存在再回 ccmake 按 c。还不行就手动把Geant4_DIR改成绝对路径指向lib/Geant4-10.3.3不要指向 build 目录。改完按 c 重新配置再按 g 生成。5.2 现象Gate 启动报 libCore.so 找不到现象终端里敲Gate报error while loading shared libraries: libCore.so: cannot open shared object file。原因ROOT 的库路径没进LD_LIBRARY_PATH。多半是新开终端没 sourcegate_env.sh或者.bashrc里那行路径写错、用了~而不是绝对路径。解决# 看 Gate 依赖哪些库没找到 ldd $(which Gate) | grep not found # 重新 source 环境脚本 source /opt/gate-stack/gate_v8.0-install/bin/gate_env.sh # 再查一次应该没有输出 ldd $(which Gate) | grep not found如果还有 not found看是哪个库补对应路径。.bashrc里统一用绝对路径别用~不同 shell 展开时机不一样容易出问题。5.3 现象apt 装 qt4 报 Unable to locate package现象sudo apt-get install libqt4-dev报E: Unable to locate package libqt4-dev。原因系统版本太新qt4 已经从官方源里移除18.04 之后逐步转 qt5。这不是命令写错是源里真没有。解决两条路。一是换到 16.04 上装 Gate 8.0这是最省事的包清单直接对得上。二是用 Gate 8.2 Geant4 10.5 qt5包名换成libqt5-default、qtbase5-dev流程一样只是版本组合不同。不建议把旧版本的源混进新系统。依赖会打架修起来比重装还久。原文说「最后还没解决就换一个系统吧Ubuntu16.04 更稳定一些」这句话是经验之谈不是偷懒。5.4 现象make -jN 编译中途被 Killed现象Geant4 编译到某个 cpp 时终端显示 Killedmake 退出没有其他报错。原因内存不够-jN开太大系统 OOM killer 杀了编译器进程。Geant4 的某些源文件编译时单个进程能吃到 1G 以上4G 内存开-j4很容易触发。解决# 看内存和 swap free -h # 看内核日志里有没有 Out of memory dmesg | tail -20 # 降并发重编 make -j28G 内存-j4一般够4G 内存建议-j1或-j2。有 swap 的话会慢但不容易被杀。dmesg里能看到 Out of memory 字样就确认是这个问题不用去查源码。6. 验证跑通benchmarkPET 跑一遍才算装完装完不验证等于没装。Gate 源码里带了 benchmark 目录benchPET 是最小的一套 PET 仿真跑通它说明 ROOT、Geant4、Gate 三层都接上了。# 进 benchmark 目录注意是源码目录不是 build 或 install cd /opt/gate-stack/gate_v8.0-src/benchmarks/benchPET ls # 删掉旧的输出文件避免拿旧结果冒充新结果 rm -f benchmarkPET.root # 跑宏观文件让程序飞一会 Gate benchPET.mac大约一分钟后按CtrlC终止。原文写的是Ctrlz实际Ctrlz是把进程挂起不是终止挂起后终端里还要kill %1才退干净用CtrlC更直接。# 进 ROOT 交互界面 root -b -q进去后执行宏// 读 benchmarkPET.root画符合能谱之类的图 .x benchmarkPET.C能出图就说明 ROOT 能正常读 Gate 写出的文件。这一步报错多半还是 ROOT 库路径的问题回头看 5.2。检查项命令预期Gate 可执行which Gate输出 install/bin/Gate动态库完整ldd $(which Gate) | grep not found无输出benchmark 输出ls benchmarkPET.root文件存在且大小非零ROOT 读文件.x benchmarkPET.C正常出图无报错从那以后我每次装完 Gate都不急着跑自己的 mac先拿 benchPET 走一遍确认三层环境都对得上再动项目文件。这套流程看着多真正卡人的就是 source 和路径两件事把它们固定进gate_env.sh后面换终端也不慌。希望帮到你。本文还有配套的精品资源点击获取