JOCL 技术文档

本文档旨在帮助用户了解和使用 JOCL（Java Bindings for OpenCL）项目。以下是关于安装、使用以及项目 API 的详细说明。

1. 安装指南

Maven 坐标

JOCL 在 Maven Central 上可用，使用以下坐标进行依赖添加：

<dependency>
    <groupId>org.jocl</groupId>
    <artifactId>jocl</artifactId>
    <version>2.0.4</version>
</dependency>

构建步骤

1. 创建一个本地工作目录，例如 C:\JOCLRoot，并将所需仓库克隆到该目录：

   git clone https://github.com/gpu/JOCL.git
   git clone https://github.com/gpu/JOCLCommon.git
   

2. 构建原生库 使用 CMake 和任何兼容的目标编译器（例如 Visual Studio 或 GCC）构建 JOCL 的原生库：

   • 启动 cmake-gui
   • 设置包含 JOCL 项目源码的目录，例如 C:\JOCLRoot\JOCL
   • 设置构建文件的目录：例如 C:\JOCLRoot\JOCL.build
   • 点击 "Configure"（并选择合适的编译器）
   • 点击 "Generate"

   然后，C:\JOCLRoot\JOCL.build 将包含构建文件，例如 GCC makefiles 或 Visual Studio 项目文件。使用这些 makefiles 编译项目将把二进制文件放置到项目的 nativeLibraries 子目录中，例如 C:\JOCLRoot\JOCL\nativeLibraries。

3. 构建和打包外部原生库依赖 JOCL 本身没有外部依赖，除了运行时依赖 OpenCL 实现。如果仅需编译 JOCL，可以跳过此部分。

   对于如 JOCLBLAS 和 JOCLBlast 等库，它们需要安装外部库（clBLAS 和 CLBlast）。按照相应文档编译并安装这些外部库后，将头文件和库文件路径填入 CMake GUI 中的 CLBLAST_INSTALL_DIR 和 CLBlast_LIBRARY。

   之后，按照上述 构建原生库 部分说明编译 JOCLBlast。

4. 构建Java库 原生库构建完成后，切换到 JOCL 目录并执行以下命令：

   mvn clean install
   

   这将编译 Java 库，运行单元测试，并将类文件（包括原生库）、源代码和 JavaDocs 打包成 JAR 文件，最终将所有库放置在 C:\JOCLRoot\JOCL\target 目录中。

5. 为 Android 构建库 编译 Android 的原生代码较为繁琐，因此使用 android-cmake 以简化流程。首先安装 android-cmake 工具链文件到 cmake 模块路径。然后在 JOCL 目录下创建构建目录，并使用以下命令配置构建：

   cmake -DCMAKE_TOOLCHAIN_FILE=android.toolchain \
         -DANDROID_ABI=armeabi-v7a \
         -DANDROID_NATIVE_API_LEVEL=21 \
         -DCMAKE_BUILD_TYPE=Release \
         ..
   

   最后，在构建最终的 .jar 文件时，避免运行本地测试：

   mvn clean install -DskipTests
   

6. 在虚拟机中构建 JOCL for Linux 可以在虚拟机中使用 Vagrant 构建。准备好 Vagrantfile 后，执行以下命令启动构建：

   vagrant up
   

   构建完成后，生成的 JAR 文件将放置在工作目录中。要删除构建过程中创建的虚拟机，执行：

   vagrant destroy
   

2. 使用说明

JOCL 的使用方式请参考官方文档和示例代码。

3. 项目 API 使用文档

JOCL 的 API 使用文档请参考官方文档。

4. 项目安装方式

请参考上述 安装指南 部分进行项目安装。