PdfKmp: Instructions file for Claude Code

CLAUDE.md

Repository conventions and build commands for AI agents (Claude Code, etc.) working on the PdfKmp codebase itself.

Reading PdfKmp to use it as a library? Check AGENTS.md (universal AI guide) or .claude/skills/pdfkmp/SKILL.md (Claude Code slash command) instead.

Looking for the human-facing tour? See README.md.

---

Project

PdfKmp is an open-source Kotlin Multiplatform PDF generator targeting Android, iOS, and Desktop (JVM — macOS, Windows, Linux). Published to Maven Central as io.github.conamobiledev:pdfkmp.

The library is built around a single closed sealed PdfNode tree authored via a Compose-style DSL. Layout is performed in commonMain (MeasuredNode), and rendering is dispatched to platform-specific PdfCanvas implementations:

• Android backend — android.graphics.pdf.PdfDocument + Canvas (AndroidPdfCanvas).
• iOS backend — UIGraphicsBeginPDFContextToData + Core Graphics (IosPdfCanvas).
• JVM / Desktop backend — Apache PdfBox (JvmPdfCanvas / JvmPdfDriver). Pure-Java, no native libraries; embeds subset TrueType fonts for vector text, builds axial/radial PDF shadings for gradients, and writes real link annotations + a populated info dictionary. The PdfBox dependency lives only in the jvmMain source set.
• Common test backend — FakePdfDriver / FakePdfCanvas in commonTest records every draw call as a sealed DrawCall so the entire pipeline can be exercised end-to-end without native APIs.

Every text glyph and shape is emitted as a vector path — no rasterisation. Output stays sharp at any zoom level.

Build commands

# Canonical test surface — exercises common + the iOS platform layer
./gradlew :pdfkmp:iosSimulatorArm64Test

# JVM / Desktop test surface — exercises common + the PdfBox backend
# end-to-end (SamplesSmokeTest re-renders every sample; JvmBackendTest
# re-parses + rasterises the output). Fast; no simulator needed.
./gradlew :pdfkmp:jvmTest

# Library — all platform artefacts (Android aar + iOS frameworks + JVM jar)
./gradlew :pdfkmp:assemble

# Library — single-platform builds
./gradlew :pdfkmp:linkDebugFrameworkIosArm64
./gradlew :pdfkmp:linkDebugFrameworkIosSimulatorArm64
./gradlew :pdfkmp:jvmJar

# Sample apps
./gradlew :sample:installDebug                     # Android, on connected device
# iOS sample: open iosApp/iosApp.xcodeproj in Xcode and Run

# Publishing — all four publishable modules ship together; release them in lock-step.
# Maven Central releases normally go through GitHub: publishing a Release triggers the
# publish.yml workflow, which runs the command below for you on a macOS runner. Run it by
# hand ONLY as a local/fallback path, and NEVER for a version you also publish a GitHub
# Release for — both call publishAndReleaseToMavenCentral, so the second fails on a
# duplicate version. See the Publishing checklist below.
./gradlew :pdfkmp:publishToMavenLocal :pdfkmp-compose-resources:publishToMavenLocal :pdfkmp-viewer:publishToMavenLocal :pdfkmp-markdown:publishToMavenLocal              # local install
./gradlew :pdfkmp:publishAndReleaseToMavenCentral :pdfkmp-compose-resources:publishAndReleaseToMavenCentral :pdfkmp-viewer:publishAndReleaseToMavenCentral :pdfkmp-markdown:publishAndReleaseToMavenCentral  # Maven Central (fallback; CI does this on Release)