Thanks to visit codestin.com
Credit goes to github.com

Skip to content

mzdk100/cargo-apk2

 
 

Repository files navigation

cargo-apk2

Actions Status Latest version MSRV Documentation Repository MIT Apache 2.0

English | 中文

Tool for creating Android packages from native Rust crates. We have created this tool because the predecessor of this tool (cargo-apk) has stagnated for over a year at the time of writing this documentation.

This tool requires minimal setup and tooling, without the requirement of Gradle configuration. Ideal for apps that provide a NativeActivity via android-activity and ndk.

In addition to features available in cargo-apk, this tool supports compiling sources of JVM-based languages into DEX data to be packaged in the APK file; declaration of multiple activities and even services are supported.

Installation

From crates.io:

cargo install cargo-apk2

From locally downloaded or cloned source:

git clone https://github.com/mzdk100/cargo-apk2
cargo install --path cargo-apk2/

Crate configuration

Android and thus cargo-apk require the Cargo Target to be a Shared Library, corresponding to Rust's cdylib crate-type. For the sole library in a crate, configure this as follows in Cargo.toml:

[lib]
# Optionally supports a different library location using `path = "..."`
crate-type = ["cdylib"]

The source repository of this tool provides some example configurations.

Commands

  • build: Compile the selected crate and package it into an APK
  • run: Compile, install and run the selected crate/package on an attached Android device via adb
  • gdb: Start a gdb session on an attached Android device via adb, with symbols loaded

Manifest

cargo apk reads additional configuration from Cargo's [package.metadata] table. The following configuration options are supported by cargo apk under [package.metadata.android]:

[package.metadata.android]
# Use `aapt2` instead of `aapt` for compiling application resources.
use_aapt2 = true

# Specifies the package property of the manifest.
# See https://developer.android.com/guide/topics/manifest/manifest-element#package
package = "com.foo.bar"

# Specifies the array of targets to build for.
build_targets = [ "armv7-linux-androideabi", "aarch64-linux-android", "i686-linux-android", "x86_64-linux-android" ]

# Path to your application's resources folder.
# If not specified, resources will not be included in the APK.
resources = "path/to/resources_folder"

# Path to the folder containing your application's assets.
# If not specified, assets will not be included in the APK.
assets = "path/to/assets_folder"

# Directory path of Java source files.
# If not specified, the Java compilation process might be skipped.
java_sources = "path/to/java"

# Directory path of Kotlin source files.
# If not specified, the Kotlin compilation process will be skipped.
kotlin_sources = "path/to/kotlin"

# Directory path of Groovy source files.
# If not specified, the Groovy compilation process will be skipped.
groovy_sources = "path/to/groovy"

# Directory path of Scala source files.
# If not specified, the Scala compilation process will be skipped.
scala_sources = "path/to/scala"

# Name for final APK file.
# Defaults to package name.
apk_name = "myapp"

# `default` (or unspecified) - Debug symbols, if they exist, are not treated
#                              specially.
#
# `strip`                    - Debug symbols are stripped from the shared
#                              libraries before being copied into the APK.
#
# `split`                    - Functions the same as `strip`, except the debug
#                              symbols are written to the apk output directory
#                              alongside the stripped shared libraries, with
#                              a `.dwarf` extension.
#
# Note that the `strip` and `split` options will only have an effect if
# debug symbols are present in the `.so` file(s) produced by your build, enabling
# https://doc.rust-lang.org/cargo/reference/profiles.html#strip or
# https://doc.rust-lang.org/cargo/reference/profiles.html#split-debuginfo
# in your cargo manifest can cause debug symbols to no longer be present
# in the `.so`.
strip = "default"

# Folder containing extra shared libraries intended to be dynamically loaded at runtime.
# Files matching `libs_folder/${android_abi}/*.so` are added to the apk
# according to the specified build_targets.
runtime_libs = "path/to/libs_folder"

# The name of a Linux user ID that is shared with other apps. By
# default, Android assigns each app its own unique user ID. However, if
# this attribute is set to the same value for two or more apps, they all
# share the same ID, provided that their certificate sets are identical.
# Apps with the same user ID can access each other's data and, if
# desired, run in the same process.
shared_user_id = "my.shared.user.id"

# Defaults to `$HOME/.android/debug.keystore` for the `dev` profile. Will ONLY
# generate a new debug.keystore if this file does NOT exist. A keystore is never
# auto-generated for other profiles.
#
# The keystore path can be absolute, or relative to the Cargo.toml file.
#
# The environment variables `CARGO_APK_<PROFILE>_KEYSTORE` and
# `CARGO_APK_<PROFILE>_KEYSTORE_PASSWORD` can be set to a keystore path
# and keystore password respectively. The profile portion follows the same rules
# as `<cfg>`, it is the uppercased profile name with `-` replaced with `_`.
#
# If present they take precedence over the signing information in the manifest.
[package.metadata.android.signing.<profile>]
path = "relative/or/absolute/path/to/my.keystore"
keystore_password = "android"

