OpenCV Maven 构建指南：用 Maven 一键产出 OSGi 兼容的 Java 原生捆绑包

OpenCV 在 Java 侧的常规构建方式是基于 CMake 生成并编译 opencv_java 模块，再交由传统 Java 工程引用；而本仓库在 platforms/maven 目录中提供了一套完整的 Apache Maven 构建方案，将既有 CMake 流程包装为多模块 Maven 项目。这篇文章以 platforms/maven/README.md 为主线，结合仓库中的 POM、Shell 脚本与集成测试源码，完整还原「环境准备 → 一键构建 → OSGi 打包 → 集成测试 → 版本维护」的端到端流程，读完你可以在 Debian 系 Linux（含树莓派 ARM）上直接用 mvn clean install 构建出可部署进 Apache Karaf 等 OSGi 容器的 OpenCV 捆绑包。

一、Maven 构建的本质与目标

首先需要明确一个关键前提：这套 Maven 构建并不是另起炉灶重写 OpenCV 的构建系统，而是一个“包装器（wrapper）”。它复用仓库根目录的标准 CMake 构建，通过 Maven 插件在生命周期中依次驱动 CMake 的生成与编译，并额外完成三件 CMake 原生流程做不到的事：

1. 提供一条更简单、面向 Java 开发者的 OpenCV 构建路径，免去手工记忆 CMake 参数；
2. 构建开始前自动检测所需的原生（native）依赖包是否齐全，缺失即在早期阶段报错，而不是编译到一半才暴露；
3. 把产出的 Java 库制作成 OSGi 兼容捆绑包（bundle），并将编译好的 OpenCV 原生动态库一并打进 bundle，从而在 OSGi 容器中部署时自动完成原生库的装载。

整体采用 Maven 标准的父子多模块结构，入口聚合 POM 为 platforms/maven/pom.xml：

• 坐标：groupId org.opencv、artifactId opencv-parent，当前版本 5.0.0，packaging 为 pom；
• 默认聚合模块只有 opencv（真正的构建模块）；
• 集成测试模块 opencv-it 被放在一个名为 integration 的 profile 中，activeByDefault 为 false，因此默认不参与构建，需要用开关显式激活（见后文第六节）。

opencv 子模块的打包类型为 bundle（platforms/maven/opencv/pom.xml），由 Felix 的 maven-bundle-plugin 支持，这正是“OSGi 兼容”落地的关键点。

二、准备构建环境

README 的假设环境是 Debian 系 Linux（Debian/Ubuntu/Raspbian 均可，POM 中也用 maven-enforcer 强制校验操作系统必须属于 Unix family）。构建机需要预先安装两样基础工具：

• Maven（构建驱动本身）
• JDK（Java Development Kit，编译 Java 绑定层）

如果你不确定是否已安装，最简单的办法是用 aptitude 包管理器一次性安装：

sudo aptitude install maven default-jdk

说明：通过发行版仓库（aptitude/apt-get）安装的 Maven 与 JDK 往往不是最新版本；但对本构建流程而言版本不是关键，只要满足使用即可，不必特意追新。另外 README 特别提示：若你后续并不开发 Java 代码，这个构建流程对 JDK 版本并不敏感。

从 platforms/maven/opencv/pom.xml 的 enforcer 配置可以印证，构建对运行环境的最低约束就是这些环境变量：

环境变量	级别	说明
JAVA_HOME	ERROR	指向 JDK 根目录的绝对路径，未设置会导致构建失败
ANT_HOME	ERROR	指向 Apache Ant 根目录的绝对路径，未设置可能导致构建失败
MAKEFLAGS	WARN	未设置不报错，但构建会退化为单线程、明显变慢

这三条规则定义在 maven-enforcer-plugin 的 enforce-environment 执行中：前两者级别为 ERROR，MAKEFLAGS 仅为 WARN，并且给出了直接可读的提示信息。除 enforcer 之外，构建还会在 native 依赖检查阶段用 dpkg 校验必需的系统库，详见第三节。

