★ FEATURED ARTICLE 简介面向核医学仿真初学者及需要在 Linux 环境中部署 GATE 的研究人员这份 PDF 文档以 GATE 8.0 为例梳理完整安装流程重点解决 Geant4、ROOT 等依赖环境配置与版本匹配问题。内容涵盖 gcc、cmake 前置检查Ubuntu 各版本所需依赖包安装ROOT 二进制包解压与环境变量配置Geant4 源码编译安装及可选光学功能依赖并附官方参考链接便于按图索骥排查依赖冲突、库版本不兼容等常见障碍。压缩包内共 1 个 PDF 文件大小约 1.09MB文档按安装顺序组织目录清晰、篇幅精炼适合作为实验室环境搭建、版本对照与终端操作时逐项查阅的速查手册。单文件形式便于离线保存、打印和在终端旁对照操作。文档重点突出、查阅方便。已有 1053 人学习可供核医学仿真入门者、医学物理方向学生及需要复现 GATE 实验的科研人员参考。1. 装完却画不出能谱GATE 8.0 的坑多半不在 Gate 本身核医学仿真软件GATE安装流程看上去就是一串 apt 命令加三次 make真正让人卡住的却往往不是 Gate 源码而是它脚下那三层依赖。我见过不止一次这样的现场终端里Gate命令能敲出来benchmark 的 mac 文件也跑了一分钟生成了 root 文件结果.x benchPET.C画不出能谱更常见的是在 ccmake 阶段就报Geant4_DIR找不到或者 make 到一半满屏 undefined reference。这类问题九成不是 Gate 的 bug而是 Geant4 版本、ROOT 环境变量、CLHEP 开关这三者里有一个没对齐。这篇笔记按我自己的复现顺序走一遍先查工具链再装 ROOT 和 Geant4然后编 Gate最后用 benchmark 把整条链验一遍。适合第一次在 Ubuntu 上装 GATE 的研究生和做蒙特卡洛仿真的工程师也适合装过一次没跑通、想弄清哪一步错了的人。2. 依赖链先理清gcc、cmake 与系统包的三层检查GATE 的编译链是「系统工具链 → ROOT → Geant4 → GATE」每一层都向下要头文件和符号任何一层版本或路径错位报错都会堆在最后一层爆发。所以这一章不是走过场而是把最容易忽略的三层检查提前做完后面 ccmake 里出现的稀奇古怪的路径错误八成能在这里找到根因。2.1 先把版本对应表抄下来再动手Gate 8.0 对应 Geant4 10.3这个对应关系是硬约束不是建议。你随手装了最新版 Geant4ccmake 阶段可能还过得去到了make链接阶段就会报一大片undefined reference to G4XXX因为 Gate 源码里调用的接口在你那版 Geant4 里签名已经变了。原文的安装说明里前后出现过geant4.10.03、geant4.10.10、geant4.10.05好几个版本号这正是最容易翻车的地方——示例命令和实际下载包对不上照着抄就会在 source 环境变量那一步指向一个不存在的目录。Gate 版本配套 Geant4参考系统Gate 7.09.6 p04Ubuntu 12.04Gate 7.110.1 p02Ubuntu 14.04Gate 7.210.2 p01Ubuntu 16.04Gate 8.010.3 p01Ubuntu 16.04Gate 8.210.5 p01Ubuntu 18.04注意这张表按原文的对应关系整理p01/p02 这类补丁号也会影响编译实际以下载页面写明的为准。装之前把这张表截图存下来后面每一步 source 的路径都对着它核对。2.2 检查 gcc、g、cmake、make 四个命令先确认工具链在不在、版本够不够。GATE 对 gcc 的下限要求不高4.8 起即可高于下限都没问题低于下限或者命令直接不存在才需要装。# 逐个确认工具链是否存在以及版本 gcc --version g --version cmake --version make --versiongcc --version输出了第一行就是版本号cmake --version同理。判断标准只看「是否满足最低版本」不需要卡在某个区间里。如果某条命令提示command not found说明这个工具根本没装直接进下一节。我一般会把这四条一次性敲完输出留存在终端里后面配置 ccmake 时对比版本方便。2.3 一次装齐 build-essential 与 cmake 工具# 更新软件源索引避免装到过期包 sudo apt-get update # build-essential 打包了 gcc、g、make、libc-dev # cmake-curses-gui 提供后面要用的 ccmake 文本界面 sudo apt-get install -y build-essential cmake cmake-curses-guibuild-essential是个元包装它会连带把 gcc、g、make、dpkg-dev、libc6-dev 一起装上比逐个装省事。cmake-curses-gui单独列出来是因为很多人只装了cmake到 Geant4 配置那一步敲ccmake会提示找不到命令。这一步失败最常见的原因是 apt 源过期或锁被占用先update再重试锁占用就等前面的 apt 进程结束。2.4 按系统版本补齐图形与 X11 依赖# Ubuntu 16.04 配 Gate 8.0 的推荐组合 sudo apt-get install -y libqt4-opengl-dev qt4-qmake libqt4-dev \ libx11-dev libxmu-dev libxpm-dev libxft-dev # 如果要启用 GATE_USE_OPTICAL 或 GDML补这个 sudo apt-get install -y libxml2-devlibxmu-dev是必须项Geant4 的 OpenGL 驱动和 GATE 的可视化都依赖它缺了会在 ccmake 阶段报 X11 相关找不到。libxml2-dev对应 GDML 几何描述和 optical 光子追踪普通玩家做 PET/SPECT 仿真时用不到但装了不亏。Ubuntu 18.04 上 qt4 那批包名会变成libqt5-default一类装之前先用apt-cache search qt5-default确认包名别硬抄 16.04 的命令。提示装包报依赖冲突时把提示里的库名连带版本号一起写进 apt 命令形如libxxx1.2.3比盲目--fix-broken稳。实在解不开优先考虑把系统降到 Ubuntu 16.04这是原文作者和我都验证过更省心的组合。2.5 目录规划源码、编译、安装三分家在正式下载之前先建一个统一目录把源码、编译产物、安装结果分开存。这一步不花时间但能省掉后面写环境变量脚本时一半的路径错误。# 统一根目录源码/编译/安装各一个子目录 mkdir -p ~/gate_stack/{src,build,install} ls ~/gate_stacksrc放解压出来的 ROOT、Geant4、Gate 源码build放各自的xxx-build目录install放最终安装路径。Geant4 和 Gate 都支持 out-of-source 编译也就是编译目录和源码目录分离这样做的好处是删掉 build 目录就能重新配置不会污染源码包出问题时排查范围也小。我习惯把三个软件的 install 目录也各自独立~/gate_stack/install/root、~/gate_stack/install/geant4、~/gate_stack/install/gate后面环境变量脚本一眼就能看明白谁指向谁。3. ROOT 与 Geant4二进制包和源码编译的两条路怎么选这一章是整条链里耗时最长的一段。ROOT 建议直接用官方编译好的二进制包省掉一两个小时的编译Geant4 必须自己源码编译因为 Gate 对 Geant4 的 CMake 选项有硬要求尤其是 CLHEP 的集成方式。两条路的技术细节不一样分开说清楚。3.1 ROOT 为什么优先用二进制包ROOT 官方为常见的 Linux 发行版提供了预编译的二进制包按 gcc 版本和系统代号区分文件名下载解压就能用。自己编译 ROOT 不是不行但它依赖一堆额外的库zlib、libssl、libtbb 等编译动辄一小时起一旦缺库还要回头补对 GATE 安装来说完全没必要。选二进制包的唯一要求是看清文件名里带的系统代号和 gcc 版本要和你当前系统对得上。# 下载后解压二进制包文件名按你实际下载的版本替换 tar -xzf root_v6.xx.xx.Linux-ubuntu16-x86_64-gcc5.4.tar.gz -C ~/gate_stack/src # 改个短名字方便后面 source mv ~/gate_stack/src/root ~/gate_stack/src/root_v6 # 加载 ROOT 环境变量只在当前终端有效 source ~/gate_stack/src/root_v6/bin/thisroot.shtar -xzf里的-C指定解压目标目录避免解压到当前工作目录。thisroot.sh是 ROOT 自带的环境脚本它会把ROOTSYS、PATH、LD_LIBRARY_PATH一次性配好不用手动 export。注意这个脚本只在当前终端会话生效关掉终端或新开一个窗口就要重新 source这一点后面 Gate 编译时还会再遇到是所有环境变量问题里出现频率最高的一个。# 验证 ROOT 是否可用进入交互界面后输入 .q 退出 root能进到 ROOT 的root [0]提示符就说明解压和环境变量都没问题。如果报error while loading shared libraries多半是系统缺少libtbb2之类的运行库按报错里的 .so 名字用apt-file search反查包名装上即可。3.2 Geant4 源码下载与目录准备Geant4 必须源码编译选版本时严格按第 2 章那张表来Gate 8.0 就下 10.3。下载下来的是个 tar 包解压后是源码目录编译和安装目录要另建。# 解压 Geant4 源码到 src tar -xzf geant4.10.03.p03.tar.gz -C ~/gate_stack/src # 建编译目录和安装目录 mkdir -p ~/gate_stack/build/geant4.10.03-build mkdir -p ~/gate_stack/install/geant4.10.03 # 进入编译目录out-of-source 编译 cd ~/gate_stack/build/geant4.10.03-build解压出来的源码目录名和 tar 包名可能不完全一致有的包里带.p03有的不带用ls ~/gate_stack/src确认实际目录名后面ccmake ../实际目录名要用到。编译目录和源码目录是平级关系所以 ccmake 里用相对路径../geant4.10.03.p03指回源码这一点搞错会报CMake Error: The source directory does not exist。3.3 ccmake 里必须改对的四个开关# 用 ccmake 打开文本配置界面按 c 配置、按 e 返回、按 g 生成退出 ccmake ../geant4.10.03.p03进到界面后按c做第一次配置会刷出一屏变量。重点改四项变量名建议值原因CMAKE_INSTALL_PREFIX~/gate_stack/install/geant4.10.03的绝对路径安装路径写相对路径容易在 install 阶段错位GEANT4_INSTALL_DATAON自动下载 Geant4 的物理数据不选则跑仿真时报缺数据GEANT4_USE_SYSTEM_CLHEPOFFGate 7.0 之后用 Geant4 集成的 CLHEP选 ON 而没装外部 CLHEP 会链接失败GEANT4_USE_OPENGL_X11 / GEANT4_USE_QT需要可视化就 ON依赖前面的 libxmu-dev、qt4 包CMAKE_INSTALL_PREFIX一定要写绝对路径把~展开成/home/你的用户名/...ccmake 里对~的支持不总是可靠写相对路径更容易在make install时把文件装到不该去的地方。GEANT4_USE_SYSTEM_CLHEP是原文踩坑很典型的一处选 OFF 用集成版选 ON 就要求你先手动把 CLHEP 装好并让 Geant4 找得到官方文档里也不推荐后者。如果不确定某个选项要不要开保持默认比乱开安全报错时至少能缩小范围。改完再按一次c做二次配置然后按g生成 Makefile 并自动退出。如果二次配置时报某个包找不到按提示补装对应的-dev包再重新进入 ccmake不要跳过。3.4 make -jN 与 install 的跑法# N 填 CPU 核心数4 核就是 -j4别贪多把内存跑满 make -j4 # 编译完成后安装到 CMAKE_INSTALL_PREFIX 指定的路径 make install # 加载 Geant4 环境变量同样只在当前终端有效 source ~/gate_stack/install/geant4.10.03/bin/geant4.shmake -j4里的 N 写大了会内存爆掉每核编译任务占几百 MB 到 1 GB16 GB 内存的机器开-j8就要小心。这一步耗时长中间报错大多是缺库或某个 CMake 变量没配按报错信息查比盲目重来快。geant4.sh会把G4INSTALL、G4LEDATA、PATH配好后面 Gate 的 ccmake 就是靠这些变量找到Geant4_DIR的记得和 ROOT 的thisroot.sh一样新开终端要重新 source。提示Geant4 编译到一半断了不用从头来make支持断点续编直接再敲一遍make -j4即可。但要是改过 ccmake 变量建议先make clean再重编避免新旧对象文件混在一起。4. Gate 编译ccmake 里的四个关键变量到这一步ROOT 和 Geant4 都已经 source 过Gate 的编译本质上是复刻 Geant4 的流程出问题的地方集中在「环境变量有没有传进来」和「ccmake 认不认得出 Geant4」。这一章把编译和环境变量脚本一起收掉。4.1 编译前必须先 source 两个脚本# 在同一个终端里依次 source缺一个后面就认不出路径 source ~/gate_stack/src/root_v6/bin/thisroot.sh source ~/gate_stack/install/geant4.10.03/bin/geant4.sh # 确认两个关键变量有没有值 echo $ROOTSYS echo $G4INSTALL如果echo $ROOTSYS输出为空说明 thisroot.sh 没生效那么后面 ccmake 里ROOTCINT_EXECUTABLE大概率是空值。如果echo $G4INSTALL有值但 ccmake 里Geant4_DIR还是NOTFOUND那就是 Geant4 的 CMake 配置文件路径没被扫到这时要在 ccmake 里手动把Geant4_DIR指到~/gate_stack/build/geant4.10.03-build目录下那个Geant4Config.cmake所在的位置。原文把这步的原因归结为「前面 source 出了问题」是准确的。4.2 解压 Gate 并建编译目录# 解压 Gate 源码 tar -xzf Gate-8.0.tar.gz -C ~/gate_stack/src # 建立编译目录 mkdir -p ~/gate_stack/build/gate_v8.0-build mkdir -p ~/gate_stack/install/gate_v8.0 # 进入编译目录 cd ~/gate_stack/build/gate_v8.0-build目录结构保持和前两节一致编译目录和源码目录平级安装目录单独一个。这里如果遇到源码目录名和 tar 包名不一致同样用ls确认ccmake ../实际目录名里的相对路径就是指这个源码目录名。4.3 ccmake 三个变量逐项核对# 打开 Gate 的配置界面 ccmake ../Gate-8.0按c配置后会看到一屏变量重点核对这三项变量名建议值说明CMAKE_INSTALL_PREFIX~/gate_stack/install/gate_v8.0的绝对路径决定 make install 的落点Geant4_DIR指向 Geant4 build 目录内含 Geant4Config.cmake 的路径为空或 NOTFOUND 时手动填ROOTCINT_EXECUTABLE~/gate_stack/src/root_v6/bin/rootcintsource 有问题时会丢手动补其余选项保持默认。ECAT7、ITK、LMF 这类可选包普通做 PET/SPECT 仿真的用不到保持 OFF如果确实要用必须在编 Gate 之前先把它们装好编完再回头装会导致 Gate 找不到。注意ccmake 里改完变量名字后路径一定要重新核对一遍尤其是你中途换过 ROOT 或 Geant4 目录的情况。填错路径不会在配置阶段报错而是在 make 阶段以一大堆找不到头文件的形式爆发。配置通过后按g生成 Makefile执行make -j4和make install参数含义和第 3.4 节完全一样这里不再重复。Gate 的编译时长比 Geant4 短不少四核机器十几分钟量级中间报错绝大多数还是环境变量问题回到 4.1 节重新 source 基本能解决。4.4 把三套环境变量收进一个脚本# 在 Gate 安装目录的 bin 下建统一的环境脚本 cd ~/gate_stack/install/gate_v8.0/bin vim gate_env.sh # 写入以下内容 # !/bin/sh source ~/gate_stack/src/root_v6/bin/thisroot.sh source ~/gate_stack/install/geant4.10.03/bin/geant4.sh export PATH$PATH:~/gate_stack/install/gate_v8.0/bin脚本里三行分别是 ROOT、Geant4、Gate 的环境加载顺序不能乱ROOT 和 Geant4 必须在 Gate 之前。如果启用了外部 CLHEP 或 ITK还要补LD_LIBRARY_PATH那几行原文里给了注释模板普通用法保持注释即可。gate_env.sh本身沿用 Geant4 风格的.sh后缀和 sh 语法source时用bash或sh都行。# 当前终端生效 source ~/gate_stack/install/gate_v8.0/bin/gate_env.sh # 验证 Gate 可执行文件在 PATH 里 which Gatewhich Gate能输出路径就说明 PATH 追加成功输出为空说明脚本没 source 或者 PATH 那行写错了。这一步成功后终端里直接敲Gate就能进交互界面。5. 避坑与排查五个让编译前功尽弃的细节装 GATE 的血泪经验基本都集中在这一章。下面五条是我和身边同事实际踩过的按「现象 → 原因 → 解决」写遇到对应现象先按这里的思路排查比从头重装快得多。5.1 现象新开终端后 ccmake 里 Geant4_DIR 变成 NOTFOUND原因thisroot.sh和geant4.sh只在 source 的那个终端会话里有效新开终端不会自动继承ccmake 找不到G4INSTALL就填不出 Geant4 路径。这是环境变量问题里出现频率最高的一条原文也专门用加粗标注过。解决进入 ccmake 之前在同一个终端里把两个脚本都 source 一遍再用echo $ROOTSYS和echo $G4INSTALL确认有值。长期的话把source gate_env.sh写进~/.bashrc新终端自动加载。5.2 现象make 阶段满屏 undefined reference to G4XXX原因Geant4 版本和 Gate 版本不配套。Gate 8.0 要 Geant4 10.3装了 10.5 或更新的版本部分接口签名变了链接时就找不到符号。解决回第 2 章查对应表重装匹配版本的 Geant4然后把 Gate 的 build 目录整个删掉重新 ccmake。不要指望改几个编译选项绕过版本不匹配是硬伤。5.3 现象Geant4 配置时报 CLHEP 相关链接错误原因GEANT4_USE_SYSTEM_CLHEP被设成了 ON但系统里并没有装外部 CLHEP。Gate 7.0 之后用 Geant4 内置的 CLHEP 就够了不需要单独装。解决在 ccmake 里把这一项改回 OFF重新配置再编。如果之前已经编了一半先make clean。5.4 现象make install 之后文件散落在奇怪的位置原因CMAKE_INSTALL_PREFIX写成了相对路径或者带了~没展开。make install会按这个路径把文件拷过去相对路径的基准是当前工作目录结果就是装到了 build 目录下面。解决ccmake 里改成完整绝对路径/home/用户名/...形式重新配置后再make install。已经装错的文件手动删掉不用重编。5.5 现象ccmake 报找不到 X11 或 OpenGL 相关库原因系统包没装齐最常见的是缺libxmu-dev其次是 Ubuntu 18.04 上误用了 16.04 的 qt4 包名。解决按第 2.4 节的列表对照补装Ubuntu 18.04 上先用apt-cache search确认 qt5 的包名再装。补装后重新进 ccmake让配置阶段重新扫描。5.6 一个快速自检顺序遇到报错别急着重装按这个顺序过一遍八成能定位先echo $ROOTSYS $G4INSTALL看环境变量再which root、which Gate看命令在不在 PATH然后进 ccmake 看Geant4_DIR和ROOTCINT_EXECUTABLE两个值最后才怀疑版本不匹配。前两步花不了一分钟能排掉大部分低级错误。6. benchmark 验证一次跑通之后再做三件事编译成功不等于装对了GATE 自带 benchmark 就是干这个用的。进到源码目录下的benchmarks/benchPET先删掉旧的benchmarkPET.root再跑Gate benchPET.mac大约一分钟后 Ctrlz 中断会生成新的 root 文件。接着起 ROOT执行.x benchPET.C能画出能谱就说明 ROOT、Geant4、Gate 三者的数据链是通的。# 进 benchmark 目录注意是源码目录不是 build 目录 cd ~/gate_stack/src/Gate-8.0/benchmarks/benchPET # 清掉旧产物再跑 rm -f benchmarkPET.root Gate benchPET.mac # 一分钟后 Ctrlz 中断再进 ROOT 画图 root # 在 ROOT 交互界面里执行 .x benchmarkPET.C如果.x执行后报cannot open benchmarkPET.root先确认中断前文件是否真的生成文件大小为 0 就是 mac 文件根本没跑起来回到第 4 章查环境变量。如果图出来了但能谱形状不对那是物理列表或几何参数的问题和安装无关。从那以后我每次装完 GATE 都强制走一遍这个 benchmark不管编译日志多干净——编译通过只代表语法和链接对了benchmark 才代表运行时数据链是通的。这三件事我一般顺手做掉把gate_env.sh的 source 写进~/.bashrc免得新终端反复手动加载把三个软件的版本号记在一个versions.txt里塞进安装目录下次换机器直接照抄benchmark 生成的 root 文件留一个作基线以后改配置出问题可以拿来对比。踩过的坑多了就明白装软件最贵的不是编译那几个小时而是装完之后不确定它对不对。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
