# razves

> Where the bytes and the time in a Kotlin/Native binary went, by Kotlin package and by the klib it came from, out of one symbol table read with no external tool. A CLI and a Gradle plugin whose size budget prints what moved.

Page: https://kotlin.website/razves

## Why it exists

`bloaty` will tell you that `kfun:io.ktor.server.engine#embeddedServer(...)` is 4,112 bytes. `perf`
will tell you the same mangled symbol was on the stack. Both are true and neither is actionable.
[razves](https://github.com/youndie/razves) turns bytes **and samples** into the units a Kotlin
developer can act on — the package, and the klib the package came from — out of one symbol table, and
then lets a build fail when the binary grows.

It reads ELF and Mach-O itself, with no subprocess: not `llvm-nm`, not `bloaty`, not `strip`. The
Kotlin/Native toolchain ships none of them.

## What it says

Every byte of the file is charged to exactly one row, and the rows add up to the file size. Three
things are the whole design:

- **`unattributed` is a row**, never a remainder folded into something else.
- **Coverage sits next to every section**, because a conclusion about `.rodata` drawn from 87 % of it
  is a different claim from one drawn from all of it.
- **A package two klibs both declare reads `<ambiguous>`** rather than being assigned to whichever
  was found first.

The same holds for time: a program links the `:sampler` module, runs, and writes raw addresses that
razves names afterwards. What runs inside your process is a C signal handler and a fixed ring buffer —
no symbol read, no allocation on the sampled path. The handler is C because a Kotlin one hangs:
3 runs in 10 at 100 Hz, 8 in 10 at 1 kHz. The profile also exports as pprof, with Kotlin names.

## The gate is the point

A report is interesting once; what gets installed is the build that goes red. Against a committed
baseline the gate prints **what moved**, by origin and by section, rather than "the binary grew
7.8 %" — the kind of message that gets the gate commented out the first week it fires.

```kotlin
// settings.gradle.kts: maven("https://reposilite.kotlin.website/snapshots") in pluginManagement
plugins {
    kotlin("multiplatform")
    id("io.github.youndie.razves") version "0.1.0.<run>"
}

binarySize {
    budget = 25.MiB            // the release binary, the one that goes in the image
    deltaPerChange = 3.percent
}
```

The budget is the **release** binary's, because the debug one is a different order of size —
28,580,560 bytes against 9,227,448 for the same module. The tasks are `sizeReport…`,
`sizeBaselineWrite…`, `sizeDiff…` and `sizeBudgetCheck…`, the last in `check`, one set per executable.
The latest version is in
[maven-metadata.xml](https://reposilite.kotlin.website/snapshots/io/github/youndie/razves/io.github.youndie.razves.gradle.plugin/maven-metadata.xml).

Or as a CLI, on any binary:

```bash
razves report app.kexe --klibs ~/.gradle/caches/modules-2 --klibs ~/.konan/…/klib
razves diff before.json after.json
```

## What the measurements found

On six real Kotlin/Native binaries:

- **The runtime is a fixed cost of about 40 KB** — 37,889 to 40,871 bytes across a 43× range of file
  size. "The runtime is 17.6 % of this binary" means the binary does almost nothing.
- **The floor is 496,232 bytes**: one `println`, one dependency.
- **Kotlin is a minority of a large release binary** — 36–40 % of the attributed bytes in one real
  service. The majority is statically linked C, OpenSSL through `ktor-client-curl`.
- **The symbol table is 19–27 % of the file**, in every one of the six.
- **`_ZN…` is mostly Rust, not C++.** Reading it as C++ charges the runtime 31 times what it is.

## Before you trust a row

- **Inlined code is charged to the caller**, so the stdlib share is understated. No total moves.
- **Data attributes worse than code** — `.rodata` coverage was 40.7 % on the measured subject.
- **Mach-O sizes include padding**, so razves refuses to diff ELF against Mach-O.
- **It cannot profile an event loop that does not retry `EINTR`**: Ktor's CIO engine on Kotlin/Native
  dies the moment sampling starts. Profile such a program from outside, with `perf`.
