手里有一台常年跑着 CentOS 的计算节点硬盘里躺着一堆单细胞 ATAC-seq 的 fragment 文件这时候你大概率会碰到 ArchR 这个名字。ArchR 是 R 语言里做单细胞染色质可及性分析绕不开的一个工具包从上游的 Arrow 文件生成、doublet 过滤到降维聚类、peak 注释、motif 富集、轨迹推断整条链路它都能接上。问题是它不在 CRAN 上依赖树又深得吓人随便一装就是几十个包跟着编译而 CentOS 特别是 CentOS 7默认的工具链又老得让人头大。这篇就把我在 CentOS 系列机器上装 ArchR 的完整过程摊开讲一遍系统层要补什么、GCC 为什么必须换、R 从源码编译时哪些参数真正影响后面的跑分和编译成功率、依赖包按什么顺序装才不容易翻车以及那些只会出现在日志末尾一两行的报错到底对应什么问题。不管你是第一次在服务器上折腾 R 生信环境还是已经被had non-zero exit status折磨过几轮下面这些内容应该都能直接拿去用。1. 动手之前CentOS 上装 ArchR 的整体思路1.1 为什么这台机器上装 ArchR 特别容易卡住在 Ubuntu 或者 macOS 上装 ArchR多数人的体验是装是装上了就是慢一点。换到 CentOS事情的性质就变了。核心矛盾在于工具链的版本落差CentOS 7 默认的 GCC 是 4.8.5这个版本对 C14 的支持都是残缺的C17 根本谈不上。而 ArchR 依赖链里的RcppArmadillo、nabor、uwot、motifmatchr这些包这几年陆续把源码标准提到了 C14 甚至 C17。编译器不支持编译就会在某个.cpp文件的第几百行突然中断报出来的话往往是error: auto changes meaning in C11或者干脆一串模板展开失败。第二个矛盾是系统库的年龄。CentOS 7 的 OpenSSL 停在 1.0.2k而现在的包管理站点普遍已经不支持这么老的 TLS 版本install.packages阶段就可能直接卡在下载上报SSL connect error或者证书校验失败。libgit2 也是同理CentOS 7 EPEL 里的版本是 0.26gert包需要 1.x装devtools的时候如果系统里有老版 libgit2gert会自作聪明地去链接它然后编译失败。第三个矛盾是内存。ArchR 的依赖里有一批重模板的 C 包单个编译单元一个.cpp文件在优化编译时峰值内存能吃到 2 到 3 GB。如果你习惯性地设置了MAKEFLAGS-j16再加上options(Ncpus 16)实际并发可能达到几十个编译进程16 GB 的机器几分钟就被 OOM killer 打成筛子症状是编译日志戛然而止末尾跟着一个Killed。搞清楚这三个矛盾后面的所有操作其实都是在解决它们。我在第一次装的时候没想明白这层直接照着网上某一篇 Ubuntu 的教程往下走结果在RcppArmadillo上卡了整整一个下午。提示装 ArchR 之前先执行free -h和df -h。内存低于 16 GB、可用磁盘低于 80 GB 的机器后面一定要降低并发并挂 swap否则失败率高得离谱。1.2 两条路线的取舍源码编译环境和 Conda 环境在 CentOS 上搞 ArchR实际操作中有两条路线可选选择不同后面踩的坑完全不一样。第一条是系统源码编译路线用 yum 补齐系统库从源码编译一个新版本的 R然后在那个 R 里用BiocManager加devtools装 ArchR。这条路的好处是环境干净、路径清晰、出了问题能顺着ldd一路查下去R 包和系统库的对应关系明确。坏处是准备工作长光是编译 R 就要二三十分钟工具链升级也得自己做。第二条是Conda 路线装一个 Miniconda建一个环境conda install -c conda-forge r-base4.3 r-devtools然后在里面装 ArchR。这条路的好处是省事conda-forge 提供了预编译好的 R 和一大批二进制包RcppArmadillo、data.table这些不用自己编安装时间能压缩到半小时以内。坏处是混装风险conda 的 R 用的是一套独立的 zlib、openssl、curl一旦某个包在装的时候走了系统库、另一个走了 conda 库就会出现运行时找不到符号的问题排查起来非常折磨人。我的建议是按机器角色来分。如果这台机器是团队共用的分析服务器长期要跑各种生信流程走源码编译路线一次搞好后面几年都省心。如果是临时借来的一台机器、或者只是想把某批数据跑完拿到结果走Conda 路线快进快出别在环境上耗时间。还有个折中方案值得一提用 conda 只装 R 本身和几个大头依赖r-rcpparmadillo、r-data.table、r-rhdf5剩下的 Bioconductor 包还是用BiocManager装。这样既避开了最耗时的编译又保住了 Bioconductor 生态的完整性。这种混法在实践里成功率不低前提是把 conda 环境的lib目录加到LD_LIBRARY_PATH里避免运行时找不到 conda 编译的动态库。1.3 开装前必须盘清楚的硬件与系统底账动手之前先把这台机器的情况摸清楚。跑几条命令几秒钟的事但能省下后面几个小时的瞎猜。cat /etc/redhat-release gcc --version | head -1 free -h df -h / /home /tmp nprocCentOS 系列的版本差异对 ArchR 安装的影响大致可以对照下面这张表系统版本默认 GCCC17 支持主要麻烦CentOS 74.8.5不支持必须升级 devtoolsetglibc 2.17 偏老OpenSSL 1.0.2CentOS 88.5支持已停止维护yum 源要改到归档地址CentOS Stream 88.5支持源地址需要重新指向EPEL 配置要跟上CentOS Stream 911.x支持编译器够新但默认仓库里的 R 版本偏老内存方面ArchR 官方的说法是 16 GB 起步但这个数字对应的是能跑起来。真要做完整的单细胞 ATAC 分析从 Arrow 文件读取、addDoubletScores、addIterativeLSI到addPeak2GeneLinks32 GB 是相对舒服的档位64 GB 可以做中等规模样本的整合分析。安装阶段的内存需求和运行阶段不一样安装阶段看重的是单次编译峰值乘以并发数这个后面细讲。磁盘方面R 本身加上全部依赖包编译过程产生的中间文件加上最终安装体积大概要 8 到 12 GB。ArchR 的基因组注释包hg38 一套下载下来 1.5 GB 左右解压后更大。原始 fragment 文件和生成的 Arrow 文件才是大头一个标准的 10x 单细胞 ATAC 样本Arrow 文件动辄几个 GB。所以预留 100 GB 是比较稳妥的。特别提醒/tmp从源码编译 R 包时中间产物默认落在/tmp如果你的/tmp是挂载的 tmpfs 并且只有 2 GB编译到一半就会报No space left on device而这个报错往往被埋在日志中间很不好找。2. 系统层准备编译器、系统库与磁盘2.1 CentOS 7 的老 GCC 必须先换掉如果你在 CentOS 7 上第一条命令不是装包是换编译器。最省事的做法是用 SCLSoftware Collections提供的 devtoolset不需要动系统自带的 GCC装完用scl enable临时切换互不干扰。yum install -y centos-release-scl yum install -y devtoolset-9-gcc devtoolset-9-gcc-c devtoolset-9-gcc-gfortrandevtoolset-9 对应 GCC 9.3对 C17 的支持已经够用而且比 devtoolset-11 的兼容性风险小。装完之后让它在当前 shell 生效scl enable devtoolset-9 bash gcc --version | head -1如果需要长期生效可以写进 profileecho source /opt/rh/devtoolset-9/enable /etc/profile注意scl enable只影响当前 shell 及其子进程。如果你用nohup或者screen挂后台任务必须先scl enable再启动否则后台进程用的还是系统老 GCC编译结果会非常诡异。我吃过这个亏同一台机器上前后两次装同一个包一次成功一次失败查了半天才发现是启动方式不同。gfortran这一项千万别漏。ArchR 的依赖链里TFBSTools依赖DirichletMultinomial这个包的源码是 Fortran 的没有 gfortran 会在 configure 阶段直接报Fortran compiler not found。很多人补了gcc和gcc-c就以为齐了结果卡在这里报错信息又藏在00check.log里不好找。CentOS 8 和 Stream 系列自带的 GCC 8.5 或 11.x 已经支持 C17这一节可以跳过。不过还是建议执行一次gcc --version确认因为有些容器的镜像被裁剪过只留了gcc没留gg缺失时R CMD INSTALL会报C compiler not found同样是 configure 阶段就挂。2.2 一份可以直接抄的系统依赖安装清单下面这份依赖清单是我在几台 CentOS 7 和 Stream 9 上反复验证过的涵盖 R 编译、常见 R 包编译、ArchR 依赖链需要的全部系统库yum install -y epel-release yum install -y \ gcc gcc-c gcc-gfortran make cmake git wget bison flex \ zlib-devel bzip2-devel xz-devel pcre-devel pcre2-devel \ libcurl-devel openssl-devel libxml2-devel \ libpng-devel libjpeg-turbo-devel libtiff-devel \ freetype-devel fontconfig-devel harfbuzz-devel fribidi-devel \ cairo-devel readline-devel \ openblas-devel lapack-devel \ libXt-devel逐项说一下这些包为什么在清单里。zlib-devel、bzip2-devel、xz-devel是 R 自身编译时用来支持压缩格式的缺了 R 就会以最小功能编译出来后面Rhdf5lib依赖压缩库时会连锁失败。libcurl-devel是curl包和httr系列的底层依赖ArchR 安装时会从网上拉数据缺了之后要么装不上要么装上了但所有网络函数都报错。libxml2-devel对应XML包Bioconductor里一堆包间接依赖它。libpng、libjpeg、libtiff、freetype、fontconfig、cairo这一组是绘图相关ggplot2生态和ragg需要缺了不会导致安装失败但会在画图时报no png support。openblas-devel和lapack-devel是矩阵运算的底层对 ArchR 尤其重要后面单独讲。readline-devel让 R 交互式终端支持方向键和历史记录没有也不影响运行但用起来很难受。装完之后建议做个简单验证确认关键库的版本rpm -q zlib-devel libcurl-devel openssl-devel openblas-devel注意epel-release必须在其他包之前装否则libgit2-devel、hdf5-devel这些只存在于 EPEL 的包会报No package available。有些精简版镜像连epel-release都装在非标准位置装完记得yum repolist确认 epel 源已经生效。2.3 三个最容易埋雷的系统库HDF5、libgit2、OpenSSL清单之外有三个库需要单独拿出来说因为它们的处理方式反直觉多数情况下不该装。先说 HDF5。ArchR 的 Arrow 文件实际上就是 HDF5 格式读写靠rhdf5而rhdf5的底层是Rhdf5lib这个包自带一份 HDF5 源码安装时会自己编译跟系统里的 HDF5 完全无关。如果你先yum install hdf5-devel装了系统版本CentOS 7 上是 1.8.x再装Rhdf5lib有时会出现运行期符号冲突症状是library(rhdf5)报HDF5 library version mismatched error。我遇到过一次代码里任何h5read都报错最后用yum remove hdf5-devel卸掉系统库才恢复正常。所以结论是不要装系统 HDF5让Rhdf5lib自己管。再说 libgit2。devtools依赖gertgert依赖 libgit2。CentOS 7 EPEL 里的libgit2-devel是 0.26而新版gert要求 1.x。如果系统里有老版本gert的 configure 脚本会检测到并尝试链接然后编译失败。正确做法是不装libgit2-devel让gert走自带的 bundled 版本需要cmake和openssl-devel这两个清单里已经有了。如果你已经装了yum remove libgit2-devel然后重装gert。最后说 OpenSSL。CentOS 7 的 1.0.2k 在访问现代软件源时会遇到 TLS 协商失败典型报错是SSL connect error、Peer certificate cannot be authenticated with given CA certificates。处理方式有几种一是尽量用国内镜像源多数镜像站还保留了 TLS 1.0/1.1 的兼容二是装openssl11和openssl11-devel然后在编译某些包时通过环境变量指向它三是干脆放弃系统 R走 Conda 路线Conda 自带一套较新的 OpenSSL绕开了这个问题。我倾向于第一种加第三种组合能省事就省事。2.4 swap 与临时目录编译期内存的真正兜底前面提过ArchR 依赖链里有几个包的编译峰值内存很高。RcppArmadillo的arma模板在-O2优化下单个文件编译能吃到 2 GB 以上motifmatchr链接阶段的峰值更高uwot里的RcppAnnoy也不省油。如果并发开得多实际占用是峰值的倍数。我的经验值是16 GB 内存的机器编译 ArchR 依赖时并发不要超过 332 GB 可以开到 664 GB 以上随便开。这个数字比多数人想象的保守但 OOM 一次重来的代价远高于多等二十分钟。光靠降并发还不够swap 是必须挂的兜底。CentOS 默认不启用 swap 分区的情况很常见尤其是云主机手动加一个fallocate -l 32G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile echo /swapfile swap swap defaults 0 0 /etc/fstab free -h32 GB 的 swapfile 在 SSD 上创建大概十几秒。虽然 swap 的速度比内存差一个数量级但编译这种场景下进程偶尔溢出到 swap 只是慢一点不会直接被杀掉。相比之下没有 swap 时 OOM killer 是直接SIGKILL编译日志断在一个莫名其妙的位置你还得从头再来。临时目录的问题同样值得提前处理。R 包编译时R CMD INSTALL会在TMPDIR指向的目录下解压源码、存放.o中间文件。如果/tmp空间不足或者被挂成了小容量 tmpfs编译就会中途失败。做法是显式指定一个大盘目录mkdir -p /data/tmp echo export TMPDIR/data/tmp ~/.bashrc source ~/.bashrc顺便把ulimit -s放开一点某些深度递归的模板代码在默认 8 MB 栈上会栈溢出echo ulimit -s unlimited ~/.bashrc这两条看起来不起眼但在装RcppArmadillo这类包时能实实在在减少一类很难定位的失败。3. R 本身的安装与关键参数调优3.1 从源码编 R 的完整命令与参数解释CentOS 仓库里的 R 版本普遍偏老。CentOS 7 的 EPEL 提供的是 R 3.5 或 3.6CentOS Stream 9 的r包大概是 4.1 左右。而 ArchR 要求 R 至少 4.1配合的 Bioconductor 版本也要对得上Bioconductor 3.16 对应 R 4.23.17 对应 R 4.33.18 对应 R 4.33.19 对应 R 4.4。版本对不上BiocManager::install第一步就会拒绝执行报Bioconductor version is too old for this R。所以要么装 conda 的 R要么从源码编。源码编的完整流程如下以 R 4.3.2 为例cd /opt wget https://cran.r-project.org/src/base/R-4/R-4.3.2.tar.gz tar -xzf R-4.3.2.tar.gz cd R-4.3.2 ./configure \ --prefix/opt/R/4.3.2 \ --enable-R-shlib \ --enable-memory-profiling \ --with-blas-lopenblas \ --with-lapack \ --with-xno \ --with-cairo \ --with-libpng \ --with-jpeglib \ --with-libtiff \ --with-readline make -j4 make install参数逐条解释。--prefix指定安装位置建议放在/opt/R/版本号这种带版本号的路径下将来装第二个版本的 R 时互不干扰切换只需要改PATH。--enable-R-shlib生成libR.so这是很多需要嵌入 R 的工具包括某些 IDE 和rpy2的前提虽然 ArchR 本身不需要但顺手开了省事。--with-blas-lopenblas是关键项见下一节。--with-xno关掉 X11 支持服务器上没有图形界面开了只会增加编译依赖和失败概率。--with-cairo配合后面的几个图像库保证png()、jpeg()、tiff()这些设备可用ArchR 出图会用到。--with-readline让交互式终端好用。编译本身在 8 核机器上大概 8 到 12 分钟make -j4的并发数根据核数调整但别开到-j$(nproc)R 的某些编译单元内存占用也不小。装完之后配置环境变量echo export R_HOME/opt/R/4.3.2/lib/R /etc/profile echo export PATH/opt/R/4.3.2/bin:$PATH /etc/profile source /etc/profile R --version注意/opt/R/4.3.2/lib/R这个路径在不同 configure 参数下可能不同装完先find /opt/R -name R_HOME确认一下。有些 R 包安装时会读R_HOME环境变量指错了会在R CMD INSTALL时报cannot find R home directory。如果机器上已经有一个系统 R装新版本后要注意PATH的优先级。which R确认当前生效的是哪一个Rscript -e R.version.string再三确认。我曾因为PATH顺序问题装了半天发现一直在用系统的 R 3.5所有包都装到了错误的 library 路径下。3.2 BLAS/LAPACK 的选择对 ArchR 的影响这一节值得单独讲因为它直接影响 ArchR 跑起来之后的速度而且是安装阶段一次性决定、后面很难改的。R 默认自带的 BLAS 是参考实现reference BLAS单线程、无优化矩阵乘法的性能大概只有 OpenBLAS 多线程版本的十分之一到五分之一。ArchR 的分析流程里addIterativeLSI要做大规模稀疏矩阵的 SVDaddClusters涉及距离矩阵计算getCoAccessibility要算相关性矩阵这些操作全都是 BLAS 的重度用户。用参考 BLAS 跑一个中等规模的样本LSI 那一步可能要跑四十分钟换成 OpenBLAS 多线程能压到十分钟以内。所以--with-blas-lopenblas这个参数一定要加。装完后验证R CMD config BLAS_LIBS输出应该包含-lopenblas。再做个性能对照建一个 2000×2000 的随机矩阵做乘法看耗时n - 2000 a - matrix(rnorm(n*n), n, n) system.time(b - a %*% a)在 8 核机器上OpenBLAS 多线程版本大约 0.5 到 1 秒参考 BLAS 要 6 到 10 秒。差一个数量级。线程数可以通过环境变量控制export OPENBLAS_NUM_THREADS8这里有个容易踩的坑ArchR 本身是多线程的addArchRThreads()OpenBLAS 也是多线程的。如果两边都开满实际线程数会相乘超订之后性能反而下降甚至因为内存争抢导致进程被杀。我的做法是把 OpenBLAS 的线程数限制在物理核数的一半左右给 ArchR 的并行留出空间。比如 16 核机器OPENBLAS_NUM_THREADS8addArchRThreads(threads 8)两边加起来基本打满但不至于打架。提示OPENBLAS_NUM_THREADS这个变量在提交作业的脚本里也要设一遍。很多人只在交互 shell 里设了写成qsub或sbatch脚本提交之后作业进程读不到这个变量又退回默认的全核模式跑起来比预期慢或者直接把节点拖垮。3.3 .Rprofile 与 .R/Makevars 的配置模板R 装好之后先别急着装包。把用户级的配置文件写好能避免后面一大批重复的、烦人的问题。~/.Rprofile里放这几行options(repos c(CRAN https://cloud.r-project.org)) options(Ncpus 4) options(timeout 600) options(warn 1) Sys.setenv(MAKEFLAGS -j2)repos指定 CRAN 源如果你的网络访问官方源慢把地址换成常用的国内镜像站即可格式一样。Ncpus控制install.packages同时安装多个包的并发数。timeout默认是 60 秒装大包比如BSgenome.Hsapiens.UCSC.hg38有几百 MB时经常超时调到 600 秒很必要。MAKEFLAGS控制单个包内部make的并发。这里有个关键点要说清楚Ncpus和MAKEFLAGS的并发是相乘的。如果Ncpus 8且MAKEFLAGS -j8理论上最多会有 64 个编译进程同时跑内存瞬间打满。我建议的做法是Ncpus设小一点4 左右让多个包并行MAKEFLAGS设成 2控制单个包内部的并发。这样总的并发峰值大约 816 GB 内存能扛住。~/.R/Makevars里放编译器和优化选项CC gcc CXX g CXX11 g -stdgnu11 CXX14 g -stdgnu14 CXX17 g -stdgnu17 CXXFLAGS -O2 -fno-var-tracking -fno-var-tracking-assignments CFLAGS -O2 -fno-var-tracking -fno-var-tracking-assignments FFLAGS -O2 FCFLAGS -O2CXX11、CXX14、CXX17这几行是给那些在DESCRIPTION里声明了SystemRequirements: C17的包用的R 会自动调用对应的编译器命令。如果你的 devtoolset 是 9 及以上这里的g就是新版如果没切 devtoolset这几行等于白写编译出来的还是 4.8.5 的标准报错照旧。-fno-var-tracking这两个选项在 CentOS 7 上尤其有用。老版本 GCC 在-g调试信息下编译大模板代码时变量跟踪会吃掉大量内存和时间关掉之后编译内存峰值能降 20% 左右编译速度也有提升。4. ArchR 及依赖包的实际安装过程4.1 依赖包的安装顺序为什么重要很多人装 ArchR 的方式是直接一句devtools::install_github(...)然后看着它一个个往下拉。这种方式在 Ubuntu 上偶尔能成在 CentOS 上成功率很低原因在于 ArchR 的DESCRIPTION里列出的依赖不一定覆盖完整有些是运行期才用到的有些是间接依赖但需要特定版本。直接装主体往往在某个间接依赖上崩掉前面的编译成果白费。我的做法是分层安装按依赖的深度分三批走。第一批是基础工具链和底层包这一批装完后面的很多问题会自动消失install.packages(c(devtools, BiocManager, remotes, data.table, Matrix))第二批是 Bioconductor 的框架包和核心数据结构包BiocManager::install(version 3.18) BiocManager::install(c( S4Vectors, IRanges, GenomicRanges, GenomeInfoDb, Biostrings, BSgenome, Rsamtools, GenomicAlignments, BiocParallel, rtracklayer, SummarizedExperiment ), update FALSE, ask FALSE)第三批是 ArchR 特有的分析依赖这批是重灾区BiocManager::install(c( rhdf5, Rhdf5lib, Rcpp, RcppArmadillo, chromVAR, motifmatchr, TFBSTools, Seurat, SeuratObject, hexbin, smooth ), update FALSE, ask FALSE)分层的价值在于失败范围可控。第二批挂了你只需要重跑那一条命令不用从头再来。而且每一层装完可以做一次library()验证确认这个包真的能加载而不是装上了但动态库链接有问题。library()验证这一步很多人跳过结果装完 ArchR 之后在library(ArchR)时报一个unable to load shared object回头一个个查哪个包出了问题。update FALSE这个参数也很关键。默认情况下 BiocManager 会检查所有依赖的版本遇到已安装但版本偏旧的包就想升级。升级意味着重新编译一处升级可能引发连锁反应一晚上都装不完。锁定为不升级用现有版本多数情况下 ArchR 能正常工作。4.2 主体安装命令与分阶段验证依赖装完之后装 ArchR 主体devtools::install_github( GreenleafLab/ArchR, ref master, repos BiocManager::repositories() )ref master指定主分支。ArchR 的迭代节奏在这两年放缓了不少master 分支长期维持在 1.0.x 这条线上相对成熟。如果你需要某个特定版本可以改成具体的 tag。repos BiocManager::repositories()这一句的作用是把 Bioconductor 的仓库地址一并传给install_github让它解析依赖时能同时看到 CRAN 和 Bioconductor。少了这一句遇到 Bioconductor 包会报package xxx is not available。安装过程可能持续二十分钟到一个小时取决于有多少包需要现场编译。日志会一直往下刷中间夹杂大量警告不用太在意。真正需要关注的是最后几十行如果有ERROR或者non-zero exit status那就是真的失败了。装完之后的验证分三步走一步比一步深# 第一步能不能加载 library(ArchR) # 第二步线程设置能不能生效 addArchRThreads(threads 4) # 第三步基因组对象能不能构建 addArchRGenome(hg38)第一步失败多半是某个动态库没找到用ldd查具体是哪个包先library(那个包)看报错报错信息里的.so路径拿去ldd一下就能看出缺了哪个系统库。第二步失败很罕见基本不会。第三步是真正的考验。addArchRGenome(hg38)会从网上下载 hg38 的全套注释文件包括BSgenome、TxDb、org.Hs.eg.db打包成的 ArchR 专用格式体积在 1.5 GB 上下解压后写入当前工作目录下的一个子目录。这一步会同时检验网络、磁盘和几个注释包是否装好是装完能跑的最终判定。注意addArchRGenome的下载缓存落在当前工作目录下不是固定的全局路径。这意味着你在不同目录下跑addArchRGenome(hg38)会重复下载多份。我建议在固定的项目根目录下先跑一次之后都setwd()过去或者用getArchRGenome()查一下当前的路径设置。磁盘紧张的时候重复下载几份注释能把盘塞满。4.3 基因组注释包与离线机器的搬运方法有些分析机器是完全隔离的没有外网。这种情况下addArchRGenome会卡住或者报错需要手动搬运。第一步是在一台能上网的机器上把注释文件准备好。最直接的方式是在能上网的机器上跑一次addArchRGenome(hg38)然后把生成的那个目录整个打包tar -czf archr_hg38_annotations.tar.gz ArchR/第二步是搬到隔离机器上解压到与源机器相同的相对路径下。ArchR 查找注释时依赖相对路径和工作目录挪位置容易找不到。第三步是验证library(ArchR) addArchRThreads(threads 4) genome - getArchRGenome() hg38 - createGenomeAnnotation(genome genome)如果第二节的txdb部分报could not find a TxDb说明注释包没装好。可以在能上网的机器上把TxDb.Hsapiens.UCSC.hg38.knownGene、org.Hs.eg.db、BSgenome.Hsapiens.UCSC.hg38这三个 R 包单独下载下来用install.packages(/path/to/pkg.tar.gz, repos NULL)离线安装。这三个包加起来大概 800 MB比下载整个注释集省事。还有个小细节org.Hs.eg.db这类注释包在不同 Bioconductor 版本之间不兼容一定要保证离线包和在线机器的 Bioconductor 版本一致否则装上了也可能读不出数据。用BiocManager::version()两边对一下版本号必须完全一致。5. 踩坑实录典型报错与排查路径5.1 编译期被 Killed内存与并行的平衡症状很典型终端里日志刷到一半突然停住最后一行是某个.cpp文件名后面紧跟着Killed或者gcc: internal compiler error: Killed (program cc1plus)。没有明确的错误信息没有行号就这么没了。新手容易误以为是代码有 bug反复重试结果每次都死在同一个位置。这个就是 OOM killer 干的。系统内存不够内核挑了个占内存最大的进程直接杀掉杀的就是cc1plusGCC 的 C 前端。验证方法是看系统日志dmesg | grep -i killed process输出里能看到被杀进程的 PID 和占用的内存量。如果看到cc1plus吃了 3 GB 以上被杀那就确诊了。解决思路有三条我通常三条一起上一是降并发。把MAKEFLAGS从-j8降到-j1或-j2options(Ncpus 4)降到2。这样峰值内存直接降一个数量级代价是时间变长。二是加 swap。前面 2.4 节讲过32 GB 的 swapfile 能兜住大部分溢出场景。有 swap 之后即使并发开得稍微大一点进程也只是变慢而不会被杀。三是单独处理重包。ArchR 依赖里最耗内存的几个包是RcppArmadillo、TFBSTools、motifmatchr、uwot、nabor。这几个可以单独用最低并发装MAKEFLAGS-j1 R CMD INSTALL --no-test-load RcppArmadillo_x.y.z.tar.gz--no-test-load跳过安装后的加载测试能省一点内存和时间。装完这几个大头剩下的包再用正常并发跑整体效率反而更高。实测下来16 GB 内存的机器按上面这套组合拳装 ArchR 全套依赖大约需要 50 分钟到 1 小时 20 分钟中途不会被 kill。如果只降并发不加 swap也基本能过但遇到TFBSTools这种吃内存的包还是有可能挂加 swap 更保险。5.2 动态库找不到与版本冲突装是装上了一library()就报unable to load shared object ... undefined symbol: xxx这类问题的排查路径和编译期错误完全不同得从动态链接的角度看。第一步定位是哪个包library(出问题的包名)报错信息里会包含.so文件的完整路径记下来。第二步查这个.so的依赖ldd /path/to/包名.so | grep not foundnot found的那几行就是缺的库。常见的有libcurl.so.4、libssl.so.1.1、libhdf5.so.xxx。缺哪个装哪个或者确认路径是否在LD_LIBRARY_PATH里。第三步如果所有库都能找到但报的是undefined symbol那就是版本冲突找到的库版本太老没有那个符号。用nm查一下符号在不在nm -D /path/to/libxxx.so | grep 符号名或者用strings看版本号。这类问题在混装 Conda 和系统库的环境里特别常见因为LD_LIBRARY_PATH里 conda 的路径和系统路径混在一起加载顺序不确定。ArchR 生态里最容易出的两个具体冲突其一HDF5 冲突。前面提过系统装了hdf5-devel会和Rhdf5lib打架。症状是library(rhdf5)报HDF5 library version mismatched error。解决就是yum remove hdf5-devel然后重新装Rhdf5libinstall.packages(BiocManager) BiocManager::install(Rhdf5lib, force TRUE)其二OpenSSL 冲突。CentOS 7 的 1.0.2 和某些包要求的 1.1.1 不兼容。curl包能装上但网络请求全失败报SSL connect error。这种场景下最省事的办法是换一个不需要新版 TLS 的源或者装openssl11后在编译curl时指定export PKG_CONFIG_PATH/usr/lib64/openssl11/pkgconfig:$PKG_CONFIG_PATH R CMD INSTALL --configure-varsINCLUDE_DIR/usr/include/openssl11 LIB_DIR/usr/lib64/openssl11 curl_x.y.z.tar.gz这套配置有点绕如果只是想让 ArchR 装上、不需要从网上下数据可以先忽略这个问题装完之后导入本地准备好的注释文件即可。5.3 常见报错速查表把这几台机器上遇到过的报错整理成一张表遇到类似情况可以先对照着看。报错片段根因处理方式error: auto changes meaning in C11GCC 太老不支持 C11 语义切换 devtoolset-9 及以上error: unrecognized command line option -stdgnu17GCC 4.x 不认识 C17 参数同上必须换编译器Fortran compiler not found缺 gfortranyum install gcc-gfortranC compiler not found缺 gyum install gcc-cKilled/internal compiler error: Killed编译内存溢出降并发、加 swapNo space left on device/tmp或工作盘满了设TMPDIR到大盘cannot find -lcurl缺 libcurl-develyum install libcurl-develcannot find -lxml2缺 libxml2-develyum install libxml2-devellibgit2 version is too old系统 libgit2 版本低卸掉libgit2-devel让 gert 自带编译HDF5 library version mismatched系统 HDF5 与 Rhdf5lib 冲突卸掉系统hdf5-devel重装 Rhdf5libSSL connect error老 OpenSSL 与站点 TLS 不匹配换源或升级 openssl11Bioconductor version ... too oldR 版本与 Bioc 版本对不上升级 R 或指定匹配的 Bioc 版本package xxx is not available仓库源没配全BiocManager::repositories()传参there is no package called xxx依赖没装全就装主体按分层顺序补装had non-zero exit status编译失败需向上翻日志找根因用install.packages(..., verboseTRUE)定位RcppArmadillo 编译超时timeout太短options(timeout 1200)表格里最后一条值得多说一句。had non-zero exit status这个提示本身不包含任何有效信息它只告诉你某个包编译失败了。真正的错误在它上面几十行的地方。用verbose TRUE重跑或者把安装日志重定向到文件再搜ERRORinstall.packages(出问题的包