@tokamakdev/platform-android-arm64 0.1.1-beta.127 → 0.1.1-beta.129

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,13 +1,130 @@
1
1
  #!/usr/bin/env bash
2
2
  set -euo pipefail
3
3
 
4
+ # The CLI runs the entrypoint from the pack root.
5
+ pack=$PWD
6
+
7
+ # The build tools of apps and of describing plugins. Coroutines are the version
8
+ # androidx.lifecycle brings, so plugins' coroutines add no code.
9
+ agp_version=8.7.3
10
+ kotlin_version=2.1.0
11
+ coroutines_version=1.9.0
12
+
13
+ # Describes the methods PLUGIN/android/Exports.kt exports into
14
+ # OUTPUT/description.json, with the dispatch that serves them,
15
+ # OUTPUT/Exports.generated.kt. A JVM unit test of the plugin, compiled with
16
+ # the plugin API and its dependencies, runs the registration and reflects on
17
+ # the methods it lists.
18
+ describe() {
19
+ local plugin=$1 output=$2
20
+ if [[ $# -ne 3 || $3 != android ]]; then
21
+ echo "Android plugins run on android, not ${*:3}" >&2
22
+ exit 2
23
+ fi
24
+ local sdk=${ANDROID_HOME:-${ANDROID_SDK_ROOT:-}}
25
+ if ! command -v gradle > /dev/null || ! command -v java > /dev/null || [[ ! -d "$sdk/platforms" ]]; then
26
+ echo "Describing an Android plugin needs Gradle, Java and the Android SDK" >&2
27
+ exit 69
28
+ fi
29
+ # Global, for the exit trap.
30
+ temporary=$(mktemp -d "${TMPDIR:-/tmp}/tokamak-describe.XXXXXX")
31
+ trap 'rm -rf "$temporary"' EXIT
32
+ local module=$temporary/plugin
33
+ mkdir -p "$module"
34
+ cat > "$temporary/settings.gradle" <<'EOF'
35
+ pluginManagement {
36
+ repositories {
37
+ google()
38
+ mavenCentral()
39
+ gradlePluginPortal()
40
+ }
41
+ }
42
+ dependencyResolutionManagement {
43
+ repositories {
44
+ google()
45
+ mavenCentral()
46
+ }
47
+ }
48
+ rootProject.name = 'tokamak-describe'
49
+ include ':plugin'
50
+ EOF
51
+ cat > "$temporary/build.gradle" <<EOF
52
+ plugins {
53
+ id 'com.android.library' version '$agp_version' apply false
54
+ id 'org.jetbrains.kotlin.android' version '$kotlin_version' apply false
55
+ }
56
+ EOF
57
+ printf '%s\n' 'android.useAndroidX=true' > "$temporary/gradle.properties"
58
+ cat > "$module/build.gradle" <<EOF
59
+ plugins {
60
+ id 'com.android.library'
61
+ id 'org.jetbrains.kotlin.android'
62
+ }
63
+
64
+ android {
65
+ namespace 'tokamak.describe'
66
+ compileSdk 35
67
+ // The plugin's own files, so compiler errors name them.
68
+ sourceSets {
69
+ main.kotlin.srcDirs = ['$pack/native-shell/plugin', '$plugin/android']
70
+ test.kotlin.srcDirs = ['$pack/describer']
71
+ }
72
+ defaultConfig {
73
+ minSdk $(<"$pack/build/min-sdk")
74
+ }
75
+ compileOptions {
76
+ sourceCompatibility JavaVersion.VERSION_17
77
+ targetCompatibility JavaVersion.VERSION_17
78
+ }
79
+ testOptions {
80
+ unitTests.returnDefaultValues = true
81
+ unitTests.all {
82
+ systemProperty 'tokamak.output', '$output'
83
+ systemProperty 'tokamak.classes', layout.buildDirectory.dir('tmp/kotlin-classes/debug').get().asFile.path
84
+ outputs.upToDateWhen { false }
85
+ }
86
+ }
87
+ }
88
+
89
+ kotlin {
90
+ jvmToolchain(17)
91
+ compilerOptions {
92
+ freeCompilerArgs.add('-Xjvm-default=all')
93
+ }
94
+ }
95
+
96
+ // The dispatch describing regenerates.
97
+ tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
98
+ exclude '**/Exports.generated.kt'
99
+ }
100
+
101
+ def manifest = new groovy.json.JsonSlurper().parse(file('$plugin/tokamak-plugin.json'))
102
+ dependencies {
103
+ implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:$coroutines_version'
104
+ (manifest.platforms?.android?.dependencies ?: []).each { implementation it }
105
+ testImplementation 'junit:junit:4.13.2'
106
+ testImplementation 'org.jetbrains.kotlin:kotlin-reflect:$kotlin_version'
107
+ // android.jar's org.json is stubs; the describer writes JSON with the reference implementation.
108
+ testImplementation 'org.json:json:20250517'
109
+ }
110
+ EOF
111
+ gradle --quiet --project-dir "$temporary" :plugin:testDebugUnitTest
112
+ if [[ -f "$output/error" ]]; then
113
+ cat "$output/error" >&2
114
+ rm "$output/error"
115
+ exit 1
116
+ fi
117
+ }
118
+ if [[ $# -ge 1 && $1 == describe ]]; then
119
+ describe "${@:2}"
120
+ exit
121
+ fi
122
+
4
123
  if [[ $# -ne 3 || $1 != build ]]; then
5
- echo "usage: entrypoint build INPUT OUTPUT" >&2
124
+ echo "usage: entrypoint build INPUT OUTPUT | entrypoint describe PLUGIN OUTPUT android" >&2
6
125
  exit 2
7
126
  fi
8
127
 
9
- # The CLI runs the entrypoint from the pack root.
10
- pack=$PWD
11
128
  input=$2
12
129
  output=$3
13
130
  metadata=$input/metadata
@@ -147,7 +264,7 @@ cp -R "$input/app/." "$assets/"
147
264
  link_runtime
148
265
  cp -R "$pack/native-shell/app/." "$kotlin/"
149
266
  cp -R "$pack/native-shell/plugin/." "$plugin_api/src/main/kotlin/"
150
- cat > "$plugin_api/build.gradle" <<'EOF'
267
+ cat > "$plugin_api/build.gradle" <<EOF
151
268
  plugins {
152
269
  id 'com.android.library'
153
270
  id 'org.jetbrains.kotlin.android'
@@ -157,9 +274,8 @@ android {
157
274
  namespace 'com.tokamak.runtime.plugin'
158
275
  }
159
276
 
160
- // Plugins mark code that needs a later API level with RequiresApi, which lint checks.
161
277
  dependencies {
162
- api 'androidx.annotation:annotation:1.9.1'
278
+ api 'org.jetbrains.kotlinx:kotlinx-coroutines-android:$coroutines_version'
163
279
  }
164
280
  EOF
165
281
 
@@ -187,32 +303,24 @@ raw_names=" "
187
303
  for plugin in "$input/plugins"/*/; do
188
304
  plugin_id=$(basename "$plugin")
189
305
  class=$(cat "$plugin/class" 2>/dev/null || true)
190
- # A plugin whose native code is its generated bindings alone has no class.
191
- if [[ -n "$class" || ! -d "$plugin/bindings" ]]; then
192
- if [[ ! "$class" =~ $kotlin_class ]]; then
193
- echo "plugin '$plugin_id' has invalid android class '$class'" >&2
194
- exit 1
195
- fi
196
- printf ' %s(app.host("%s")),\n' "$class" "$plugin_id" >> "$registry"
306
+ if [[ ! "$class" =~ $kotlin_class ]]; then
307
+ echo "plugin '$plugin_id' has invalid android class '$class'" >&2
308
+ exit 1
309
+ fi
310
+ # A plugin that exports methods runs behind the dispatch generated for it.
311
+ if [[ -f "$plugin/native/Exports.kt" ]]; then
312
+ class=${class}Dispatch
197
313
  fi
314
+ printf ' %s(app.host("%s")),\n' "$class" "$plugin_id" >> "$registry"
198
315
  module=$plugin_modules/$plugin_id
199
316
  mkdir -p "$module/src/main/kotlin"
200
- # `tok bindings` names the generated class com.tokamak.bindings.<id>.Bindings, with - as _.
201
- for source in "$plugin/bindings"/*.kt; do
202
- printf ' com.tokamak.bindings.%s.Bindings(app.host("%s")),\n' "${plugin_id//-/_}" "$plugin_id" >> "$registry"
203
- cp "$source" "$module/src/main/kotlin/TokamakBindings.kt"
204
- done
205
- for source in "$plugin/sources"/*; do
206
- case "$source" in
207
- *.kt)
208
- cp "$source" "$module/src/main/kotlin/$(basename "$source")"
209
- ;;
210
- *)
211
- echo "Android plugin source must be Kotlin: $source" >&2
212
- exit 1
213
- ;;
214
- esac
215
- done
317
+ if [[ -d "$plugin/native" ]]; then
318
+ while IFS= read -r -d '' source; do
319
+ relative=${source#"$plugin/native/"}
320
+ mkdir -p "$module/src/main/kotlin/$(dirname "$relative")"
321
+ cp "$source" "$module/src/main/kotlin/$relative"
322
+ done < <(find "$plugin/native" -name '*.kt' -print0)
323
+ fi
216
324
  if [[ -f "$plugin/manifest" ]]; then
217
325
  cp "$plugin/manifest" "$module/src/main/AndroidManifest.xml"
218
326
  fi
@@ -274,9 +382,9 @@ done
274
382
 
275
383
  cat > "$project/build.gradle" <<EOF
276
384
  plugins {
277
- id 'com.android.application' version '8.7.3' apply false
278
- id 'com.android.library' version '8.7.3' apply false
279
- id 'org.jetbrains.kotlin.android' version '2.1.0' apply false
385
+ id 'com.android.application' version '$agp_version' apply false
386
+ id 'com.android.library' version '$agp_version' apply false
387
+ id 'org.jetbrains.kotlin.android' version '$kotlin_version' apply false
280
388
  }
281
389
 
282
390
  subprojects {
@@ -0,0 +1,221 @@
1
+ package com.tokamak.runtime
2
+
3
+ import java.io.File
4
+ import kotlin.reflect.KClass
5
+ import kotlin.reflect.KParameter
6
+ import kotlin.reflect.KType
7
+ import kotlin.reflect.full.allSupertypes
8
+ import kotlin.reflect.full.findAnnotation
9
+ import kotlin.reflect.full.primaryConstructor
10
+ import kotlin.reflect.full.starProjectedType
11
+ import kotlinx.coroutines.flow.Flow
12
+ import org.json.JSONArray
13
+ import org.json.JSONObject
14
+ import org.junit.Test
15
+
16
+ /** A failure to describe the plugin, which the message explains. */
17
+ class DescribeError(message: String) : Exception(message)
18
+
19
+ /**
20
+ * Runs the plugin's registration, which the compiled classes in `tokamak.classes` include, and
21
+ * describes the methods it exports and the events it emits into `tokamak.output`:
22
+ * `description.json`, and the dispatch that serves them, `Exports.generated.kt`. A failure's
23
+ * message goes to `error` there.
24
+ */
25
+ class Describe {
26
+ @Test
27
+ @Suppress("UNCHECKED_CAST")
28
+ fun describe() {
29
+ val output = File(System.getProperty("tokamak.output"))
30
+ try {
31
+ val registration = registration(File(System.getProperty("tokamak.classes")))
32
+ val plugin = registration::class.allSupertypes.first { it.classifier == TokamakExports::class }
33
+ .arguments.single().type?.classifier as KClass<*>
34
+ val exporter = TokamakExporter<TokamakPlugin>()
35
+ (registration as TokamakExports<TokamakPlugin>).exports(exporter)
36
+ val exports = exports(exporter, plugin)
37
+ val events = exporter.events.map { Event(it.name, it.doc, it.type.starProjectedType, it.reply?.starProjectedType) }
38
+ output.resolve("description.json").writeText(description(exports, events, Types()))
39
+ output.resolve("Exports.generated.kt").writeText(dispatch(plugin, exports, events))
40
+ } catch (error: DescribeError) {
41
+ output.resolve("error").writeText(error.message ?: "")
42
+ }
43
+ }
44
+ }
45
+
46
+ /** An exported method as the registration lists it and Kotlin declares it. */
47
+ internal class Export(
48
+ val kind: String,
49
+ val name: String,
50
+ val doc: String,
51
+ val overflow: TokamakOverflow,
52
+ val parameters: List<KParameter>,
53
+ val returns: KType,
54
+ val suspends: Boolean,
55
+ )
56
+
57
+ /** An event as the registration lists it, with the types its listeners receive and reply with. */
58
+ internal class Event(val name: String, val doc: String, val type: KType, val reply: KType?)
59
+
60
+ /** The one object in [classes] that implements [TokamakExports]. */
61
+ private fun registration(classes: File): TokamakExports<*> {
62
+ val loader = Describe::class.java.classLoader
63
+ val registrations = classes.walk()
64
+ .filter { it.extension == "class" }
65
+ .map { it.relativeTo(classes).path.removeSuffix(".class").replace(File.separatorChar, '.') }
66
+ .mapNotNull { name -> runCatching { Class.forName(name, false, loader) }.getOrNull() }
67
+ .filter { TokamakExports::class.java.isAssignableFrom(it) && !it.isInterface }
68
+ .toList()
69
+ val registration = registrations.singleOrNull()
70
+ ?: throw DescribeError("android/Exports.kt declares one object that implements TokamakExports, not ${registrations.size}")
71
+ return registration.kotlin.objectInstance as? TokamakExports<*>
72
+ ?: throw DescribeError("${registration.simpleName} is an object")
73
+ }
74
+
75
+ /** The methods [exporter] lists, which are [plugin]'s. */
76
+ private fun exports(exporter: TokamakExporter<TokamakPlugin>, plugin: KClass<*>): List<Export> =
77
+ exporter.exports.map { export ->
78
+ val method = export.method
79
+ val receiver = method.parameters.firstOrNull()
80
+ if (receiver?.kind != KParameter.Kind.INSTANCE || receiver.type.classifier != plugin) {
81
+ throw DescribeError("${method.name} is not a method of ${plugin.simpleName}")
82
+ }
83
+ if (export.kind == "stream" && method.isSuspend) {
84
+ throw DescribeError("${plugin.simpleName}.${method.name} returns its Flow without suspending")
85
+ }
86
+ Export(export.kind, method.name, export.doc, export.overflow, method.parameters.drop(1), method.returnType, method.isSuspend)
87
+ }
88
+
89
+ /** The description of [exports] and [events], which records the data classes and enums they use in [types]. */
90
+ private fun description(exports: List<Export>, events: List<Event>, types: Types): String {
91
+ val methods = exports.map { export ->
92
+ val context = "${export.name}:"
93
+ buildMap {
94
+ put("name", export.name)
95
+ put("kind", export.kind)
96
+ if (export.doc.isNotEmpty()) put("doc", export.doc)
97
+ if (export.parameters.isNotEmpty()) {
98
+ put("parameters", export.parameters.map { mapOf("name" to it.name, "type" to types.describe(it.type, "$context ${it.name}")) })
99
+ }
100
+ when (export.kind) {
101
+ "call" -> put("returns", types.describe(export.returns, "$context result"))
102
+ "stream" -> put("returns", types.describe(element(export.returns, context), "$context values"))
103
+ }
104
+ if (export.overflow == TokamakOverflow.DROP_OLDEST) put("overflow", "dropOldest")
105
+ }
106
+ }
107
+ val described = events.map { event ->
108
+ val context = "event ${event.name}:"
109
+ buildMap {
110
+ put("name", event.name)
111
+ if (event.doc.isNotEmpty()) put("doc", event.doc)
112
+ put("type", types.describe(event.type, context))
113
+ event.reply?.let { put("reply", types.describe(it, "$context reply")) }
114
+ }
115
+ }
116
+ val description = buildMap {
117
+ put("methods", methods)
118
+ if (described.isNotEmpty()) put("events", described)
119
+ put("types", types.described.values.toList())
120
+ }
121
+ return JSONObject(description).toString() + "\n"
122
+ }
123
+
124
+ /** The data classes and enums the description names. */
125
+ private class Types {
126
+ private val classes = mutableMapOf<String, KClass<*>>()
127
+
128
+ /** The descriptions of the named types, by name. */
129
+ val described = sortedMapOf<String, Any>()
130
+
131
+ /** The JSON description of [type], whose [context] errors name. Placement rules are tok's to check. */
132
+ fun describe(type: KType, context: String): Any {
133
+ val classifier = type.classifier as? KClass<*> ?: throw DescribeError("$context $type is not a type the Worker can pass")
134
+ val argument = { index: Int -> type.arguments[index].type ?: throw DescribeError("$context $type has a star projection") }
135
+ val value: Any = when (classifier) {
136
+ String::class -> "string"
137
+ Boolean::class -> "boolean"
138
+ Int::class, Long::class, Short::class, Byte::class, Double::class, Float::class -> "number"
139
+ Unit::class -> "void"
140
+ ByteArray::class -> "bytes"
141
+ Any::class -> "json"
142
+ JSONObject::class -> mapOf("record" to "json")
143
+ JSONArray::class -> mapOf("array" to "json")
144
+ TokamakPluginBody::class -> "body"
145
+ TokamakReference::class -> "reference"
146
+ List::class -> mapOf("array" to describe(argument(0), context))
147
+ Map::class -> {
148
+ if (argument(0).classifier != String::class) throw DescribeError("$context maps the Worker passes have String keys")
149
+ mapOf("record" to describe(argument(1), context))
150
+ }
151
+ else -> mapOf("named" to named(classifier, context))
152
+ }
153
+ return if (type.isMarkedNullable) mapOf("optional" to value) else value
154
+ }
155
+
156
+ /** The name of [type], which the first use describes; recording it first ends recursion. */
157
+ private fun named(type: KClass<*>, context: String): String {
158
+ val name = type.simpleName ?: throw DescribeError("$context $type has no name")
159
+ if (!type.java.isEnum && !type.isData && !type.isSealed) {
160
+ throw DescribeError("$context ${type.qualifiedName} is not a data class, an enum class or a sealed type")
161
+ }
162
+ val existing = classes.putIfAbsent(name, type)
163
+ if (existing == null) {
164
+ described[name] = declaration(type, name)
165
+ } else if (existing != type) {
166
+ throw DescribeError("two types the Worker passes are named $name")
167
+ }
168
+ return name
169
+ }
170
+
171
+ private fun declaration(type: KClass<*>, name: String): Any =
172
+ when {
173
+ type.java.isEnum -> mapOf("name" to name, "values" to constants(type))
174
+ type.isSealed -> buildMap {
175
+ put("name", name)
176
+ put("alternatives", forms(type).map { alternative(it, "$name.${it.name}:") })
177
+ type.findAnnotation<TokamakTag>()?.let { put("tag", it.field) }
178
+ }
179
+ else -> mapOf("name" to name, "fields" to fields(type).map { mapOf("name" to it.name, "type" to describe(it.type, "$name.${it.name}:")) })
180
+ }
181
+
182
+ /** The [form]'s name, and the type of its value: a value class's value, or a data class. */
183
+ private fun alternative(form: Form, context: String): Map<String, Any> {
184
+ val value = form.value
185
+ return when {
186
+ form.isName -> mapOf("name" to form.name)
187
+ value != null && (value.type.classifier as? KClass<*>)?.isData == true ->
188
+ throw DescribeError("$context a data class is a form itself, not a value class's value")
189
+ value != null -> mapOf("name" to form.name, "type" to describe(value.type, context))
190
+ form.type.isData -> mapOf("name" to form.name, "type" to mapOf("named" to named(form.type, context)))
191
+ else -> throw DescribeError("$context ${form.type.qualifiedName} is not an object, a data class or a value class")
192
+ }
193
+ }
194
+ }
195
+
196
+ /** A form of a sealed type: a subclass, named with a lowercase first letter. */
197
+ internal class Form(val name: String, val type: KClass<*>) {
198
+ /** Whether the form is an object, whose JSON is its name. */
199
+ val isName = type.objectInstance != null
200
+
201
+ /** A value class's value, which is the form's JSON. */
202
+ val value: KParameter? = if (type.isValue) fields(type).single() else null
203
+ }
204
+
205
+ /** The forms of the sealed type [type], by name, as reflection lists no declaration order. */
206
+ internal fun forms(type: KClass<*>): List<Form> =
207
+ type.sealedSubclasses.map { subclass ->
208
+ val name = subclass.simpleName ?: throw DescribeError("${type.simpleName} has a form without a name")
209
+ Form(name.replaceFirstChar { it.lowercase() }, subclass)
210
+ }.sortedBy { it.name }
211
+
212
+ /** A data class's properties: its primary constructor's parameters. */
213
+ internal fun fields(type: KClass<*>): List<KParameter> = type.primaryConstructor?.parameters.orEmpty()
214
+
215
+ /** An enum class's constants, read without running its initializer. */
216
+ private fun constants(type: KClass<*>): List<String> = type.java.declaredFields.filter { it.isEnumConstant }.map { it.name }
217
+
218
+ private fun element(type: KType, context: String): KType {
219
+ if (type.classifier != Flow::class) throw DescribeError("$context a stream returns a Flow")
220
+ return type.arguments.single().type ?: throw DescribeError("$context $type has a star projection")
221
+ }