# See https://developer.android.com/guide/topics/manifest/uses-sdk-element
#
# Defaults to a `min_sdk_version` of `24` and `target_sdk_version` of `36`
# (or lower if the detected NDK doesn't support this).
[package.metadata.android.sdk]
min_sdk_version = 24
target_sdk_version = 36
max_sdk_version = 36

# See https://developer.android.com/guide/topics/manifest/uses-feature-element
#
# Note: there can be multiple .uses_feature entries.
[[package.metadata.android.uses_feature]]
name = "android.hardware.vulkan.level"
required = true
version = 1

# See https://developer.android.com/guide/topics/manifest/uses-permission-element
#
# Note: there can be multiple .uses_permission entries.
[[package.metadata.android.uses_permission]]
name = "android.permission.WRITE_EXTERNAL_STORAGE"
max_sdk_version = 36

# See https://developer.android.com/guide/topics/manifest/queries-element#provider
[[package.metadata.android.queries.provider]]
authorities = "org.khronos.openxr.runtime_broker;org.khronos.openxr.system_runtime_broker"
# Note: The `name` attribute is normally not required for a queries provider, but is non-optional
# as a workaround for aapt throwing errors about missing `android:name` attribute.
# This is optional when aapt2 is used.
name = "org.khronos.openxr"

# See https://developer.android.com/guide/topics/manifest/queries-element#intent
[[package.metadata.android.queries.intent]]
actions = ["android.intent.action.SEND"]

# See https://developer.android.com/guide/topics/manifest/queries-element#intent
# Note: there can be several .data entries.
[[package.metadata.android.queries.intent.data]]
mime_type = "image/jpeg"

# See https://developer.android.com/guide/topics/manifest/queries-element#package
[[package.metadata.android.queries.package]]
name = "org.freedesktop.monado.openxr_runtime.in_process"

# See https://developer.android.com/guide/topics/manifest/application-element
[package.metadata.android.application]

# See https://developer.android.com/guide/topics/manifest/application-element#debug
#
# Defaults to false.
debuggable = false

# See https://developer.android.com/guide/topics/manifest/application-element#theme
#
# Example shows setting the theme of an application to fullscreen.
theme = "@android:style/Theme.DeviceDefault.NoActionBar.Fullscreen"

# Virtual path your application's icon for any mipmap level.
# If not specified, an icon will not be included in the APK.
icon = "@mipmap/ic_launcher"

# See https://developer.android.com/guide/topics/manifest/application-element#label
#
# User-readable application name. Defaults to the compiled artifact's name.
label = "Application Name"

# See https://developer.android.com/guide/topics/manifest/application-element#extractNativeLibs
extract_native_libs = true

# See https://developer.android.com/guide/topics/manifest/application-element#usesCleartextTraffic
uses_cleartext_traffic = true

# See https://developer.android.com/guide/topics/manifest/meta-data-element
#
# Note: there can be several .meta_data entries.
[[package.metadata.android.application.meta_data]]
name = "com.samsung.android.vr.application.mode"
value = "vr_only"

# Supports multiple `activity` elements (there should be at least one); by default
# `cargo-apk2` does not generate any activity implicitly.
# See https://developer.android.com/guide/topics/manifest/activity-element
[[package.metadata.android.application.activity]]

# See https://developer.android.com/guide/topics/manifest/activity-element#config
#
# Defaults to "orientation|keyboardHidden|screenSize".
config_changes = "orientation"

# See https://developer.android.com/guide/topics/manifest/activity-element#label
#
# Defaults to the application's label.
label = "Activity Name"

# See https://developer.android.com/guide/topics/manifest/activity-element#lmode
#
# Defaults to "standard".
launch_mode = "singleTop"

# See https://developer.android.com/guide/topics/manifest/activity-element#screen
#
# Defaults to "unspecified".
orientation = "landscape"

# See https://developer.android.com/guide/topics/manifest/activity-element#exported
#
# Unset by default, or true when targeting Android >= 31 (S and up).
exported = true

# See https://developer.android.com/guide/topics/manifest/activity-element#resizeableActivity
#
# Defaults to true on Android >= 24, no effect on earlier API levels
resizeable_activity = false

# See https://developer.android.com/guide/topics/manifest/activity-element#always
always_retain_task_state = true

# See https://developer.android.com/guide/topics/manifest/meta-data-element
#
# Note: there can be several .meta_data entries.
[[package.metadata.android.application.activity.meta_data]]
name = "com.oculus.vr.focusaware"
value = "true"

