MacOS下CMake与JDK8 JNI配置教程

本教程旨在解决在macOS系统上使用Temurin JDK 8时，CMake无法正确检测JNI（Java Native Interface）组件的问题。文章详细阐述了导致FindJNI模块失败的常见原因，并提供了一种通过在CMake命令中显式设置关键路径变量（如JAVA_HOME、JAVA_INCLUDE_PATH等）来确保JNI正确被识别和链接的有效解决方案，帮助开发者顺利构建依赖JNI的本地库。

引言：macOS上CMake与JNI集成的挑战

在macOS系统上进行Java本地接口（JNI）相关的开发时，开发者经常会遇到CMake无法正确识别和链接JNI组件的问题。即使Java开发环境（如Adoptium Eclipse Temurin JDK 8）已正确安装，且JAVA_HOME环境变量也已指向正确的JDK路径，CMake的FindJNI模块仍可能报告Could NOT find JNI (missing: JAVA_INCLUDED_PATH JAVA_INCLUDED_PATH2 AWT)等错误。这通常意味着CMake未能自动找到所有必需的JNI头文件和库路径，从而阻碍了本地库的成功构建。

此问题的根本原因在于CMake的FindJNI.cmake模块在某些特定环境下（尤其是macOS与Temurin JDK的组合）可能无法完全适配所有JDK安装路径的约定或平台差异，导致其自动检测机制失效。尽管jni.h等关键头文件实际存在于JDK的include目录下，CMake却未能正确地将这些路径赋值给其内部变量。

环境准备与问题复现

在深入解决方案之前，我们首先确保开发环境的配置符合本教程的场景，并理解问题的典型表现。

1. 安装Temurin JDK 8： 使用Homebrew可以方便地安装Temurin JDK 8。

   brew tap homebrew/cask-versions
   brew install --cask temurin8

2. 配置JAVA_HOME环境变量： 安装完成后，需要将JAVA_HOME环境变量指向Temurin JDK 8的安装路径。/usr/libexec/java_home工具可以帮助我们动态获取指定版本的JDK路径。

   export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
   echo $JAVA_HOME

   预期输出应类似于：/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home。

3. 安装CMake： 通过Homebrew安装CMake。

   brew install cmake

4. 问题复现： 在一个典型的CMake项目中，当您尝试通过find_package(JNI 1.7 REQUIRED)命令查找JNI时，可能会遇到以下错误信息：

   CMake Error at /usr/local/Cellar/cmake/3.24.2/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
     Could NOT find JNI (missing: JAVA_INCLUDED_PATH JAVA_INCLUDED_PATH2 AWT)

   这表明CMake未能成功定位JNI所需的全部组件。

解决方案：显式指定JNI路径

解决CMake无法正确检测JNI问题的最有效方法是，在调用CMake时，通过命令行参数显式地指定JNI相关的关键路径。这会覆盖FindJNI.cmake模块的自动检测行为，直接为CMake提供所需的信息。

以下是需要显式设置的关键CMake变量及其作用：

• JAVA_HOME: 指向您的Java开发工具包（JDK）的根目录。
• JAVA_INCLUDE_PATH: 指向JNI头文件（如jni.h）所在的主目录，通常是JDK根目录下的include文件夹。
• JAVA_INCLUDE_PATH2: 指向平台特定的JNI头文件（如jni_md.h）所在目录。在macOS上，这通常是JDK根目录下的include/darwin文件夹。
• JAVA_AWT_INCLUDE_PATH: 指向AWT相关的头文件目录。对于JNI目的，它通常与JAVA_INCLUDE_PATH相同。

完整的CMake命令示例：

在您的CMake构建命令中，追加以下参数。请根据您的实际项目结构调整命令，例如添加源目录路径。

# 假设您在项目构建目录中执行此命令
# $(/usr/libexec/java_home -v 1.8) 会动态获取JDK 8的安装路径
cmake \
  -DJAVA_HOME=$(/usr/libexec/java_home -v 1.8) \
  -DJAVA_INCLUDE_PATH=$(/usr/libexec/java_home -v 1.8)/include \
  -DJAVA_INCLUDE_PATH2=$(/usr/libexec/java_home -v 1.8)/include/darwin \
  -DJAVA_AWT_INCLUDE_PATH=$(/usr/libexec/java_home -v 1.8)/include \
  .. # 这里是您的CMakeLists.txt所在的源目录路径，例如如果CMakeLists.txt在父目录

执行此命令后，CMake将使用您提供的精确路径来查找JNI组件，从而成功配置您的项目。

注意事项与最佳实践

• 路径的动态性： 示例中使用了/usr/libexec/java_home -v 1.8来动态获取JDK 8的安装路径。这种方法比硬编码路径更具鲁棒性，因为它能适应JDK安装位置的变化。
• 平台特异性： JAVA_INCLUDE_PATH2变量的值是平台特定的。本教程中使用的include/darwin路径专门适用于macOS系统。在其他操作系统（如Linux或Windows）上，您需要根据其JDK的实际目录结构进行调整（例如，Linux可能是include/linux或直接在include下）。
• 适用性： 这种显式配置JNI路径的方法对于多种CMake版本和JDK版本（特别是当FindJNI.cmake无法自动检测到JNI时）都非常有效。
• 调试与验证： 运行CMake后，仔细检查其输出日志。如果配置成功，您应该不会再看到JNI相关的错误，并且在CMakeCache.txt文件中可以找到正确设置的JNI相关变量。

总结

在macOS环境下，当CMake无法正确检测Temurin JDK 8的JNI组件时，通过在CMake命令中显式指定JAVA_HOME、JAVA_INCLUDE_PATH、JAVA_INCLUDE_PATH2和JAVA_AWT_INCLUDE_PATH等关键路径变量，可以有效地解决这一问题。这种方法提供了对JNI查找过程的精确控制，确保了依赖JNI的本地库能够顺利编译和链接。建议开发者在遇到类似的JNI检测问题时，将显式路径配置作为首选的解决方案。