关于并行加速：Maven 本身并不直接控制底层 C/C++ 的编译并发度，真正的并行度来自 make，因此 README 建议导出：

export MAKEFLAGS="-j8"

其中 -jN 的 N 代表并行编译任务数。若不确定，可保守地按 CPU 核心数设置。文档同时给出了一组参考数据：在不设置 MAKEFLAGS（等效 -j1）时，Raspberry Pi 2 上构建耗时约 5 小时，而改用 -j4 后降到 2 小时出头——可见并行开关对 ARM 等慢速平台几乎是必备的。以上三个变量都可以临时用 export 设置，无需写入全局配置。

三、依赖自检：构建开始前先“体检”

3.1 自检机制如何工作

mvn clean install 启动后，构建会先检查系统里是否装齐了编译 OpenCV 所需的原生依赖，缺哪一个会直接红字标出并中止。承担这项工作的脚本是 platforms/maven/opencv/scripts/deb_package_check：

• 通过 dpkg -s <包名> 判断某个 Debian 包是否已安装；
• 支持 -o <包名> 开关把某个包标记为可选（optional），缺失不致命；
• 支持用管道符 | 分隔“二选一（或多选一）”的包族，例如 libpng-dev|libpng12-dev，按从左到右的顺序检查，命中第一个已安装的即通过。

在 POM 中，这一步被绑定为 exec-maven-plugin 的 setup-environment 执行，运行在 validate 阶段，传入参数时遵循“可选包必须排在必需包之前”的注释约定。脚本全部通过时返回 0，任意必需包缺失则返回 1，构建随即在此失败。

3.2 依赖包清单

下表整理了 platforms/maven/opencv/pom.xml 中实际校验的包（注意这是 Debian 发行版语境下的包名，不同版本库略有差异）：

必需（必装）

Debian 包	用途推测
build-essential	gcc/g++/make 等编译工具链
cmake	底层构建系统
git	版本信息/源码管理
libgtk2.0-dev	highgui 的 GTK 后端
pkg-config	依赖查找
libavcodec-dev / libavformat-dev / libswscale-dev	FFmpeg 音视频编解码支持
libtbb2 / libtbb-dev	Intel TBB 并行库（运行时 + 开发头文件）
libjpeg-dev	JPEG 编解码
libtiff5-dev	TIFF 编解码
libdc1394-22-dev	IEEE 1394 相机接口
execstack	用于后处理校验生成的 .so 是否含可执行栈
ant	Ant 构建工具（与 $ANT_HOME 配套）

可选（二选一或可缺省）

Debian 包	说明
-o libpng-dev|libpng12-dev	PNG 支持，两个版本装其一即可
-o libopenjp2-7-dev|libjasper-dev	JPEG2000 支持，OpenJPEG 或 JasPer 二选一
-o python-dev	Python 头文件（可选）
-o python-numpy	NumPy 支持（可选）

若自检阶段提示缺失，用 sudo aptitude install <包名> 或 sudo apt-get install <包名> 补装后，重新执行 mvn clean install 即可，脚本会显示绿色 INSTALLED / 红色 MISSING 的彩色状态便于逐项核对。

四、启动构建与产物目录

4.1 统一的启动命令

Maven 构建的入口是 platforms/maven/pom.xml，所以应当进入该 POM 所在目录再执行标准命令：

mvn clean install

无论 x86、x86_64 还是 ARM 32 位，主流程命令完全相同。README 中唯一提示的架构差异在于：ARM 版 Raspbian 时代没有官方的 libtbb2 / libtbb-dev 包，需要自行安装（当时有非官方的 TBB 4.4.3 Raspbian 兼容 Debian 包，属于非官方来源，风险自担），而在 x86 架构上只需保证自检清单通过即可。

