Skip to content

Phase 2 Android: jniLibs packaging + unified rollup loader plugin#17

Merged
gmaclennan merged 1 commit into
mainfrom
claude/phase-2-android-jnilibs
Apr 28, 2026
Merged

Phase 2 Android: jniLibs packaging + unified rollup loader plugin#17
gmaclennan merged 1 commit into
mainfrom
claude/phase-2-android-jnilibs

Conversation

@gmaclennan

@gmaclennan gmaclennan commented Apr 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

Completes Phase 2 of docs/build-architecture-plan.md — the symmetric Android counterpart to PR #16 (iOS xcframework Embed & Sign). Native .node files now ship as lib<name>__<version>.so under android/src/main/jniLibs/<abi>/, mmap'd from the APK by Bionic's per-app linker namespace at load time. The runtime asset extraction step (copyAssetFolder("nodejs-native/<abi>", ...)) and the legacy rollup-plugin-native-paths.js are gone. The iOS-only addon-loader rollup plugin from #16 is generalised to a single platform-agnostic plugin with per-platform banners.

Detailed plan: docs/phase-2-android-jnilibs-plan.md. One deviation from the original plan: versioned filenames (lib<name>__<version>.so) are adopted from the start instead of deferred — the dep tree already carries multi-version sodium-native (4.3.3 + 5.1.0) and better-sqlite3 (11.10.0 + 12.9.0), surfaced by the iOS Phase 2 work, so the multi-version path is the reference path.

Changes

File What
scripts/build-backend.ts Drops assets/nodejs-native/<abi>/... write; emits lib<name>__<version>.so per (name, version) instance × ABI into jniLibs/<abi>/. Lifts findNodeForArch + androidAbiForArch to top-level helpers shared with the iOS xcframework wrap.
backend/rollup-plugins/rollup-plugin-addon-loader.js (renamed from rollup-plugin-ios-addon-loader.js) Platform-agnostic loader-pattern transform. Two banner exports: iosAddonLoaderBanner, androidAddonLoaderBanner differ only in the process.dlopen argument.
backend/rollup-plugins/rollup-plugin-native-paths.js Deleted.
backend/rollup.config.js Both outputs use the unified plugin; per-platform output.banner.
android/build.gradle jniLibs.srcDirs += 'src/main/jniLibs/', packagingOptions.jniLibs.useLegacyPackaging = false.
android/src/main/AndroidManifest.xml <application android:extractNativeLibs="false">.
android/src/main/java/com/comapeo/core/NodeJSService.kt Drops nodejs-native overlay extraction in start(); removes unused getCurrentABIName external fun, nodeNativeAssetsDir field, NODEJS_NATIVE_ASSETS_DIRNAME const.
android/src/main/cpp/jni-bridge.cpp Removes getCurrentABIName JNI export + CURRENT_ABI_NAME macro (no callers).
.gitignore Adds android/src/main/jniLibs/.

Test plan

Local validation against the running iOS simulator + Android emulator on this commit:

  • iOS simulator (iPhone 16 / iOS 26.2): 4/4 tests pass — CoreManagerSmokeTest, ServiceLifecycleTest, both ComapeoCoreModuleTests. Confirms the rollup plugin rename didn't regress iOS.
  • Android JVM unit tests: BUILD SUCCESSFUL.
  • Android instrumented tests (Pixel 7a API 29 emulator, arm64-v8a): 16 + 15 = 31 tests, 0 failed. Confirms bare-name process.dlopen('lib<key>.so') works end-to-end against the APK mmap region with extractNativeLibs="false".
  • CI Android workflow on emulator runner (pending push).
  • CI iOS workflow simulator + device-build (pending push).

Out of scope (deferred follow-ups)

  • NodeJSService.kt JNI stdio pump drain fix (canonical build-architecture-plan.md §0.4 / §8). Important for diagnostics — uncaught backend exceptions are routinely lost to the pthread_detach race today — but separable from packaging. Recommend its own PR right after this one.
  • iOS pre-release sanity items (real-device runtime test, TestFlight upload).
  • iOS map-tile fetching re-introduction; globalThis.fetch polyfill; maps-stub console.warn.
  • 16 KB page alignment audit (readelf -l | grep LOAD on each shipping .so).

🤖 Generated with Claude Code

