Cliff的工作室
如何将rust库封装为Android AAR

前一段时间用Rust实现了一些功能,最近需要将这些实现搬到Android上来跑。这种问题,说简单也简单,就是用JNI(Java Native Interface)实现。但实际做起来,从来就没有那么简单。

工程相关问题

这里希望的是在Android App中使用Rust代码,因此Rust代码必须是library。虽然binary方式也可以运行,但Java只能通过exec调用binary,这种方式只能通过输入输出流来与binary交互,效率低且容易出错,没有太大意义。

工程组织方式

先考虑一下工程应该如何组织。基本上,JNI就是包括两部分:Java实现和对应的lib封装。在Android上,直接调用缺乏灵活性,因此考虑通过jar或aar方式来封装JNI库。这两种方式的区别是:

  1. jar方式可以在普通Java工程(非Android工程)中使用,但通常JNI的Java实现和对应的lib封装是分开来打包的。如果要考虑将lib封装打进jar的话,虽然不是不可行,但是非常麻烦。另外,在我的场景中,由于lib封装的编译必须使用ndk工具链,因此这样的封装也没有太大实际意义(如果lib是ndk编译的,在普通Java工程中也就无法使用了)。
  2. aar方式是Android库的标准实现方式,lib封装可以作为资源打包进去;但这种方式是不能在普通Java工程中使用的。

考虑以上两种方式的区别,aar方式比较适用于我的使用场景。而jar场景比较适用于普通的Java项目,在jar场景下,lib和jar需要分别提交。这里不做深入讨论。

Android AAR独立工程的创建

Android Developers官网上关于AAR工程的创建文档在这里

需要理解的一点是,AAR工程和app工程都是Module。Android Studio创建app工程时,实际是创建了一个根工程,然后创建了一个app module。而AAR module必须在根工程中新增,不能直接创建。

因此,如果想要创建独立的AAR工程,需要先创建一个app工程,然后将app目录删掉,并修改对应的工程根目录下的settings.gradle

Rust库的整合

下一步是创建Rust库并整合进入工程。创建库当然是使用cargo new --lib命令。

由于Rust库是根工程的一部分,我将Rust库放在工程根目录下,跟aar module同级。

整合部分依赖于Mozilla提供的plugin,使用方法参考其README中的Usage,照做即可。

需要注意的一点是,如果需要在emulator上运行,那么可能需要对应的target。例如如果emulator上跑的是x86-64版本的img,那么target需要增加x86-64。另外,考虑到后面可能会使用单元测试,建议加上desktop的target,比如linux-x86-64

Rust库的实现

目前我们有了一个工程,工程里面包含一个AAR Module,和一个rust库。编译之后,rust库会被打包进入生成的aar文件。但目前还没有完成从java到rust的调用。这里需要参考jni crate

文档中主要就注意下面几点:

  1. 实现Java类,需要在rust中实现的方法用native关键字修饰
  2. 通过javah生成c语言header文件,获取其中的函数名定义
  3. 参考jni crate文档实现rust库中的函数,使用第2步获得的函数名定义,crate_type需要是cdylib

为方便下一步进行测试,这里最好先简单实现一个可以调用的接口。

测试代码

在这里测试的目的,是为了使用简单的命令行,来确认工程整体是可以编译和运行的。

Android有两种测试方式,UnitTestInstrumentTest。前者是单元测试,直接在Java虚拟机中运行,不需要Android环境,也不能使用Android API(如果有需求,需要Mock)。后者需要配合Android环境运行(需要虚拟机或实体设备),可以使用Android API。

如果Java部分代码对于Android依赖较多的话,只能使用InstrumentTest。但我这里只有简单使用android.util.Log。因此我选择UnitTest方式。需要以下几部分工作。

Mock实现

在单元测试中,android.jar是空的,所以用到的Android功能都需要Mock。这里是一个简单的android.util.Log实现,放到aar module的src/test/java/android/util/Log.java

package android.util;

import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;

public class Log {
    public static final String ANSI_RESET = "\u001B[0m";
    public static final String ANSI_BLACK = "\u001B[30m";
    public static final String ANSI_RED = "\u001B[31m";
    public static final String ANSI_GREEN = "\u001B[32m";
    public static final String ANSI_YELLOW = "\u001B[33m";
    public static final String ANSI_BLUE = "\u001B[34m";
    public static final String ANSI_PURPLE = "\u001B[35m";
    public static final String ANSI_CYAN = "\u001B[36m";
    public static final String ANSI_WHITE = "\u001B[37m";