4.2 构建产物目录

默认情况下构建会落到仓库根目录下名为 build 的目录，README 与 POM 协同定义的布局如下：

目录（以 <OpenCV_root_dir> 为仓库根）	内容
<OpenCV_root_dir>/build	标准 CMake 产物（lib、src 等）
<OpenCV_root_dir>/build/maven/opencv/target	OSGi 兼容的 Java 捆绑包（本文的核心产物）
<OpenCV_root_dir>/build/maven/opencv-it/target	集成测试模块的构建输出（仅构建期有用）

从 platforms/maven/opencv/pom.xml 可以看到具体映射：opencv 模块的 <directory> 直接指到 ../../../build/maven/opencv/target（相对该 POM），sourceDirectory 与 outputDirectory 指向 build/src，即 CMake 阶段生成的 Java 绑定源码所在的目录。bundle 打好后部署进 OSGi 框架（例如 Apache Karaf），原生库的装载会自动完成，不需要额外配置。

五、Maven 生命周期与 CMake 的衔接：逐阶段源码解析

maven 构建与 CMake 的衔接并非魔法，而是由一组插件按生命周期阶段精确编排的。读懂 platforms/maven/opencv/pom.xml 中的插件配置，整条流水线就一目了然：

生命周期阶段	动作	执行方式
validate	强制 OS 为 Unix；校验 ANT_HOME / JAVA_HOME / MAKEFLAGS	maven-enforcer-plugin
validate	运行 deb_package_check 做原生依赖自检	exec-maven-plugin（setup-environment）
generate-resources	运行 properties 脚本提取版本/架构信息并写出 build.properties	exec-maven-plugin（get-opencv-version）
generate-resources	把 resources 目录（含 blueprint 等）复制进 build/src	maven-resources-plugin
generate-sources	cmake-maven-plugin 先 generate（配置 CMake）再 compile（编译目标）	cmake-maven-plugin
process-resources	读取 build.properties 把版本/架构注入 Maven 属性	properties-maven-plugin
process-resources	校验 POM 版本与 OpenCV 核心版本一致	maven-enforcer-plugin（check-versions-match）
process-classes	对生成的 build/lib/libopencv_java*.so 执行 execstack_check	exec-maven-plugin
package	用 maven-bundle-plugin 打 OSGi bundle	maven-bundle-plugin
install	安装到本地 Maven 仓库	标准 lifecycle

几个值得展开的关键细节：

1. CMake 由 cmake-maven-plugin（com.googlecode.cmake-maven-project）驱动。 它被配置为使用系统已装的原生 CMake（download.cmake 属性默认 false），不会擅自联网下载 CMake 二进制。生成阶段指定 generator 为 Unix Makefiles、sourcePath 指向 ../../..（即 OpenCV 仓库根），并传入关键 CMake 选项：

-DBUILD_SHARED_LIBS:BOOL=OFF

随后编译阶段只针对 opencv_java 这一个 target 调用 make，从而把整个仓库的编译范围收敛到 Java 绑定产物上。

2. 版本与架构信息不是写死的，而是从源码实时抽取。 get-opencv-version 执行 platforms/maven/opencv/scripts/properties，该脚本先定位 OpenCV 核心版本头文件 modules/core/include/opencv2/core/version.hpp，再由 platforms/maven/opencv/scripts/functions 中定义的 extract_version() 用 grep 取出 CV_VERSION_MAJOR、CV_VERSION_MINOR、CV_VERSION_REVISION 宏，拼出形如 5.0.0 的三段版本号。本仓库该头文件当前定义的宏为 5 / 1 / 0（状态 -dev）。随后脚本综合 CPU 字长（getconf LONG_BIT）与 arch/lscpu 结果，把以下内容写入构建目录的 build.properties：