@gmaclennan @claude
feat(android): jniLibs + extractNativeLibs=false + unified rollup plugin
9c17bf8 
Phase 2 Android, completing Phase 2 across both platforms. Mirrors the
iOS xcframework work landed earlier on this branch — same shape, same
naming convention, same rollup-plugin loader-pattern transform — only
the runtime-helper banner and the file extension differ.

scripts/build-backend.ts:

  - Replaces the `assets/nodejs-native/<abi>/...` write with
    `android/src/main/jniLibs/<abi>/lib<name>__<version>.so`. One
    `.so` per (name, version) instance × ABI, so multi-version dep
    trees (sodium-native@4.3.3 + @5.1.0, better-sqlite3@11.10.0 +
    @12.9.0) get distinct slots. Reuses `NATIVE_PAIRS` already
    enumerated for the iOS xcframework wrap.
  - Lifts `findNodeForArch(name, version, target)` and
    `androidAbiForArch(arch)` to top-level helpers so iOS and
    Android share them. The iOS xcframework wrap loop is unchanged
    in shape — just calls the lifted helper.

backend/rollup-plugins:

  - Renames `rollup-plugin-ios-addon-loader.js` to
    `rollup-plugin-addon-loader.js`. The loader-pattern transform
    (rewrite `bindings`/`node-gyp-build`/`require.addon` callsites
    to `__loadAddon(name, version)`) is platform-agnostic; only the
    runtime helper banner differs.
  - Adds `androidAddonLoaderBanner` alongside the existing
    `iosAddonLoaderBanner`. Both define `__loadAddon(name, version)`
    with cache key `name + '__' + version`; the only difference is
    the `process.dlopen` argument: bare `lib<key>.so` on Android
    (Bionic linker namespace resolves against APK mmap region), or
    `<NATIVE_LIB_DIR>/<key>.framework/<key>` on iOS.
  - Deletes `rollup-plugin-native-paths.js`. Its job (route
    bare-resolver paths through node_modules/<pkg>/prebuilds/...)
    no longer applies — `.so` files don't live under node_modules
    on Android any more.

backend/rollup.config.js:

  - Both outputs use the unified plugin. Per-platform banners on
    `output.banner`. iOS-specific bits (maps-stub alias) stay
    iOS-only.

android/build.gradle:

  - `jniLibs.srcDirs` adds `'src/main/jniLibs/'` (alongside the
    existing `'libnode/bin/'` for the prebuilt nodejs-mobile
    libnode.so).
  - `packagingOptions { jniLibs { useLegacyPackaging false } }` —
    keeps `.so` files uncompressed and aligned in the APK so
    Bionic can mmap them in place when the manifest disables
    extraction.

android/src/main/AndroidManifest.xml:

  - `<application android:extractNativeLibs="false">`. Pairs with
    `useLegacyPackaging=false` above. Required by the rolled-up
    backend's bare-name `process.dlopen` calls — see canonical
    plan §0.1.

android/src/main/java/com/comapeo/core/NodeJSService.kt:

  - Drops the `copyAssetFolder(nodejs-native/<abi>/, ...)` overlay
    extraction step in `start()`. Native code now lives in the
    APK's `lib/<abi>/` segment, mmap'd at load time. JS bundle
    extraction (`copyAssetFolder(NODEJS_PROJECT_DIRNAME, ...)`)
    stays — the rolled-up `index.mjs` still needs a filesystem
    path to start nodejs-mobile from.
  - Removes the now-unused `getCurrentABIName()` `external fun`
    declaration. `nodeNativeAssetsDir` field, `NODEJS_NATIVE_ASSETS_DIRNAME`
    const both gone.

android/src/main/cpp/jni-bridge.cpp:

  - Removes the JNI-side `getCurrentABIName` function + its
    `registerNatives` entry + the `CURRENT_ABI_NAME` macro. No
    callers — it was only used by the removed asset-overlay step.

.gitignore:

  - Adds `android/src/main/jniLibs/`. Removes the now-stale
    Phase-1 / Phase-2 iOS guard-rail comments — the per-platform
    generated paths are under a single comment block.