# See https://developer.android.com/guide/topics/manifest/intent-filter-element
#
# Note: there can be several .intent_filter entries.
[[package.metadata.android.application.activity.intent_filter]]
# See https://developer.android.com/guide/topics/manifest/action-element
actions = ["android.intent.action.VIEW", "android.intent.action.WEB_SEARCH"]
# See https://developer.android.com/guide/topics/manifest/category-element
categories = ["android.intent.category.DEFAULT", "android.intent.category.BROWSABLE"]

# See https://developer.android.com/guide/topics/manifest/data-element
#
# Note: there can be several .data entries.
# Note: not specifying an attribute excludes it from the final data specification.
[[package.metadata.android.application.activity.intent_filter.data]]
scheme = "https"
host = "github.com"
port = "8080"
path = "/rust-windowing/android-ndk-rs/tree/master/cargo-apk"
path_prefix = "/rust-windowing/"
mime_type = "image/jpeg"

# Supports multiple `service` elements, and they can have intent filters as well.
# See https://developer.android.com/guide/topics/manifest/service-element
[[package.metadata.android.application.service]]

# The name of the Service subclass that implements the service. This is a fully qualified
# class name, such as "com.example.project.RoomService". However, as a shorthand, if the
# first character of the name is a period, such as ".RoomService", it is appended to the
# package name specified in the <manifest> element.
# Once you publish your application, don't change this name, unless you set
# `android:exported="false"`. There is no default. The name must be specified. 
name = ".MyService"

# Whether the service can be instantiated by the system. It's "true" if it can be, and
# "false" if not. The default value is "true".
# The <application> element has its own enabled attribute that applies to all application
# components, including services. The <application> and <service> attributes must both be
# "true", as they both are by default, for the service to be enabled. If either is "false",
# the service is disabled and can't be instantiated. 
enabled = true

# The name of a permission that an entity needs in order to launch the service or bind to it.
# If a caller of startService(), bindService(), or stopService() isn't granted this permission,
# the method doesn't work and the Intent object isn't delivered to the service.
# If this attribute isn't set, the permission set by the <application> element's permission
# attribute applies to the service. If neither attribute is set, the service isn't protected
# by a permission. 
permission = "android.permission.BIND_JOB_SERVICE"

# The name of the process where the service runs. Normally, all components of an application
# run in the default process created for the application. It has the same name as the
# application package. The <application> element's process attribute can set a different
# default for all components. But a component can override the default with its own process
# attribute, letting you spread your application across multiple processes.
# If the name assigned to this attribute begins with a colon (:), a new process, private to
# the application, is created when it's needed and the service runs in that process.
# If the process name begins with a lowercase character, the service runs in a global process
# of that name, provided that it has permission to do so. This lets components in different
# applications share a process, reducing resource usage. 
process = ":my_service"

# See https://developer.android.com/guide/topics/manifest/meta-data-element
[[package.metadata.android.application.service.meta_data]]
name = "android.accessibilityservice"
# References a XML resource.
resource = "@xml/accessibilityservice"

# Set up reverse port forwarding through `adb reverse`, meaning that if the
# Android device connects to `localhost` on port `1338` it will be routed to
# the host on port `1338` instead. Source and destination ports can differ,
# see the `adb` help page for possible configurations.
[package.metadata.android.reverse_port_forward]
"tcp:1338" = "tcp:1338"

If a manifest attribute is not supported by cargo apk2, feel free to create a PR that adds the missing attribute.

Environmental variables provided by this tool

cargo-apk2 sets environmental variables listed below to be used in build.rs or some custom script.

  • CARGO_APK2_APK_NAME:File name of the currently generating APK.
  • CARGO_APK2_PACKAGE:Package name.
  • CARGO_APK2_ASSETS_DIR:Absolute path of the assets directory.
  • CARGO_APK2_RESOURCES_DIR:Absolute path of the resources directory.
  • CARGO_APK2_CLASSES_DIR:Directory storing compiled Java classes.
  • CARGO_APK2_RUNTIME_LIBS_DIR:Directory storing runtime (dynamic) libraries.
  • CARGO_APK2_JAVA_HOME:Root directory of the Java environment.
  • CARGO_APK2_SDK_HOME:Root directory of the Android SDK.
  • CARGO_APK2_ANDROID_JAR:Path of android.jar corresponding to the current targetSdkVersion.
  • CARGO_APK2_PLATFORM_DIR:Path of platforms/android-<api> corresponding to the current targetSdkVersion.
  • CARGO_APK2_BUILD_TOOLS_VERSION:Version of the Android Build Tools currently being used.
  • CARGO_APK2_MIN_SDK_VERSIONminSdkVersion.
  • CARGO_APK2_TARGET_SDK_VERSIONtargetSdkVersion.
  • CARGO_APK2_ARTIFACT:Output path of the main dynamic library.

These variables can be used in circumstances like automation scripting, resource processing, and Java integration.

About

使用rust构建安卓应用(apk)

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Rust 91.0%
  • Java 4.0%
  • Kotlin 1.7%
  • Scala 1.7%
  • Groovy 1.6%