属性	含义	取值示例
opencv.version	三段式版本号，用于 enforcer 比对	5.1.0
lib.version.string	去掉点号的版本串，用于拼原生库名	510（对应 libopencv_java510.so）
bits	CPU 二进制字长	32 / 64
architecture	处理器架构	x86_64 / armv7l 等
osgi.processor	OSGi 规范的处理器名	x86 / x86_64 / arm_le / arm_be

脚本中 osgi.processor 的判断逻辑：x86 家族按字长分为 x86 与 x86_64；ARM 家族则依据字节序（lscpu 输出的 Byte Order）区分 arm_le 与 arm_be。随后 properties-maven-plugin 在 process-resources 阶段把这个文件读回为 Maven 属性，供后续插件使用——例如原生库文件名：

<nativelibrary.name>libopencv_java${lib.version.string}.so</nativelibrary.name>

3. check-execstack 是一个值得注意的安全质检步骤。 POM 在 process-classes 阶段调用 platforms/maven/opencv/scripts/execstack_check，对 build/lib/ 下生成的 libopencv_java*.so 做检查（这也解释了为何依赖清单里要求安装 execstack 工具）。这类检查在部分安全策略严格的 OSGi/容器部署场景下是有价值的把关环节。

六、OSGi 捆绑包的生成、部署与原生库自动装载

6.1 打包指令

maven-bundle-plugin（Felix）在 package 阶段把 Java 绑定类打成真正的 OSGi bundle，其核心指令集中在 platforms/maven/opencv/pom.xml：

<Export-Package>*</Export-Package>
<Bundle-NativeCode>${nativelibrary.name};osname=linux;processor=${osgi.processor}</Bundle-NativeCode>
<Include-Resource>${build.directory}/lib/${nativelibrary.name}</Include-Resource>

含义分别是：导出 bundle 内全部包；声明原生代码段（Bundle-NativeCode 头，注明 osname=linux 与处理器名，这正是 OSGi 选择原生库的依据）；把编译好的 .so 作为 bundle 资源一并打入，使其随 bundle 分发而不再要求外部手工放置。manifestLocation 指向 build/manifest，niceManifest 为 true 以便人类阅读生成的 MANIFEST.MF。

6.2 原生库如何被自动装载

关键在 org.opencv.osgi.OpenCVNativeLoader 这个类。它的模板源码位于 modules/java/generator/src/java/org/opencv/osgi/OpenCVNativeLoader.java.in，构建期由 CMake 把 @OPENCV_JAVA_LIB_NAME_SUFFIX@ 占位符替换成实际的库名后缀，核心动作只有一行：

System.loadLibrary("opencv_java" + ...);

而 modules/java/generator/src/java/org/opencv/osgi/OpenCVInterface.java 是一个标记接口，用来在 OSGi 服务注册层面充当“原生库已就绪”的信号。

为了让 bundle 部署进容器时能自动触发装载，platforms/maven/opencv/resources/OSGI-INF/blueprint/blueprint.xml 定义了一个 Blueprint 描述文件（该文件经 maven-resources-plugin 在 generate-resources 阶段被复制进 build/src 随 bundle 发布）：

<bean id="opencvnativeloader" class="org.opencv.osgi.OpenCVNativeLoader" scope="singleton" init-method="init" />
<service id="opencvtestservice" ref="opencvnativeloader" interface="org.opencv.osgi.OpenCVInterface" />

容器实例化这个单例 bean 并执行其 init 方法时，原生库即被加载；加载成功后，名为 opencvtestservice、类型为 OpenCVInterface 的 OSGi 服务随之发布，后续业务代码只要注入该服务，就能保证原生库已经可用——这正是“部署后自动搞定 native 装载”的实现机制。

6.3 运行 OSGi 集成测试

README 指出集成测试模块默认关闭（原文档中的 “disabled by fault” 为 “disabled by default” 之误），需要显式激活 integration profile：

mvn clean install -Pintegration

