Zipline
This library streamlines using Kotlin/JS libraries from Kotlin/JVM and Kotlin/Native programs. It makes it possible to do continuous deployment of mobile apps, just like we do for servers and web applications.
It'd be simpler to do continuous deploys via the App Store & Play Store! But that process is too slow. Even if we could release via these channels every day, we can’t guarantee that user’s devices will take the updates immediately. For Cash App we support apps that haven’t been updated for a full year.
(Looking for Duktape Android?)
QuickJS
This library uses the QuickJS embeddable JavaScript engine to execute Kotlin/JS. It's included in this library and supports both Android and the JVM.
QuickJS Usage
try (QuickJs engine = QuickJs.create()) {
Log.d("Greeting", engine.evaluate("'hello world'.toUpperCase();").toString());
}
For long-lived usage feel free to call QuickJs.create() and retain the returned instance for as long as you need. Be sure to call .close() when you are done to avoid leaking native components.
Supported Java Types
Currently, the following Java types are supported when interfacing with JavaScript:
booleanandBooleanintandInteger- as an argument only (not a return value) when calling JavaScript from Java.doubleandDoubleStringvoid- as a return value.
Object is also supported in declarations, but the type of the actual value passed must be one of the above or null.
Calling Java from JavaScript
You can provide a Java object for use as a JavaScript global, and call Java functions from JavaScript!
Example
Suppose we wanted to expose the functionality of Okio's ByteString in JavaScript to convert hex-encoded strings back into UTF-8. First, define a Java interface that declares the methods you would like to call from JavaScript:
interface Utf8 {
String fromHex(String hex);
}
Next, implement the interface in Java code (we leave the heavy lifting to Okio):
Utf8 utf8 = new Utf8() {
@Override public String fromHex(String hex) {
return okio.ByteString.decodeHex(hex).utf8();
}
};
Now you can set the object to a JavaScript global, making it available in JavaScript code:
// Attach our interface to a JavaScript object called Utf8.
engine.set("Utf8", Utf8.class, utf8);
String greeting = (String) engine.evaluate(""
// Here we have a hex encoded string.
+ "var hexEnc = 'EC9588EB8595ED9598EC84B8EC9A9421';\n"
// Call out to Java to decode it!
+ "var message = Utf8.fromHex(hexEnc);\n"
+ "message;");
Log.d("Greeting", greeting);
Calling JavaScript from Java
You can attach a Java interface to a JavaScript global object, and call JavaScript functions directly from Java! The same Java types are supported for function arguments and return values as the opposite case above.
Example
TODO fix this example, as it no longer works with QuickJS! You should still be able to understand what is going on, though.
Imagine a world where we don't have Okio's ByteString. Fortunately, there's a [Duktape builtin][dukdec] that allows us to convert hex-encoded strings back into UTF-8! We can easily set up a proxy that allows us to use it directly from our Java code. First, define a Java interface that declares the JavaScript methods you would like to call:
interface Utf8 {
String fromHex(String hex);
}
Next, we define a global JavaScript object in Duktape to connect to:
// Note that Duktape.dec returns a Buffer, we must convert it to a String return value.
engine.evaluate(""
+ "var Utf8 = {\n"
+ " fromHex: function(v) { return String(Duktape.dec('hex', v)); }\n"
+ "};");
Now you can connect our interface to the JavaScript global, making it available in Java code:
// Connect our interface to a JavaScript object called Utf8.
Utf8 utf8 = engine.get("Utf8", Utf8.class);
// Call into the JavaScript object to decode a string.
String greeting = utf8.fromHex("EC9588EB8595ED9598EC84B8EC9A9421");
Log.d("Greeting", greeting);
Download
This project supports both Android and Java. On Java only Linux and macOS are currently supported.
repositories {
mavenCentral()
}
dependencies {
implementation 'app.cash.zipline:zipline:0.1.0'
}
This library is provided as a "fat" .aar with native binaries for all available architectures. To reduce your binary size, use ABI filtering/splitting when building an APK and/or enable Android App Bundles.
Snapshots of the development version are available in Sonatype's snapshots repository.
repository {
mavenCentral()
maven {
url 'https://oss.sonatype.org/content/repositories/snapshots/'
}
}
dependencies {
implementation 'app.cash.zipline:zipline:1.0.0-SNAPSHOT'
}
Building
For Android
$ ./gradlew :quickjs:android:build
The build system will automatically cross-compile the native library to all applicable ABIs and create the fat .aar in quickjs/android/build/outputs/aar/.
This will not run the tests. You must have a working device or emulator connected at which point you can explicitly run them.
$ ./gradlew :quickjs:android:connectedCheck
For the JVM
First, build the native library for your host OS:
$ cmake -S quickjs/jvm/ -B build/jni/ -DQUICKJS_VERSION="$(cat quickjs/common/native/quickjs/VERSION)"
$ cmake --build build/jni/ --verbose
Next, copy the resulting binary into the resources of the JVM project:
$ mkdir -p quickjs/jvm/src/main/resources/
$ cp -v build/jni/libquickjs.* quickjs/jvm/src/main/resources/
Finally, build the platform-specific .jar and run the tests:
$ ./gradlew :quickjs:jvm:build
The .jar will be available in quickjs/jvm/build/libs/.
License
Copyright 2015 Square, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Note: The included C code from QuickJS is licensed under MIT.
Duktape
This repository used to host an Android-specific packaging of the Duktape engine. We have changed to using QuickJS with exactly the same features and API. The Duktape history is still present in this repo as are the release tags. Available versions are listed on Maven central.
5 Dec 8, 2022
3 Jun 18, 2022
5 Dec 23, 2022
479 Dec 25, 2022
187 Jan 9, 2023
64 Dec 29, 2022
28 Oct 17, 2022
1 Jan 9, 2022
2 Jun 26, 2022
1 Jan 28, 2022
14 Nov 5, 2022
19 Sep 8, 2022
2 Mar 31, 2022
994 Dec 28, 2022
3 Dec 6, 2022
2 Nov 10, 2022
13 Dec 16, 2022
18 Nov 24, 2022