Development¶
Building and testing¶
The Makefile wraps the common Gradle tasks; make help lists them all.
make build # compile every target and the doc examples, lint, check the ABI; no tests
make tests # kotlinter + detekt + ABI check + every test this host can run
make jvm-tests # the JVM tests only, the quickest loop
make js-tests # the tests on Node.js (js and wasmJs)
make native-tests # the native tests this host supports
make docker-linux-tests # the linuxX64 and linuxArm64 tests in Docker containers
make platform-tests # the JVM, Node.js, native and Docker Linux tests in one run, without lint
make test-jdk JDK=17 # run the JVM tests on one JDK, as CI's matrix does
make all-tests # tests + the JDK matrix + coverage floors + Docker Linux tests + live tests
make abi-update # rewrite the API dumps in api/ after an intended API change (macOS only)
make lint # kotlinter + detekt only
make zizmor # audit the GitHub Actions workflows and dependabot.yml with zizmor
make format # auto-format Kotlin sources with ktlint
make kdocs # API docs in build/dokka/html
make coverage # Kover HTML + XML coverage reports
make example # run the example against the live API (needs TYPESAFE_API_KEY)
make hotdog-example # run the hot dog image example against the live API (needs TYPESAFE_API_KEY)
make live-tests # smoke tests and probes against the live API (needs TYPESAFE_API_KEY)
make versions # list the outdated dependencies, plugins and Gradle
make versions-all # the full dependency report, up-to-date entries included
To run a single test class:
- Checks.
make testsruns kotlinter (ktlint), detekt, the ABI check, and the Kotest suite on every platform the host can run: the JVM, Node.js (js and wasmJs), and the native targets (macOS and the iOS simulator on a Mac, linuxX64 on Linux). CI runs the rest, on a macOS and a Windows runner, except iosX64's tests, which need an Intel Mac and run nowhere: iosX64 is compiled and published, but never tested. The tvOS and watchOS simulator tests run on a Mac that has a simulator device for them (Xcode installs neither by default) and are skipped otherwise; CI fails instead of skipping them. - Linux tests anywhere.
make docker-linux-testslinks the linuxX64 and linuxArm64 test binaries and runs each in a Docker container of its own architecture, so a Mac can run the Linux tests too. It is the only place linuxArm64's tests run.JEV4K_LIVE=1 make docker-linux-testsadds the live probes. - API dumps.
api/jev4k.api(the JVM surface, Java callers included) andapi/jev4k.klib.api(every other target) record the public API, andmake testsfails if it changes. After an intended change, runmake abi-updateon a Mac, where every target's klib is known to compile into a complete dump, and commit the new dumps. - JDK coverage. The JVM tests run on the build toolchain by default. CI also runs them on JDK 17, 21 and 25,
since jev4k ships Java 17 bytecode and compiling against the 17 API doesn't prove it behaves there.
make test-jdk JDK=17reproduces one of those rows, andmake all-testsruns every test target there is. - Coverage.
make coverage-openbuilds the Kover report and opens it;make coverage-verifychecks the line and branch floors. CI's build job checks the same floors, which are the coverage gate, and uploads the report to Codecov, whose statuses only report. - Workflow audits.
make zizmorruns zizmor over the GitHub Actions workflows anddependabot.yml(brew install zizmorfirst). Its online audits, which catch a known-vulnerable action or a pinned SHA that isn't a commit of its action, useGH_TOKENor the gh CLI's login, and are skipped without either. CI runs the same audits: a pull request fails on any finding, while pushes tomasterand a weekly run report to the repository's code scanning alerts. - No traffic leaves the machine in unit tests. They exercise the client through Ktor's
MockEngine, apart from five tests that drive the real CIO engine against loopback servers (a timeout, an untrusted certificate, a body cut short, an oversized declared body and an unparseable response), and one test per platform that dials a loopback port nothing listens on, to check how that platform's default engine reports a refused connection. - Live tests are opt-in. They run only when
JEV4K_LIVE=1, whichmake live-testssets. The JVM smoke tests also needTYPESAFE_API_KEY, and fail, naming it, when it's missing; the probes that run on every platform send an invalid key and a 1 ms timeout, so they spend no tokens. .envsupplies the key. Copy.env.exampleto.env(gitignored) and setTYPESAFE_API_KEY. Gradle loads it into the JVM test and example tasks, somake exampleand the JVM smoke tests need nothing exported in your shell. The js, wasmJs and native test tasks see only the shell's environment.
An index for agents¶
The site publishes an llms.txt at its root, following the
llmstxt.org convention: a short description of the library followed by an annotated link
to every page. Point a coding agent at https://jev4k.com/llms.txt and it can find the rest.
Project layout¶
| Path | Contents |
|---|---|
src/commonMain/kotlin/com/pambrose/jev4k |
the library, shared by every platform |
src/jvmMain, src/nativeMain, … |
per-platform code: BlockingJev, the default engines, getenv |
src/commonTest/kotlin/com/pambrose/jev4k |
the Kotest tests that run on every platform |
src/jvmTest/kotlin/com/pambrose/jev4k |
the JVM-only tests (MockK, blocking, live smoke), both examples |
src/jvmTest/kotlin/website |
the code examples used by this site |
src/jvmTest/java/website |
the Java example used by this site |
api/ |
the public API dumps checked by make tests |
website/jev4k |
this documentation site |
jev-docs/ |
a compressed copy of TypeSafe's documentation |
This site¶
The site is built with Zensical from website/jev4k:
make site # serve these docs at http://localhost:8000, rebuilding on change
make site-build # build the static site into website/jev4k/site, with KDocs under /kdocs
make check-site # report newer versions of the site's Python dependencies
make upgrade-site # upgrade them
Publishing¶
The site is published to GitHub Pages at https://jev4k.com/ by .github/workflows/docs.yml. On every pull request
and push to master it builds the site from the locked website/uv.lock in strict mode, builds the KDocs with Dokka
and copies them under /kdocs: the same steps as make site-build. It deploys the result only when a release is
published, or when run by hand from the Actions tab, so the site never shows a version that isn't on Maven Central
yet. The workflow restores nothing from a cache and installs a pinned uv, so neither an entry written by another run nor
a new uv release can change what gets published. On a release tag, the KDocs' source links open that tag instead of
master, as the published javadoc jars' do.
The repository needs one setting before the first deploy: under Settings → Pages → Build and deployment, set Source to GitHub Actions. After a failed deploy, re-run just the failed deploy job; the build job's artifact is reused.
The custom domain¶
The site answers on jev4k.com rather than pambrose.github.io/jev4k, so its URLs carry no path prefix. Two things
keep that working:
docs/CNAMEholds the bare domain. Zensical copies it verbatim intosite/, and GitHub Pages reads the domain from the deployed artifact — a site published by Actions can otherwise lose the domain set under Settings → Pages.- DNS points the apex at GitHub's Pages servers: four
Arecords (185.199.108.153through185.199.111.153), fourAAAArecords (2606:50c0:8000::153through2606:50c0:8003::153), andwwwas aCNAMEtopambrose.github.io.
Links that leave the site — llms.txt, the README, the release checklist — are absolute, so they name jev4k.com
directly and have to be updated together if the domain ever changes.
Code examples¶
Code examples aren't written into the pages. They live in src/jvmTest/kotlin/website as ordinary Kotlin, with the
Java example in src/jvmTest/java/website, so they compile against the real API and pass the same lint checks as
the rest of the code. A page includes a region of a file with a snippet directive:
That includes the region of NoulExamples.kt fenced by a pair of comment markers, a start:basic marker and an
end:basic marker, dedented. (The markers use the same --8<-- prefix as the directive; see any file in
src/jvmTest/kotlin/website.) The site's zensical.toml sets check_paths, so a reference to a missing file fails
the build. Non-Kotlin snippets, such as shell commands, live in .txt files next to them.
The examples are compiled with the test sources, but they aren't tests, and nothing runs them.