在x86架构的MacBook上拿IntelliJ IDEA去编译Hadoop 2.6.0-cdh5.14.0这个组合听起来就像是给十年前的项目做考古修复。但只要你的公司里还跑着CDH 5.14的集群或者你接手了一个基于CDH源码做二次开发的模块这事儿就绕不开。我为了在本地调试一个HDFS的定制功能花了整整一个周末把这条编译链路彻底走通过程中踩掉的坑几乎覆盖了所有能在macOS上遇到的经典问题。先说结论CDH 5.14的Hadoop虽然内核是Apache Hadoop 2.6.0但它的源码结构、依赖坐标、构建脚本和原生库编译方式都做了不少改动直接拿Apache版本的教程来套十有八九会在中途报错。这篇内容就是记录我在x86 macOSIntel芯片10.14/10.15带Xcode Command Line Tools上用IDEA编译这套源码的全过程顺便把那些报错信息一条条对出来讲清楚。1. CDH 5.14的Hadoop 2.6源码为什么值得在macOS上费力1.1 它和Apache Hadoop 2.6.0的差异CDH是Cloudera发行版的代号5.14.x对应的是2017年前后的一批稳定版本当中的Hadoop主版本就是2.6.0-cdh5.14.0。很多人以为Cloudera只是换个壳实际不是。CDH在Apache Hadoop之上打了大量patch包括HDFS的Sentry集成、HA故障切换的细化、配额和审计日志的改动以及一堆bugfix。这些patch不是注释级别的修改而是直接改变了源码树的结构。你在IDEA里打开CDH仓库会发现它比Apache版本多出不少子模块比如hadoop-sentry、hadoop-fairscheduler-ext甚至在hadoop-hdfs模块里也多了一些Cloudera自己加的类。如果你直接拿Apache Hadoop 2.6的源码包来编译跑出来的东西和公司CDH集群上跑的二进制不一致二开出来的代码很可能在线上行为完全不同。所以做CDH体系的二次开发编译CDH自己的源码是第一步不是可选步骤。1.2 哪些场景下需要本地编译我遇到的需求很典型公司那套CDH 5.14集群上有个HDFS的NameNode内存监控逻辑是定制过的代码在运维团队手里但文档基本等于没有。我需要把整套源码拉下来在本地跑一个伪分布式的NameNode和DataNode打断点看路径才能搞清楚它到底改了哪些行为。这种场景下本地编译有几个硬性要求编译结果要和线上CDH版本一致不能用Apache原版代替要能在IDE里直接启动HDFS进程而不是打包完丢到服务器上黑盒运行需要把native library编出来否则部分JNI调用会报warning甚至某些加密代码路径跑不起来如果你也是冲着这些目标来的那这篇笔记应该能帮你省掉不少时间。2. 环境准备先对付JDK、Maven和protobuf三条拦路虎2.1 JDK只能选8原因在这里CDH 5.14的Hadoop 2.6时代官方推荐的是JDK 7和JDK 8但我建议直接装JDK 8。原因有两个第一JDK 7在Intel Mac上已经很难找到合适的macOS版本且Oracle早就停止支持没必要给自己找麻烦。第二JDK 8是这套源码的实测安全区间编译时不会碰到模块化问题。如果你用JDK 9或更高版本会立刻在编译期撞上javax.annotation和javax.xml.bind找不到的问题因为JDK 9模块化之后这些包不再默认包含在classpath里了。Hadoop 2.6的代码里不少类依赖它们没有添加--add-modules java.xml.bind的旧版构建逻辑基本过不去。我的建议是安装一个干净的JDK 8比如jdk1.8.0_291.jdk然后把JAVA_HOME明确指过去export JAVA_HOME/Library/Java/JavaVirtualMachines/jdk1.8.0_291.jdk/Contents/Home export PATH$JAVA_HOME/bin:$PATH注意x86 macOS的Intel Mac不需要额外处理Rosetta但如果你用的是Apple Silicon Mac还得给这整套工具链加一层x86转译那就更折腾了。所以标题里强调x86架构是有实际意义的Intel Mac至少不用处理arch匹配问题。2.2 Maven版本不要贪心3.3.9最稳Hadoop 2.6的pom结构是在Maven 3.2/3.3时代写的。我一开始用的是Maven 3.8.6结果一堆老插件直接翻车比如maven-remote-resources-plugin报执行失败maven-antrun-plugin的脚本在解析时也出现了古怪的格式错乱。后来我换成了Maven 3.3.9整个编译过程就顺畅多了。如果是新装的机器直接用Homebrew安装指定版本brew install maven3.3装完之后确认版本mvn -version只要输出里能看到Maven 3.3.9和正确的Java version: 1.8就可以进入下一步。别小看这个版本对齐我在这个环节浪费了一个下午最后发现就是Maven太新惹的祸。2.3 protobuf必须卡在2.5.0这是整个编译过程中最不能妥协的一个依赖。Hadoop 2.6的RPC协议定义用的protobuf是2.5.0HDFS的NameNodeRpcServer和DataNode之间的通信协议由一系列.proto文件生成Java代码。如果protoc编译器版本不是2.5.0生成的代码会在运行时出现协议不匹配的异常。CDH源码里的hadoop-common目录下一堆.proto文件的语法是proto2写法protobuf 2.5.0能正常解析。你要是装个3.x的protoc虽然大部分proto2语法它也兼容但某些生成类的签名和Hadoop源码里写死的接口不一致编译期就会报错。我安装protobuf 2.5.0的方式是下载官方源码包在本地编译安装tar -zxvf protobuf-2.5.0.tar.gz cd protobuf-2.5.0 ./configure --prefix/usr/local/protobuf-2.5.0 make -j4 make install编译完后把/usr/local/protobuf-2.5.0/bin放到PATH的最前面再用protoc --version确认输出为libprotoc 2.5.0。在比较新的macOS系统上protobuf 2.5.0的C代码可能会因为编译器太新而出一些兼容性报错我当时的处理方式是直接用CC/usr/bin/clang、CXX/usr/bin/clang来configure注意不要让它默认找Homebrew里的更新版GCC老版本源码对新编译器反而更敏感。2.4 其他系统级依赖除了JDK、Maven、protobufnative部分编译还需要cmake和一堆构建工具。我在x86 macOS上预先用Homebrew装好了这些brew install cmake autoconf automake libtool snappy brew install openssl zlib bzip2openssl尤其重要。如果你编译时开启了native库的OpenSSL支持却找不到头文件会直接报openssl/evp.h不存在。Homebrew安装的openssl是/usr/local/opt/opensslHadoop的configure脚本不一定会自动找到这个路径后面如果有需要我会讲怎么利用环境变量把这个路径传进去。到这里环境准备算是告一段落。我建议你先把每个依赖的版本都确认一遍然后再启动Maven构建。磨刀不误砍柴工在这个项目上尤其适用。3. Maven构建我的关键参数选择与执行顺序3.1 官方打包命令逐一拆解CDH源码根目录下的README会告诉你用Maven构建但给的命令很笼统。实战下来我用的命令是这样的mvn clean install -DskipTests \ -Dmaven.javadoc.skiptrue \ -Dfindbugs.skiptrue \ -Dtarfalse \ -Pdist,native逐个参数看它做了什么-DskipTests跳过测试执行但保留测试代码的编译。这一步很重要因为Hadoop的测试用例量很大很多测试需要启动本地进程在macOS上经常因为端口占用或系统权限失败。-Dmaven.javadoc.skiptrue跳过javadoc生成。这个纯粹是为了省时间一个模块的javadoc就要跑好几分钟。-Dfindbugs.skiptrue跳过FindBugs静态检查。CDH的老pom里findbugs插件版本比较旧在JDK 8的新字节码格式下经常误报而且跑起来极慢。-Dtarfalse不生成tar.gz发行包。这个参数能让构建跳过不少打包后处理缩短时间。-Pdist,native激活两个profile。dist会生成一个完整可运行的Hadoop发行目录native会触发JNI和native代码库的编译。如果你的目的只是把Java源码编译好然后导入IDEA其实可以暂时不加-Pnative后面单独编native库。我第一次就直接上了全量native结果一堆依赖问题全涌上来反而不利于定位。所以我的建议是分两步走第一步先纯Java编译mvn install -DskipTests -Dmaven.javadoc.skiptrue -Dfindbugs.skiptrue -Dtarfalse这一步能通过说明Java层面的所有源码、资源依赖都没问题。第二步再考虑native。3.2 子模块依赖顺序问题CDH 5.14的源码是一个超多模块的Maven聚合工程模块依赖呈现明显的分层。你从根目录执行mvn installMaven会计算依赖拓朴并依次构建但有些时候如果根pom的仓库配置不全某个中间子模块会拉不到依赖然后一直失败。我在构建过程中就遇到过hadoop-project-dist模块报错问题不是代码而是它依赖的hadoop-client和hadoop-minicluster中的某些CDH版jar在Maven中央仓库根本没有只有Cloudera的仓库里有。如果你的Maven日志里出现Could not find artifact org.apache.hadoop:hadoop-hdfs:jar:2.6.0-cdh5.14.0之类的错误多半就是仓库列表不够。解决方法是把Cloudera仓库加进settings.xml的profile里profile idcloudera/id repositories repository idcloudera-repos/id urlhttps://repository.cloudera.com/artifactory/cloudera-repos//url snapshots enabledfalse/enabled /snapshots /repository /repositories /profile然后在activeProfiles里激活它。这样Maven在解析依赖时中央仓库找不到的CDH专属构件就会自动去Cloudera仓库拉取。3.3 首次构建的耗时和内存控制Hadoop这种规模的聚合工程首次构建会下载几百个jar加上Java源码编译整体耗时在30到60分钟之间具体看机器性能。x86 Mac上我实测大概是40分钟出头。如果中途某个子模块编译失败修改后重新执行mvn install时由于前面的模块已经安装了第二次的速度会快不少。另外要特别注意Maven JVM内存。Hadoop编译时会启动多个插件进程内存不足会出现java.lang.OutOfMemoryError: PermGen space。虽然JDK 8已经没有PermGen但部分老插件还是会申请较大的堆内存。我习惯了在编译前设置export MAVEN_OPTS-Xmx4096m -XX:MaxPermSize512m这个设置对后面导入IDEA也有帮助IDEA里的Maven importer同样会用到这类内存参数。构建成功以后你会看到一堆BUILD SUCCESS尤其是最后几个核心子模块的构建结果这就说明命令行层面的编译已经打通了。接下来才轮到IDEA出场。4. 从命令行到IntelliJ IDEA导入与运行配置4.1 导入前的仓库预热很多人喜欢把源码直接拖进IDEA让IDEA自己去解析Maven然后卡在indexing和依赖下载上半天。我试过CDH这个工程模块实在是多IDEA的首次导入会扫描所有pom并建立索引不预热的话体验很差。更顺滑的做法是先用命令行执行一次完整的mvn install跳过测试即可把本地Maven仓库填满。这样IDEA导入时所有依赖都能从本地仓库直接读取解析速度会快很多也基本不会出现Cannot resolve symbol的红字。如果你遇到IDEA里的Maven窗口显示某些dependency还是红的点一下Reload All Maven Projects然后检查IDEA使用的settings.xml路径是否和命令行一致。这一步很关键IDEA默认有自己的一套User settings路径如果它和命令行用的不是同一个就会觉得依赖是乱的。4.2 配置Project SDK和Maven Runner在IDEA的File - Project Structure - Project里把Project SDK设为1.8Language Level也设为8。然后进入Settings - Build, Execution, Deployment - Build Tools - MavenMaven home path指向Maven 3.3.9的安装目录User settings file指向你配置了Cloudera仓库的settings.xmlLocal repository指向命令行使用的本地仓库这些配置对齐以后Maven窗口里的子模块列表会清晰很多。注意导入的时候IDEA可能会问你是否信任这个Maven project选择信任否则某些插件执行会被拦截。这里还有个容易忽略的地方IDEA内置的编译器和Maven编译器是两个独立系统。如果你直接在IDEA的工具栏点Build它用的可能是IDEA自己的编译器报错信息经常和Maven构建不一样。所以我个人的习惯是先用Maven窗口执行clean和install确认源码本身没问题然后再用IDEA的Build来增量编译做代码跳转和调试。4.3 调整IDEA的内存和索引设置CDH 5.14工程包含的子模块数量很多再加上自带的三方依赖IDEA首次打开时索引任务会很重。x86 Mac上如果内存只有8G建议在Help - Change Memory Settings里把IDEA的堆内存调到至少2G否则卡到键盘冒烟。导入完成后你可以试着搜索一个核心类比如NameNode如果能正常跳转到hadoop-hdfs模块的源码说明整个工程的索引已经建立成功。如果跳转失败可能是这个模块没有被IDEA正确识别为源码目录右键对应根目录在Mark Directory as里选择Sources Root。这些准备工作做完以后IDEA里的代码浏览和搜索就已经可用了。但真正要跑起HDFS进程还需要额外的运行时配置我放到第6章再讲。5. 遍历macOS特有坑从glibtoolize到protoc版本5.1 glibtoolize和libtoolize的软链问题这套源码的native部分在macOS上编译时第一个经典报错来自autotools。CDH的configure.ac脚本会优先找libtoolize命令但Linux发行版上的GNU libtool提供的是这个名字macOS上Homebrew安装的libtool提供的是glibtoolize和glibtool因为系统里还有一个Apple版本的libtool用来做Mach-O库管理的两者冲突了。于是configure阶段很容易出现这样的错误checking for libtoolize... no checking for glibtoolize... glibtoolize然后后续的Makefile生成过程会因为libtool宏问题直接失败。解决方式很直接做个软链brew install libtool ln -s /usr/local/bin/glibtoolize /usr/local/bin/libtoolize ln -s /usr/local/bin/glibtool /usr/local/bin/libtool做完软链后重新执行Maven构建这一步就能越过去。这个坑在Linux上的教程里基本见不到是macOS专属。5.2 protoc版本被覆盖Hadoop的native编译过程中会调用protoc来生成一些协议代码。如果你系统里有多个protobuf版本比如为了其他项目装过protoc 3.x而且它的路径在PATH中排在2.5.0之前那configure脚本会检测到3.x版本并报版本不兼容的错误。报错一般长这样checking protoc version... 3.1.0 configure: error: cannot find compatible protoc遇到这个问题时不要急着改代码先把PATH理顺。我直接把protoc 2.5.0的bin目录放在PATH最前面并在构建命令前再次验证which protoc protoc --version确保输出的是/usr/local/protobuf-2.5.0/bin/protoc和libprotoc 2.5.0然后再跑Maven构建。这个问题的深层原因是CDH源码的许多.proto文件生成的Java代码是强绑定protoc 2.5.0的版本一旦漂移生成出来的源码接口会变化后续javac编译时会大量报错。你如果看到一堆cannot find symbol错误先别急回头检查protoc版本比逐行改代码靠谱得多。5.3 OpenSSL和snappy头文件路径当启用-Pnative构建时configure脚本会探测OpenSSL、snappy、zlib、bzip2等依赖库。macOS系统自带的/usr/include/openssl在早期版本还存在但较新的Xcode Command Line Tools已经把它移除了。如果你用的是12或13代的macOS建议在编译前把Homebrew的openssl路径导出到环境变量export OPENSSL_ROOT_DIR/usr/local/opt/openssl export OPENSSL_INCLUDE_DIR/usr/local/opt/openssl/include export OPENSSL_LIBRARY_DIR/usr/local/opt/openssl/lib export CPPFLAGS-I/usr/local/opt/openssl/include -I/usr/local/include export LDFLAGS-L/usr/local/opt/openssl/lib -L/usr/local/libsnappy的库路径同理。Hadoop的configure脚本在macOS上经常找不到snappy.h和libsnappy.dylib导出CPPFLAGS和LDFLAGS是最省事的做法。如果你只是做Java层二开可以暂时不编进native依赖把-Pnative去掉然后在运行时使用-Djava.library.path指向不存在的目录Hadoop会退回到纯Java模式虽然会打warning但大部分HDFS测试功能可以跑。5.4 老插件和Maven 3.8的新仇旧账我必须强调一下这个坑。CDH 5.14默认pom里的maven-antrun-plugin版本很老旧插件在用模板引擎和资源过滤时对新版Maven的API兼容性非常差。如果你坚持用Maven 3.8可能会遇到这样的错误[ERROR] Failed to execute goal org.apache.maven.plugins:maven-antrun-plugin:1.7:run此时你有两条路一条是像我一样把Maven降级到3.3.9用CDH时代的工具链去编译CDH时代的代码。这条路的成本最低效果最快。另一条是在父pom里覆盖插件版本比如把maven-antrun-plugin升到1.8或更高但风险是升级后的插件行为和旧脚本的预期不完全一致可能引入新的问题。我建议除非你对Maven插件机制十分熟悉否则还是降级Maven版本更稳。这个问题的本质是Hadoop 2.6年代还没适配Maven 3.6之后引入的一些插件执行细节。你非要让老车跑新路也不是完全不行但前提是你愿意处理一长串连锁反应。6. 编译产物检查与本地伪分布式调试6.1 编译完成后应该出现哪些目录当mvn install全量通过后最好先检查一下产物。在hadoop-dist/target下你会看到一个类似hadoop-2.6.0-cdh5.14.0的目录这是-Pdist生成的可运行发行目录。里面包含bin/hdfs、yarn、mapred等启动脚本etc/hadoop/默认配置模板lib/Java依赖jarlib/native/本地库目录如果native编译成功这里会有libhadoop.dylib而不是Linux下的libhadoop.so如果你发现自己电脑上生成的是libhadoop.dylib别觉得奇怪macOS的动态库后缀就是dylib。IDEA启动NameNode时-Djava.library.path指向这个目录就行。6.2 在IDEA里启动NameNode和DataNode本地调试HDFS最常用的办法是启动两个Java进程NameNode和DataNode。在IDEA里我用Application类型的Run Configuration来跑具体配置如下。NameNodeMain class:org.apache.hadoop.hdfs.server.namenode.NameNodeVM options:-Djava.library.path/你的路径/hadoop-dist/target/hadoop-2.6.0-cdh5.14.0/lib/nativeProgram arguments: 第一次运行时先用-format之后用默认参数启动即可DataNodeMain class:org.apache.hadoop.hdfs.server.datanode.DataNodeVM options: 同上启动前还需要设置环境变量HADOOP_CONF_DIR或准备好一份core-site.xml。最简单的做法是在IDEA的Run Configuration里加一个环境变量HADOOP_CONF_DIR/你的路径/hadoop-dist/target/hadoop-2.6.0-cdh5.14.0/etc/hadoop用这个发行目录自带的etc/hadoop配置虽然默认配置比较粗糙但足以让NameNode和DataNode在本地跑起来。你要调试的二开代码如果涉及某个特定配置项再单独往配置文件里加property。6.3 native library加载问题本地调试时最不显眼但又最常出问题的是native库加载。Hadoop启动日志如果出现WARN util.NativeCodeLoader: Unable to load native-hadoop library处理方式是用显式的-Djava.library.path指定到lib/native目录然后再次启动。如果还不行就检查这个目录下是否真的生成了libhadoop.dylib有时候-Pnative没启用或者native构建失败这个目录是空的。从IDEA启动时VM options里的路径不要有中文或空格否则JNI的加载逻辑会非常脆弱。我当时把整个工程放在/Users/me/work/cdh-hadoop下路径干干净净就是不想在这种地方踩低级坑。6.4 调试时的常见断点位置如果你和我一样目的是分析NameNode的内存或元数据管理逻辑推荐关注这几个类的断点org.apache.hadoop.hdfs.server.namenode.FSNamesystem几乎所有元数据操作的主战场org.apache.hadoop.hdfs.server.blockmanagement.BlockManagerBlock的状态机核心org.apache.hadoop.hdfs.server.namenode.NameNodeRpcServerRPC请求入口打断点时要注意NameNode进程是一个持续运行的daemon断点打在启动路径上会在格式化阶段就停住。建议先以-format参数跑一次格式化完成后再正常启动否则断点命中时机不对会让你以为代码有问题。把断点打在NameNodeRpcServer的某个RPC方法上然后用HDFS的shell命令或一个简单的Java客户端去触发mkdir、写文件之类的操作就能观察完整的调用链。这一套流程在IDEA里跑通以后本地二开的效率比写代码丢服务器验证高出一个数量级。最后说一点实在的整个过程最大的感受是不要把CDH的源码当成Apache Hadoop来编译。版本对齐、仓库配置、native工具的软链处理哪一步都不能用“差不多”的心态去糊弄。我在x86 macOS上用IDEA跑通这套CDH 5.14编译前后踩掉的坑如果算成时间够我写完十个业务模块了。但一旦这条链路稳定下来后续每天改代码、跑进程、断点调试都变得非常顺手。如果你也是被CDH钉在老版本上的开发希望这篇记录能帮你少走一圈弯路。