profile 定义在聚合 POM platforms/maven/pom.xml 中，激活后把 opencv-it 纳入 reactor。该模块的测试代码 platforms/maven/opencv-it/src/test/java/org/opencv/osgi/DeployOpenCVTest.java 展示了完整的“OSGi 环境下真实部署验证”思路：

• 使用 Pax Exam（pax-exam-container-karaf 4.8.0）动态下载并展开 Apache Karaf 4.0.6 发行版作为测试容器；
• 通过 mavenBundle().groupId("org.opencv").artifactId("opencv").versionAsInProject() 把刚构建的 OpenCV bundle 部署进 Karaf；
• 注入 OpenCVInterface 服务与 Karaf 的 LogService，然后扫描容器日志，断言其中出现 Successfully loaded OpenCV native library. 这条成功日志；
• 若 bundle 未能成功部署或原生库加载失败，测试即断言失败并给出明确信息。

值得留意的是，该测试依赖清单（platforms/maven/opencv-it/pom.xml）里还包含了 OSGi 规范 API（org.osgi.core、org.osgi.compendium）、JUnit 与 SLF4J 等，全部以 test 作用域引入，不会污染生产依赖。这套机制把“能编出来”验证到了“能在真实 OSGi 容器里跑起来”。

6.4 可选开关：下载 CMake

上文提到 cmake-maven-plugin 默认使用系统原生 CMake（推荐做法）。README 也保留了一条旁路：若确有需要让构建下载 CMake 二进制，可附加开关：

mvn clean install -Ddownload.cmake=true

七、维护者笔记：POM 版本与核心版本的同步

本节约有读者可能不关心，但对维护 Maven 平台构建的人是必读内容，README 原样保留了这部分。

7.1 为什么需要强校验

Maven 要求版本号硬编码在 POM 中，无法在运行时改动。当核心 C/C++ 版本号更新后，很容易忘记同步 Maven 侧的版本。为此 platforms/maven/opencv/pom.xml 用 enforcer 插件的 check-versions-match 执行来兜底：它把 process-resources 阶段抽取出的 opencv.version 作为正则，要求 project.version 与之匹配，不一致则构建直接失败，错误信息会给出修复命令的提示。

7.2 如何批量升级版本

POM 版本需要升级时，推荐使用 Maven 的 versions 插件，它会把这个版本应用到项目内所有 POM。执行位置是 Maven 工程（即 platforms/maven）的根目录，版本号由仓库脚本现场算出，无需手填：

mvn versions:set -DnewVersion=$(. ./opencv/scripts/functions && cd ./opencv/scripts && extract_version && echo $REPLY)

命令的工作方式：先 source 脚本 platforms/maven/opencv/scripts/functions，切到 scripts 目录调用 extract_version，把从 modules/core/include/opencv2/core/version.hpp 宏中读出的三段版本号输出给 -DnewVersion。这样 Maven 侧版本始终以 C/C++ 核心头文件为准，从源头消除手改出错的可能。

八、适用范围与限制小结

• 平台：面向 Debian 系 Linux；POM 通过 enforcer 强制 unix 家族，设计目标同时覆盖 x86/x86_64 与 Raspberry Pi（ARM 32 位，Raspbian）架构，x86 Linux 上同样可用；
• 产物：build/maven/opencv/target 下得到 OSGi 兼容 bundle（内含 libopencv_java*.so 原生库与 Blueprint 描述），另在 build/lib 等标准位置保留 CMake 产物，传统 Java 用法也不受影响；
• 非目标：opencv-it 集成测试默认不执行，仅在显式加 -Pintegration 时运行；download.cmake 默认关闭。

若想亲手验证这套构建，可沿 platforms/maven 目录按顺序阅读聚合 POM、opencv 模块 POM、三个 辅助脚本 与 集成测试源码，它们共同构成了“依赖自检 → CMake 编译 → OSGi 打包 → 容器验证 → 版本守卫”的完整可审计链路。