    public static int d(String tag, String msg) {
        ZonedDateTime now = ZonedDateTime.now(ZoneOffset.UTC);
        System.out.println("[" + now.format(DateTimeFormatter.ISO_INSTANT) + " " + ANSI_BLUE + "DEBUG" + ANSI_RESET + " " + tag + "] " + msg);
        System.out.flush();
        return 0;
    }

    public static int i(String tag, String msg) {
        ZonedDateTime now = ZonedDateTime.now(ZoneOffset.UTC);
        System.out.println("[" + now.format(DateTimeFormatter.ISO_INSTANT) + " " + ANSI_BLUE + "INFO" + ANSI_RESET + " " + tag + "] " + msg);
        System.out.flush();
        return 0;
    }

    public static int w(String tag, String msg) {
        ZonedDateTime now = ZonedDateTime.now(ZoneOffset.UTC);
        System.out.println("[" + now.format(DateTimeFormatter.ISO_INSTANT) + " " + ANSI_BLUE + "WARN" + ANSI_RESET + " " + tag + "] " + msg);
        System.out.flush();
        return 0;
    }

    public static int e(String tag, String msg) {
        ZonedDateTime now = ZonedDateTime.now(ZoneOffset.UTC);
        System.out.println("[" + now.format(DateTimeFormatter.ISO_INSTANT) + " " + ANSI_BLUE + "ERROR" + ANSI_RESET + " " + tag + "] " + msg);
        System.out.flush();
        return 0;
    }
}

编译问题

在单元测试时,由于运行环境不是android,因此不能使用ndk编译。换句话说,在前面提到的Mozilla插件所涉及的修改中,需要在target中增加对应的desktop的target。我这里对应的是linux-x86-64。这样会在lib库目录下的target/debug生成so文件。

但是,现在有两个问题。第一是测试时不会自动编译rust库;第二是运行时java部分无法加载rust库。前者需要增加task之间的依赖关系,后者需要将编译出来的so所在目录添加到LD_LIBRARY_PATH。具体一点,参考下面对aar目录下的build.gradle的修改,增加了这些内容:

tasks.whenTaskAdded { task ->
    if ((task.name == 'javaPreCompileDebug' || task.name == 'javaPreCompileRelease')) {
        task.dependsOn 'cargoBuild'
    }
    if ((task.name == 'testDebugUnitTest' || task.name == 'testReleaseUnitTest')) {
        // For unit test, we need to add target path to LD_LIBRARY_PATH
        def libpath = '' + projectDir + '/../jni/target/debug/'
        environment 'LD_LIBRARY_PATH', libpath
    }
}

注意:其中的libpath需要根据具体情况修改

运行测试

现在,在aar目录下的src/test中的对应测试代码中加入测试,就可以使用gradle testDebug进行测试了。

JavaDoc

由于这样暴露出来的库看起来是Java库的形式,因此要生成文档的话,可以使用javadoc,具体一点,在aar工程的build.gradle中,加几个task和配置,例如:

// 由于增加的任务都需要classpath,因此加一个配置,将对应的dependency加入这个配置
configurations {
    javadocClasspath
}
dependencies {
    //……
	// 这个例子里,我加入了lombok和jackson的依赖
    javadocClasspath 'org.projectlombok:lombok:1.18.18'
    javadocClasspath group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.12.1'
}

// delombok是将lombok部分展开成为新的源码
task delombok {
    def srcOriginal = 'src/main/java'
    def srcTarget = 'build/intermediates/src_delombok'
    def classpath = configurations.javadocClasspath + project.files(android.getBootClasspath().join(File.pathSeparator))

    inputs.files file( srcOriginal )
    outputs.dir file( srcTarget )

    doLast {
        println "Delombok source from ${srcOriginal} to ${srcTarget}"
        ant.taskdef(name: 'delombok', classname: 'lombok.delombok.ant.Tasks$Delombok', classpath: classpath.asPath)
        ant.delombok(verbose: false, from:srcOriginal, to:srcTarget, classpath: classpath.asPath)
    }
}

