kmp-stellar-sdk: Instructions file for Codex

AGENTS.md

This file is for everyone who changes the Kotlin Multiplatform Stellar SDK, people and agents alike. It holds what the tree does not show: the commands, what "done" means, which files are generated, the conventions that differ from Kotlin and Gradle defaults, and the limits of a change. When this file and a file it names disagree, the named file wins, and the pull request that changes the fact updates this file. Users of the SDK read README.md and docs/; agents that build on the SDK read the skill under skills/.

Commands

Setup is described in CONTRIBUTING.md. The Kotlin, Android, and JVM target versions are in build.gradle.kts and stellar-sdk/build.gradle.kts, the Gradle version in gradle/wrapper/gradle-wrapper.properties; the CI matrix in the tests workflow names the tested JDKs.

./gradlew :stellar-sdk:jvmTest -PexcludeIntegrationTests --no-daemon
./gradlew :stellar-sdk:jvmTest -PexcludeIntegrationTests --no-daemon --tests 'com.soneso.stellar.sdk.unitTests.KeyPairTest'
./gradlew :stellar-sdk:koverHtmlReportJvmOnly :stellar-sdk:koverXmlReportJvmOnly -PexcludeIntegrationTests --no-daemon
python3 tools/coverage/coverage_summary.py --min 90
./gradlew :stellar-sdk:jsNodeTest -PexcludeIntegrationTests --no-daemon
./gradlew :stellar-sdk:macosArm64Test -PexcludeIntegrationTests --no-daemon
./gradlew :stellar-sdk:testDebugUnitTest -PexcludeIntegrationTests --no-daemon
./gradlew :stellar-sdk:verifyTestNamespaces --no-daemon

• Pass -PexcludeIntegrationTests to every test task; without it the integration tests run against testnet. check, build and test without it run them too, and check also runs the browser, iOS simulator, macOS x64, and Android tasks and Android Lint, more than 160 tasks.
• The JVM unit suite (about 10,600 tests) takes 35 to 70 seconds, the JS suite 60 to 90 seconds, and the Android suite two to four minutes. The macOS suite takes about 30 seconds with a warm Kotlin/Native cache and about three minutes when a source change recompiles and links the test binary. The JVM and JS suites run with the network blocked once the dependencies are cached; they need loopback sockets.
• The build cache can answer a test task from cache without running a test. --rerun forces execution when you need the evidence.
• The Android tasks, check and the documentation build need the Android SDK location: ANDROID_HOME or sdk.dir in the gitignored local.properties. The iOS simulator tests need -PexcludeIntegrationTests because the simulator rejects the testnet certificate chain.
• verifyTestNamespaces fails a test outside the unitTests or integrationTests packages; CI does not run it.
• The coverage script counts a line as covered only when all of its branches are covered; Kover measures the JVM target only.
• No separate Kotlin linter or formatter is configured; kotlin.code.style=official in gradle.properties sets the style, and Android Lint runs through check.
• The API documentation builds with ./gradlew :stellar-sdk:dokkaGenerateHtml --no-daemon in about three minutes into stellar-sdk/build/dokka/html/; the Pages workflow copies that output to the gitignored docs/api/latest/ and publishes it from main. The package descriptions Dokka reads are in stellar-sdk/dokka/packages.md.
• ./gradlew :stellar-sdk:assemble -x test -x allTests builds every target without tests; it needs Xcode and the Android SDK and takes minutes.
• The demos demo/ and smart-account-demo/ are Gradle modules in settings.gradle.kts that CI does not build; a change to an API they use is compiled against them locally.