Scripts and source generation

Bleep models exactly two ways to extend the build, both as first-class concepts in bleep.yaml:

• Bleep scripts — regular Java / Kotlin / Scala programs you invoke as bleep subcommands.
• Source generation scripts — programs that emit code or resources for another project, run automatically before compilation, with hashing and atomic failure.

That's the entire extension surface. There is no plugin lifecycle, no preCompile hook, no Compile / packageBin / mappings += … to learn. The build follows the build graph; everything else is just code you write.

Why these are core concepts

Across years of building on the JVM, almost every "useful build extension" people end up writing in Maven / Gradle / sbt / Mill collapses into one of two shapes:

1. Generate code from something the build can see — a schema, a protobuf descriptor, a build version string, an OpenAPI spec. Inspect, generate, keep compiling. Sourcegen is this slot.
2. Run a program after the build has produced its artifacts — publish them, sign them, ship them, lint them, package them, post a release note. Scripts are this slot.

Bleep models exactly those two as first-class — and refuses everything else. Almost every other "build mechanism" you've met on the JVM — phase injection, autoplugins, scope axes, custom configurations, Plugin<Project> registration ceremonies — is ceremony around one of those two shapes, dressed up in a DSL. By naming them directly, bleep skips the dressing.

The win isn't only ergonomic. It's that a script is a regular program: it has a main, you debug it with breakpoints, you unit-test it, you depend on any library on the JVM, and the bleep runtime gives you a typed handle on the resolved build model. There is no privileged layer of magic dust between you and the JVM.

When to use which

You want to…	Use
Publish artifacts, sign a release, post to Slack on green CI	Bleep script
Run a custom linter, check licenses, audit deps	Bleep script
Generate .java / .kt / .scala from a schema or spec	Source generation script
Stamp a build version into a generated Constants file	Source generation script
Anything where the output of your code is consumed by compile	Source generation script
Anything where you invoke it manually or from CI	Bleep script

The dividing line is whether compile needs the output. If it does, you want sourcegen — bleep runs your generator on demand, hashes the inputs, and reruns when they change. Otherwise it's a plain script.

Where to go from here

• Bleep scripts — the BleepScript API, classpath isolation, IDE debugging, and the framework flags bleep prepends when forking your script.
• Source generation scripts — the BleepCodegenScript API, the sourcegen: field, the invalidation model, and the temp-directory-then-sync dance that guarantees no half-generated state survives a failure.
• Write your first script — the language-specific scaffolding tutorials (Java · Kotlin · Scala).