// 生成javadoc之前,要先做delombok,否则一些通过lombok生成的方法是不会被加入javadoc的
task javadoc(type: Javadoc, dependsOn: delombok) {
    failOnError false
    def srcDelomboked = 'build/intermediates/src_delombok'
    source = srcDelomboked
    // Default output dir is "build/docs/javadoc", change destinationDir if needed
    classpath = configurations.javadocClasspath + project.files(android.getBootClasspath().join(File.pathSeparator))
    doFirst {
        println "Generate javadoc from delomboked source at ${srcDelomboked}"
    }
}

加入上面配置后,通过gradle javadoc命令,就可以将html版本的javadoc文档输出到build/docs/javadoc目录。

Log问题

关于测试时的Log问题,Java部分需要修改aar工程的build.gradle,允许应用输出,这里给出参考:

android {
      //...
      testOptions {
        unitTests.all {
            testLogging {
                events "passed", "skipped", "failed", "standardOut", "standardError"
                outputs.upToDateWhen {false}
                showStandardStreams = true
            }
        }
    }
}

注意:这里只是android配置中的一段,省略了其他部分

Rust库部分要配合log crate和其他log库实现。由于log只是facade,所以还是需要一个显式的初始化动作。我把初始化放在了一个initLogging函数中,交给Java部分的调用者来决定何时启用库中的log;当然,也可以考虑放在JNI_OnLoad函数中。代码例子如下:

#[cfg(target_os = "android")]
fn initLogging() {
    android_logger::init_once(Config::default().with_min_level(Level::Debug));
}

#[cfg(not(target_os = "android"))]
fn initLogging() {
    Builder::new().filter(None, LevelFilter::Debug).init();
}

基本的工程相关问题,这一部分就已经说完了。剩下的就是实现过程中的一些细节问题了。

实现细节问题

Java -> Rust 的调用/传参/返回

Java部分的调用跟普通类没什么区别。这里仅仅建议做成singleton模式以简化模型。

从java传参到rust时,考虑尽量使用基本数据类型。复杂数据考虑采用json转换成String对象传递。如果是基础类型,那么在rust库中获得的类型是jni::sys::jboolean等基础类型,可以直接使用。如果是String类型,在rust中获得的是jni::objects::JString类型,需要通过jni::JNIEnv转换成rust中的String。参考下面的宏:

macro_rules! try_convert_java_string {
    ($var:ident, $env:ident) => {
        if let Ok(v) = $env.get_string($var) {
            Into::<String>::into(v)
        } else {
            debug!("Failed to convert \"{}\", return false", stringify!($var));
            return false as jboolean;
        }
    };
}

返回时情况类似,如果需要返回java String,需要用env.new_string()生成对象再返回。

Rust -> Java 的调用/传参/返回

有时在rust库中,需要通过回调Java函数来获取一些信息。此时就需要按照以下步骤进行:

  1. 在java实现中,定义用于回调的方法。这里无需考虑方法是public、protected还是private;但static和non-static稍有不同。
  2. 在rust实现中,通过env.call_method()env.call_static_method查询到目标方法并执行,获得返回对象。
  3. 返回对象和Java->Rust调用时传入的参数是一样的处理方式。

多线程问题

在Java -> rust和rust -> Java部分,都存在需要注意的多线程问题。

当Java -> rust时,如果在java vm的子线程中调用,那么rust中拿到的env指针是一个不同的指针。因此不要试图去保存env指针。

当rust -> java时,由于回调必须拥有env指针,而rust中创建的子线程中是没有env指针的,所以必须按照如下顺序操作:

  1. 在JNI_OnLoad函数中,保存获取的JavaVM指针
  2. 在合适的时机,保存回调使用的Java对象
  3. 在需要回调时,先获取保存的JavaVM指针和Java对象,然后:
    1. 通过JavaVM::attach_current_thread()系列函数(建议使用attach_current_thread_as_daemon,细节自查文档)获取env指针。
    2. 按照前面所说的env.call_method()方式回调

Json String在Java和rust代码中的解析方式

都是一句话问题。

Java代码中用Jackson的ObjectMapper。

rust代码中用serde_json::Value。

2021 年 02 月 08 日 09 时 05 分