Skip to main content

Project layout

A project's folder says where it lives on disk. source-layout says how sources and resources are organised inside that folder. Together with the sources: and resources: arrays, they tell bleep where to find every file it needs to compile your project — without a single absolute path in bleep.yaml.

This page covers the everyday case — one project, one source folder, one resources folder. For Scala cross-builds and sbt-imported layouts, see Source layout in cross-builds and sbt imports.

The project folder​

Every project has a folder — the directory the rest of its paths are anchored to. It is relative to the build root (where bleep.yaml lives), and it defaults to ./${PROJECT_NAME}.

projects:
  myapp:                       # folder defaults to ./myapp/
  greeter:
    folder: ./modules/greeter  # explicit folder override

So a project named myapp lives in ./myapp/ unless told otherwise.

Source layout: how files inside the folder are organised​

source-layout is the rule bleep uses to derive default sources and resources paths inside the project folder. For everyday projects there are four values:

source-layoutWhen you'd use it
kotlinDefault for Kotlin projects.
normalDefault for Scala projects.
javaDefault for plain Java projects.
noneNo defaults at all. Use only sources: / resources:.

Bleep auto-fills source-layout based on what your project compiles. The priority is Kotlin → Scala → Java, so:

  • A project with a kotlin: block gets kotlin layout.
  • A project with a scala: block gets normal layout.
  • A project with neither (Java only) gets java layout.

You can override by setting the field explicitly.

What each layout produces​

Layoutsourcesresources
kotlin<folder>/src/kotlin, <folder>/src/java<folder>/src/resources
normal<folder>/src/scala, <folder>/src/java, plus version-specific paths<folder>/src/resources
java<folder>/src/java<folder>/src/resources
none(none)(none)

The "version-specific" extras under normal only matter for cross-builds — see the appendix.

Notice that none of these have a main/ or test/ segment in them. In bleep, tests are their own project with isTestProject: true, so the test code lives in a separate folder (myapp-test/src/kotlin/), not under myapp/src/test/kotlin/. There is no scope distinction inside a project.

Adding extra paths​

sources: and resources: are additive — bleep takes the union of the layout's paths and whatever you list:

projects:
  myapp:
    sources:
      - ../shared/src/kotlin   # relative to ./myapp/
      - extra-sources

Plain relative paths work for almost everything. For the rare case you need ${BUILD_DIR}, ${PROJECT_DIR}, or a Scala version variable woven into a path, see Path replacements. Don't reach for those if a relative path will do.

If you want to replace the defaults rather than add to them, set source-layout: none and list every path you actually want.

Worked example​

Here's the smallest end-to-end Kotlin build on the docs site, lifted directly from one of bleep's integration tests:

$schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
$version: 1.0.0-M9
jvm:
  name: graalvm-community:25.0.1
projects:
  myapp:
    extends: template-common
    platform:
      mainClass: com.example.MainKt
  myapp-test:
    dependencies:
    - io.kotest:kotest-runner-junit5-jvm:5.8.0
    - org.junit.jupiter:junit-jupiter:5.10.1
    dependsOn: myapp
    extends: template-common
    isTestProject: true
templates:
  template-common:
    kotlin:
      jvmTarget: '25'
      version: 2.3.0
    platform:
      name: jvm

Two Kotlin projects, no folder overrides, no sources overrides. With source-layout: kotlin auto-applied, the actual files live at:

./myapp/src/kotlin/com/example/Main.kt
./myapp-test/src/kotlin/com/example/MainTest.kt

The same shape for Scala (source-layout: normal):

./myapp/src/scala/com/example/Main.scala
./myapp-test/src/scala/com/example/MainTest.scala

That's the whole interaction model: folder picks the directory, source-layout picks the subdirectory pattern, sources and resources add to it.

Where to go next​