Write Your First Script (Scala)

This page walks through the Scala flow for adding a script to your build. For what a script is and why bleep models scripts as a core concept, see Scripts and source generation.

The bleep API for scripts is bleepscript.* — a pure-Java library that Scala consumes through standard Java interop. (Bleep's internal bleep.* Scala API is not part of the user surface.)

Other languages: Java → · Kotlin →

Prerequisites

• A working bleep project (see Your First Project (Scala))
• Scala 3

Step 1: Add a scripts project

The scripts project depends on bleepscript (Java) — note the single : since bleepscript is a Java artifact, not a Scala-cross-versioned one — and is registered under the top-level scripts: section.

$schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
$version: 1.0.0-M9
jvm:
  name: graalvm-community:25.0.1
projects:
  myapp:
    platform:
      name: jvm
      mainClass: myapp.Main
    scala:
      version: 3.8.3
  scripts:
    dependencies:
      - build.bleep:bleepscript:${BLEEP_VERSION}
    platform:
      name: jvm
    scala:
      version: 3.8.3
scripts:
  hello:
    main: scripts.HelloScript
    project: scripts

Key points:

• ${BLEEP_VERSION} is interpolated by bleep to your installed version.
• The scripts project sets scala.version: 3.8.3 to match the surrounding bleep build's Scala version. Bumping bleep usually means bumping this in lockstep.
• The Scala class compiles to scripts.HelloScript (no $ suffix because it's a class, not a Scala object).

Step 2: Write the script

Extend bleepscript.BleepScript and implement run:

package scripts

import bleepscript.{BleepScript, Commands, Started}

import scala.jdk.CollectionConverters.*

class HelloScript extends BleepScript("hello") {
  override def run(started: Started, commands: Commands, args: java.util.List[String]): Unit = {
    val projectCount = started.build.explodedProjects.size
    started.logger.info(s"This build has $projectCount projects")
    args.asScala.toList match {
      case Nil => started.logger.info("Hello, world!")
      case xs  => started.logger.info(s"Hello, ${xs.mkString(" ")}!")
    }
  }
}

Notes:

• We use class HelloScript rather than object HelloScript so the class inherits BleepScript's static main method via standard JVM inheritance — Scala objects don't expose inherited statics on the forwarder class.
• The constructor takes the script name: extends BleepScript("hello").
• args is java.util.List[String] from the Java API. Convert with args.asScala.toList (or use directly via Java collection ops).

Step 3: Run it

bleep hello

This build has 2 projects
Hello, world!

bleep hello Alice

This build has 2 projects
Hello, Alice!

Where to go from here

• Bleep scripts (concept) — the full BleepScript API. From Scala you can drop () on no-arg Java getters; everything else reads as plain interop.
• Source generation scripts — for scripts whose output is consumed by compile.
• Java script tutorial — same API, different language.