docs(native-cpu): document JVM-only consumption + shadow-jar caveat#579
Merged
michalharakal merged 1 commit intodevelopfrom Apr 30, 2026
Merged
docs(native-cpu): document JVM-only consumption + shadow-jar caveat#579michalharakal merged 1 commit intodevelopfrom
michalharakal merged 1 commit intodevelopfrom
Conversation
Adds a "Consuming this module" section to NativeKernelProvider's
class kdoc covering the two gotchas a downstream consumer hits
when wiring skainet-backend-native-cpu into a KMP project for
the first time:
1. The module ships only a `jvm()` Kotlin target — no klib
variants for Native / JS / Wasm. KMP consumers MUST put the
dep in `jvmMain.dependencies`, never in `commonMain`. The
wrong placement triggers "Couldn't resolve dependency
'sk.ainet.core:skainet-backend-native-cpu' in 'commonMain'
for all target platforms" warnings on every non-JVM target.
Plain `kotlin("jvm")` modules use the regular `dependencies`
block.
2. Shadow-jar consumers using `mergeServiceFiles()` on
com.gradleup.shadow:9.4.x silently lose the
NativeKernelProviderFactory entry from the merged
META-INF/services/...KernelProvider file. The fat JAR ends up
running the priority-50 Panama path even though the native
classes + .so live in the JAR. Cross-references the doLast
workaround in `kllama-cli` (SKaiNET-transformers) that
rebuilds the union.
Also re-words the staged-rollout cursor: previously called PR 5
"this commit" — accurate when first written, but stale now that
all 5 rollout PRs have shipped.
Pure documentation; no code changes; tests still 27/27 green
on jvmTest.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a "Consuming this module" section to
NativeKernelProvider's class kdoc capturing two gotchas a downstream consumer hits when wiringskainet-backend-native-cpuinto a KMP project for the first time. Pure documentation — no code changes, tests still green (:skainet-backends:skainet-backend-native-cpu:jvmTest27/27).Two gotchas covered
JVM-only: the module ships only a
jvm()target — no klib variants. KMP consumers must put the dep injvmMain.dependencies, never incommonMain(the wrong placement triggers "Couldn't resolve dependency 'sk.ainet.core:skainet-backend-native-cpu' in 'commonMain' for all target platforms" on every non-JVM target). Plainkotlin("jvm")modules use the normaldependenciesblock.Shadow-jar
mergeServiceFiles()bug: oncom.gradleup.shadow:9.4.xthe mergedMETA-INF/services/sk.ainet.backend.api.kernel.KernelProvidersilently loses theNativeKernelProviderFactoryentry when bothskainet-backend-cpuandskainet-backend-native-cpuare on the classpath. Fat JAR runs Panama priority-50 even though native classes + .so are bundled. Cross-references the workingdoLastworkaround inkllama-cli(SKaiNET-transformers PR Bump com.android.library from 8.12.1 to 8.12.2 #88).Also fixed
The staged-rollout cursor in the kdoc previously said "PR 5 (this commit)" — accurate when first written but stale now that all 5 PRs have shipped. Re-worded.
Test plan
:skainet-backends:skainet-backend-native-cpu:jvmTest— 27/27 (no behavior change)🤖 Generated with Claude Code