跳轉至

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 設定。