iOS sim regression check: 4/4 tests pass (smoke + lifecycle +
ComapeoCoreModule pair). Android emulator + APK-shape verification
land on next CI run.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@gmaclennan gmaclennan merged commit 3c22524 into main Apr 28, 2026
7 checks passed
@gmaclennan gmaclennan deleted the claude/phase-2-android-jnilibs branch April 28, 2026 18:01
This was referenced Apr 28, 2026
Closed
Merged
gmaclennan added a commit that referenced this pull request Apr 28, 2026
@gmaclennan @claude
chore: post-Phase-2 cleanup — comments, plan docs, agents.md (#33)
9f5ee20 
## Summary

Cleanup pass after Phase 2 (PRs #15, #16, #17) landed on `main`.

- **Open follow-up issues** for everything deferred from those PRs:
#19–#32 (Android JNI stdio drain, iOS device smoke test, TestFlight
ritual, fetch polyfill, maps plugin re-introduction, Phase 3 smoke test,
Phase 4 socket-transport shim, IPC backpressure, 16KB page alignment
audit, Android lifecycle parity, `abiFilters`, blobs over UDS, web
platform).
- **Remove implemented plan docs** — `docs/Todos.md`,
`docs/phase-2-android-jnilibs-plan.md`,
`docs/phase-2-xcframework-plan.md`,
`docs/unified-js-bundle-ios-plan.md`. `docs/build-architecture-plan.md`
stays (Phase 3-4 still open) with its inline status banners updated to
point at the merged PRs.
- **Trim history-oriented comments** throughout
`scripts/build-backend.ts`, `backend/`, `ios/`, and `android/`: drop
"Phase 1 wrote X / Phase 2 ships Y" framing, references to the external
validating harness in `digidem/nodejs-mobile-bare-prebuilds`, and
lingering `state.sock` naming in favour of `control.sock`.
- **Refresh `agents.md`** to describe the unified rolled-up backend,
jniLibs/xcframework packaging, and the current test layout. Replace the
regression-test history table with a forward-looking "Open follow-ups"
list pointing at the new issues.

No behaviour changes.

## Test plan

- [x] `tsc --noEmit -p scripts/tsconfig.json` clean (only comment edits
there)
- [ ] CI Android workflow green
- [ ] CI iOS workflow green (simulator + device-build)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@optic-release-automation optic-release-automation Bot mentioned this pull request Jun 22, 2026
Merged
gmaclennan added a commit that referenced this pull request Jun 22, 2026
@gmaclennan
[OPTIC-RELEASE-AUTOMATION] release/v1.0.0-pre.2 (#112)
15131a5 
## Optic Release Automation

This **draft** PR is opened by Github action
[optic-release-automation-action](https://github.com/nearform-actions/optic-release-automation-action).

A new **draft** GitHub release
[v1.0.0-pre.2](https://github.com/digidem/comapeo-core-react-native/releases/tag/untagged-c499977757c9745e56b2)
has been created.

Release author: @gmaclennan

#### If you want to go ahead with the release, please merge this PR.
When you merge:

- The GitHub release will be published

- The npm package with tag pre will be published according to the
publishing rules you have configured



- No major or minor tags will be updated as configured


#### If you close the PR

- The new draft release will be deleted and nothing will change

## What's Changed
* Android Testing Infrastructure & Bug Fixes by @gmaclennan in
#3
* chore: prebuild example/android; harden instrumented tests by
@gmaclennan in
#10
* Integrate @comapeo/core via IPC over Unix sockets by @gmaclennan in
#5
* chore: adjust repo setup by @achou11 in
#12
* chore: minor fixes based on expo-doctor by @achou11 in
#13
* Add iOS support & test infrastructure by @gmaclennan in
#6
* chore: add architecture docs & plans by @gmaclennan in
#11
* update some native deps used in backend by @achou11 in
#14
* iOS Phase 1: unified JS bundle + smoke test (simulator-only) by
@gmaclennan in
#15
* iOS Phase 2: xcframework Embed & Sign for native addons by @gmaclennan
in #16
* Phase 2 Android: jniLibs packaging + unified rollup loader plugin by
@gmaclennan in
#17
* chore: post-Phase-2 cleanup — comments, plan docs, agents.md by
@gmaclennan in
#33
* android: read abiFilters from reactNativeArchitectures (#30) by
@gmaclennan in
#35
* refactor: simplify build-backend.ts; rollup writes directly to native
asset trees by @gmaclennan in
#34
* chore: fix eslint configuration by @achou11 in
#41
* android: audit 16 KB page alignment on every shipped .so by
@gmaclennan in
#43
* Add rootkey persistence and lifecycle state management by @gmaclennan
in #36
* chore: move example app into apps directory by @achou11 in
#18
* refactor: per-component lifecycle state with derived ComapeoState by
@gmaclennan in
#47
* android: fold waitForFile into connect retry loop by @gmaclennan in
#52
* chore: add e2e testing app by @achou11 in
#49
* fix(android): drop setUnlockedDeviceRequired from rootkey wrapper key
by @gmaclennan in
#57
* fix(backend): cache stopping/error frames for late joiners by
@gmaclennan in
#58
* fix(ios-tests): wait for STOPPING before signalling node exit by
@gmaclennan in
#59
* fix(android): drain JNI stdio pumps before returning from node::Start
by @gmaclennan in
#60
* Sentry integration: Phase 1 + Phase 2a + Phase 2b by @gmaclennan in
#54
* feat(backend): polywasm-backed undici on iOS, re-enable maps plugin by
@gmaclennan in
#62
* ci: drop unreliable Android emulator snapshot caching by @gmaclennan
in #64
* feat(sentry): land Phase 3 — backend loader + RPC tracing by
@gmaclennan in
#63
* fix(ios-tests): serialise STOPPING/STOPPED observers in
testFullLifecycleStateTransitions by @gmaclennan in
#71
* use npm list instead of custom traversal to get native module versions
by @achou11 in
#70
* feat(sentry): land Phases 6 + 7a — Android exit reasons & iOS
MetricKit app-exit telemetry by @gmaclennan in
#72
* fix(sentry): make exit telemetry lossless and stop cross-process
clobbering by @gmaclennan in
#84
* chore(e2e): add e2e tests on browserstack via Maestro by @achou11 in
#56
* feat(sentry): migrate to @sentry/react-native v8; exit telemetry as
Application Metrics by @gmaclennan in
#73
* Map server integration by @gmaclennan in
#86
* chore(deps): upgrade to Expo SDK 56 (React Native 0.85) by @gmaclennan
in #87
* chore(ci): add release workflow by @gmaclennan in
#90
* chore: fix npm script and release build script by @gmaclennan in
#91
* chore(pack): don't try to package build files by @gmaclennan in
#92
* fix: start fastify listening by @gmaclennan in
#93
* perf(backend): switch bundler from rollup to rolldown by @gmaclennan
in #94
* fix(ci): ignore-scripts in ios npm installs by @gmaclennan in
#96
* fix(ci): replace --ignore-scripts with npm strict-allow-scripts
allowlist by @gmaclennan in
#106
* feat(config): let the consuming app supply the default project config
by @gmaclennan in
#95
* chore(release): merge prerelease branch. by @gmaclennan in
#110

## New Contributors
* @achou11 made their first contribution in
#12

**Full Changelog**:
https://github.com/digidem/comapeo-core-react-native/commits/v1.0.0-pre.2

<!--

<release-meta>{"id":342868678,"version":"v1.0.0-pre.2","npmTag":"pre","opticUrl":"https://optic-zf3votdk5a-ew.a.run.app/api/generate/"}</release-meta>
-->
@gmaclennan gmaclennan added the feature New feature (changelog) label Jun 22, 2026
@optic-release-automation optic-release-automation Bot mentioned this pull request Jun 22, 2026
Merged
gmaclennan added a commit that referenced this pull request Jun 22, 2026
@gmaclennan
[OPTIC-RELEASE-AUTOMATION] release/v1.0.0-pre.2 (#133)
20a3454 
## Optic Release Automation

This **draft** PR is opened by Github action
[optic-release-automation-action](https://github.com/nearform-actions/optic-release-automation-action).

A new **draft** GitHub release
[v1.0.0-pre.2](https://github.com/digidem/comapeo-core-react-native/releases/tag/untagged-352a6c41c12fd02dec37)
has been created.

Release author: @gmaclennan

#### If you want to go ahead with the release, please merge this PR.
When you merge:

- The GitHub release will be published

- The npm package with tag pre will be published according to the
publishing rules you have configured



- No major or minor tags will be updated as configured


#### If you close the PR

- The new draft release will be deleted and nothing will change

<!-- Release notes generated using configuration in .github/release.yml
at 7fe80b4 -->

## What's Changed
### 🚀 Features
* Integrate @comapeo/core via IPC over Unix sockets by @gmaclennan in
#5
* Add iOS support & test infrastructure by @gmaclennan in
#6
* iOS Phase 1: unified JS bundle + smoke test (simulator-only) by
@gmaclennan in
#15
* iOS Phase 2: xcframework Embed & Sign for native addons by @gmaclennan
in #16
* Phase 2 Android: jniLibs packaging + unified rollup loader plugin by
@gmaclennan in
#17
* android: read abiFilters from reactNativeArchitectures (#30) by
@gmaclennan in
#35
* Add rootkey persistence and lifecycle state management by @gmaclennan
in #36
* Sentry integration: Phase 1 + Phase 2a + Phase 2b by @gmaclennan in
#54
* feat(backend): polywasm-backed undici on iOS, re-enable maps plugin by
@gmaclennan in
#62
* feat(sentry): land Phase 3 — backend loader + RPC tracing by
@gmaclennan in
#63
* feat(sentry): land Phases 6 + 7a — Android exit reasons & iOS
MetricKit app-exit telemetry by @gmaclennan in
#72
* feat(sentry): migrate to @sentry/react-native v8; exit telemetry as
Application Metrics by @gmaclennan in
#73
* Map server integration by @gmaclennan in
#86
* feat(config): let the consuming app supply the default project config
by @gmaclennan in
#95
### 🐛 Bug Fixes
* fix(android): drop setUnlockedDeviceRequired from rootkey wrapper key
by @gmaclennan in
#57
* fix(backend): cache stopping/error frames for late joiners by
@gmaclennan in
#58
* fix(ios-tests): wait for STOPPING before signalling node exit by
@gmaclennan in
#59
* fix(android): drain JNI stdio pumps before returning from node::Start
by @gmaclennan in
#60
* fix(ios-tests): serialise STOPPING/STOPPED observers in
testFullLifecycleStateTransitions by @gmaclennan in
#71
* fix(sentry): make exit telemetry lossless and stop cross-process
clobbering by @gmaclennan in
#84
* fix: start fastify listening by @gmaclennan in
#93
* fix(ci): ignore-scripts in ios npm installs by @gmaclennan in
#96
* fix(ci): replace --ignore-scripts with npm strict-allow-scripts
allowlist by @gmaclennan in
#106
* fix(release): stop `npm pack --dry-run` leaking dry-run into backend
install by @gmaclennan in
#129
### ⚡ Performance
* perf(backend): switch bundler from rollup to rolldown by @gmaclennan
in #94
### ⬆️ Dependencies
* update some native deps used in backend by @achou11 in
#14
* chore(deps): upgrade to Expo SDK 56 (React Native 0.85) by @gmaclennan
in #87
### 🏗️ Maintenance
* Android Testing Infrastructure & Bug Fixes by @gmaclennan in
#3
* chore: prebuild example/android; harden instrumented tests by
@gmaclennan in
#10
* chore: adjust repo setup by @achou11 in
#12
* chore: minor fixes based on expo-doctor by @achou11 in
#13
* chore: add architecture docs & plans by @gmaclennan in
#11
* chore: post-Phase-2 cleanup — comments, plan docs, agents.md by
@gmaclennan in
#33
* refactor: simplify build-backend.ts; rollup writes directly to native
asset trees by @gmaclennan in
#34
* chore: fix eslint configuration by @achou11 in
#41
* android: audit 16 KB page alignment on every shipped .so by
@gmaclennan in
#43
* chore: move example app into apps directory by @achou11 in
#18
* refactor: per-component lifecycle state with derived ComapeoState by
@gmaclennan in
#47
* android: fold waitForFile into connect retry loop by @gmaclennan in
#52
* chore: add e2e testing app by @achou11 in
#49
* ci: drop unreliable Android emulator snapshot caching by @gmaclennan
in #64
* use npm list instead of custom traversal to get native module versions
by @achou11 in
#70
* chore(e2e): add e2e tests on browserstack via Maestro by @achou11 in
#56
* chore(ci): add release workflow by @gmaclennan in
#90
* chore: fix npm script and release build script by @gmaclennan in
#91
* chore(pack): don't try to package build files by @gmaclennan in
#92
* chore(release): merge prerelease branch. by @gmaclennan in
#110
* ci(e2e): retry BrowserStack builds on infra-class flakes by
@gmaclennan in
#113
### Other Changes
* ci: derive changelog labels from PR titles + add Dependabot by
@gmaclennan in
#114

## New Contributors
* @achou11 made their first contribution in
#12
* @optic-release-automation[bot] made their first contribution in
#112

**Full Changelog**:
https://github.com/digidem/comapeo-core-react-native/commits/v1.0.0-pre.2

<!--

<release-meta>{"id":342970724,"version":"v1.0.0-pre.2","npmTag":"pre","opticUrl":"https://optic-zf3votdk5a-ew.a.run.app/api/generate/"}</release-meta>
-->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

feature New feature (changelog)

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@gmaclennan