Android Native
Android Native Installation Guide¶
The Hercules Android Native Library can be installed through Maven Central.
1. Configure the Maven Central Repository¶
Check that the Maven Central repository is registered in your project's settings.gradle or settings.gradle.kts.
No additional configuration is required if mavenCentral() is already present in the repositories block of dependencyResolutionManagement.
If dependencyResolutionManagement already exists but does not include mavenCentral(), add mavenCentral() to the existing repositories block.
If your project does not manage repositories in settings.gradle or settings.gradle.kts, add the following to the build.gradle or build.gradle.kts file of the module that uses Hercules.
Warning
If a repositories block already exists, do not delete or overwrite it. Add only mavenCentral().
2. Add the Hercules Dependency¶
Add the Hercules dependency to the build.gradle or build.gradle.kts file of the Android module that will use Hercules.
Gradle (Groovy DSL)¶
Kotlin DSL¶
Run Gradle Sync to automatically download the Hercules AAR from Maven Central.
3. Use Hercules in C/C++¶
Hercules supports the following ABIs.
To use the API in C/C++, enable Prefab in the Android module.
Gradle (Groovy DSL)¶
Kotlin DSL¶
Then add the CMake or ndk-build configuration according to the native build system you use.
4. Configure CMake¶
Skip the CMake configuration if you use ndk-build or do not use Hercules in C/C++.
4.1 Connect CMake to Gradle¶
Specify CMakeLists.txt in the Gradle configuration of the module that uses Hercules.
Gradle (Groovy DSL)¶
Kotlin DSL¶
If your project already uses CMake, keep the existing externalNativeBuild configuration.
4.2 Link Hercules in CMakeLists.txt¶
Import the Hercules Prefab package using find_package, then link it to the native target that will use Hercules.
For example, if your project's native library is named 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. Configure ndk-build¶
Skip the ndk-build configuration if you use CMake or do not use Hercules in C/C++.
5.1 Connect ndk-build to Gradle¶
Specify Android.mk in the Gradle configuration of the module that uses Hercules.
Gradle (Groovy DSL)¶
Kotlin DSL¶
If your project already uses ndk-build, keep the existing externalNativeBuild configuration.
5.2 Link Hercules in Android.mk¶
Add Hercules to LOCAL_SHARED_LIBRARIES in the native module that will use Hercules, and import the Prefab module.
For example, if your project's native library is named 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)
If you also need to support versions earlier than NDK r21, add the following configuration before importing Prefab.
ifneq ($(call ndk-major-at-least,21),true)
$(call import-add-path,$(NDK_GRADLE_INJECTED_IMPORT_PATH))
endif
6. Use the API¶
Example:
#include <Hercules.h>
...
unsigned int version = HerculesGetVersion();
__android_log_print(ANDROID_LOG_INFO, "Hercules", "version: %u", version);
Hercules is initialized together with the Hive SDK.
You do not need to call InitializeHercules.
7. Change the Version¶
To change the version of Hercules to install, change the version specified in dependencies.
Gradle (Groovy DSL)¶
Kotlin DSL¶
8. Remove Hercules¶
To remove Hercules, delete the Hercules dependency from the module's dependencies.
If you used Hercules in C/C++, also remove the Hercules linking configuration you added to CMake or ndk-build.
CMake:
ndk-build:
If no dependencies other than Hercules use Prefab packages, you can also remove the buildFeatures.prefab setting from Gradle.