跳转至

Android Native

Android Native 安装指南

Hercules Android Native Library 可通过 Maven Central 安装。


1. 配置 Maven Central 仓库

确认项目的 settings.gradle 或 settings.gradle.kts 中已添加 Maven Central 仓库。

如果 dependencyResolutionManagement 的 repositories 中已有 mavenCentral(),则无需额外配置。

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

如果已有 dependencyResolutionManagement,但其中没有 mavenCentral(),请将 mavenCentral() 添加到现有的 repositories 中。

如果项目不是通过 settings.gradle 或 settings.gradle.kts 管理仓库,请将以下内容添加到使用 Hercules 的模块的 build.gradle 或 build.gradle.kts 中。

repositories {
    mavenCentral()
}
Warning

如果已有 repositories 配置块,请勿删除或覆盖,只需添加 mavenCentral()。


2. 添加 Hercules 依赖项

在将使用 Hercules 的 Android 模块的 build.gradle 或 build.gradle.kts 中添加 Hercules 依赖项。

Gradle (Groovy DSL)

dependencies {
    implementation 'com.com2us.android.gamesec:hercules:26.8.31'
}

Kotlin DSL

dependencies {
    implementation("com.com2us.android.gamesec:hercules:26.8.31")
}

执行 Gradle Sync 后,系统会自动从 Maven Central 下载 Hercules AAR。


3. 在 C/C++ 中使用 Hercules

Hercules 支持以下 ABI。

arm64-v8a, armeabi-v7a, x86, x86_64

要在 C/C++ 中使用 API,请在 Android 模块中启用 Prefab。

Gradle (Groovy DSL)

android {
    buildFeatures {
        prefab true
    }
}

Kotlin DSL

android {
    buildFeatures {
        prefab = true
    }
}

然后,根据使用的原生构建系统,添加 CMake 或 ndk-build 配置。


4. 配置 CMake

如果使用 ndk-build,或不在 C/C++ 中使用 Hercules,请跳过 CMake 配置。

4.1 将 CMake 连接到 Gradle

在使用 Hercules 的模块的 Gradle 配置中指定 CMakeLists.txt。

Gradle (Groovy DSL)
android {
    externalNativeBuild {
        cmake {
            path file('src/main/cpp/CMakeLists.txt')
        }
    }
}
Kotlin DSL
android {
    externalNativeBuild {
        cmake {
            path = file("src/main/cpp/CMakeLists.txt")
        }
    }
}

如果项目已在使用 CMake,请保留现有的 externalNativeBuild 配置。

4.2 在 CMakeLists.txt 中链接 Hercules

使用 find_package 导入 Hercules Prefab 包,然后将其链接到将使用 Hercules 的原生目标。

例如,如果项目的原生库名称为 native-lib:

cmake_minimum_required(VERSION 3.22.1)

project("sample")

add_library(native-lib SHARED
    native-lib.cpp
)

find_package(Hercules REQUIRED CONFIG)

target_link_libraries(native-lib
    Hercules::Hercules
)

5. 配置 ndk-build

如果使用 CMake,或不在 C/C++ 中使用 Hercules,请跳过 ndk-build 配置。

5.1 将 ndk-build 连接到 Gradle

在使用 Hercules 的模块的 Gradle 配置中指定 Android.mk。

Gradle (Groovy DSL)
android {
    externalNativeBuild {
        ndkBuild {
            path file('src/main/cpp/Android.mk')
        }
    }
}
Kotlin DSL
android {
    externalNativeBuild {
        ndkBuild {
            path = file("src/main/cpp/Android.mk")
        }
    }
}

如果项目已在使用 ndk-build,请保留现有的 externalNativeBuild 配置。

5.2 在 Android.mk 中链接 Hercules

在将使用 Hercules 的原生模块的 LOCAL_SHARED_LIBRARIES 中添加 Hercules,并导入 Prefab 模块。

例如,如果项目的原生库名称为 native-lib:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)
LOCAL_MODULE := native-lib
LOCAL_SRC_FILES := native-lib.cpp
LOCAL_SHARED_LIBRARIES := Hercules
include $(BUILD_SHARED_LIBRARY)

$(call import-module,prefab/Hercules)

如果还需要支持 NDK r21 之前的版本,请在导入 Prefab 前添加以下配置。

ifneq ($(call ndk-major-at-least,21),true)
    $(call import-add-path,$(NDK_GRADLE_INJECTED_IMPORT_PATH))
endif

6. 使用 API

示例:

#include <Hercules.h>
...
unsigned int version = HerculesGetVersion();
__android_log_print(ANDROID_LOG_INFO, "Hercules", "version: %u", version);

Hercules 会在 Hive SDK 初始化时一同初始化。

无需调用 InitializeHercules。


7. 更改版本

要更改要安装的 Hercules 版本,请修改 dependencies 中指定的版本。

Gradle (Groovy DSL)

implementation 'com.com2us.android.gamesec:hercules:26.8.31'

Kotlin DSL

implementation("com.com2us.android.gamesec:hercules:26.8.31")

8. 移除 Hercules

要移除 Hercules,请从该模块的 dependencies 中删除 Hercules 依赖项。

com.com2us.android.gamesec:hercules:26.8.31

如果曾在 C/C++ 中使用 Hercules,也请移除之前添加到 CMake 或 ndk-build 中的 Hercules 链接配置。

CMake:

find_package(Hercules REQUIRED CONFIG)
Hercules::Hercules

ndk-build:

LOCAL_SHARED_LIBRARIES := Hercules
$(call import-module,prefab/Hercules)

如果除了 Hercules 以外,没有其他依赖项使用 Prefab 包,也可以移除 Gradle 的 buildFeatures.prefab 配置。