Skip to main content

Your First Bleep Project

This tutorial walks you through scaffolding a small Java project with bleep, running it, running its tests, and importing the project into IntelliJ IDEA.

Other languages: Kotlin → · Scala →

Prerequisites​

Step 1: Create the project​

mkdir my-first-bleep-project
cd my-first-bleep-project
bleep new myapp --lang java

bleep new writes a complete, ready-to-run workspace: a bleep.yaml, a myapp project with a hello-world Main, and a myapp-test project wired up with JUnit 5.

Step 2: What got generated​

The build file:

$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.Main
  myapp-test:
    dependencies: org.junit.jupiter:junit-jupiter:5.10.1
    dependsOn: myapp
    extends: template-common
    isTestProject: true
templates:
  template-common:
    platform:
      name: jvm

What each part does:

  • $schema — gives your editor autocomplete and validation
  • $version — the bleep version this build was authored against
  • jvm.name — bleep downloads and manages this JVM for you
  • projects.myapp — the main project; mainClass is what bleep run invokes
  • projects.myapp-test — the test project, marked isTestProject: true (separate output directory, test-only dependencies) and depending on myapp so test code can reach myapp classes
  • templates.template-common — bleep auto-infers a template for the shared platform.name: jvm settings; both projects extend it

The main source, myapp/src/java/com/example/Main.java:

package com.example;

public class Main {
  public static String greet(String name) {
    return "Hello, " + name + "!";
  }

  public static void main(String[] args) {
    System.out.println(greet("World"));
  }
}

The test, myapp-test/src/java/com/example/MainTest.java:

package com.example;

import static org.junit.jupiter.api.Assertions.assertEquals;

import org.junit.jupiter.api.Test;

class MainTest {
  @Test
  void greetsByName() {
    assertEquals("Hello, World!", Main.greet("World"));
  }
}

Step 3: Run it​

bleep run myapp

The first run downloads the JVM and warms the build server; subsequent runs are near-instant.

Hello, World!

Step 4: Run the tests​

bleep test myapp-test

bleep compiles myapp-test, then runs its JUnit 5 suite.

Step 5: Add a dependency​

Java dependencies use a single colon : between groupId, artifactId, and version. To add SLF4J, edit bleep.yaml:

projects:
  myapp:
    extends: template-common
    dependencies:
      - org.slf4j:slf4j-api:2.0.9
      - org.slf4j:slf4j-simple:2.0.9
    platform:
      mainClass: com.example.Main

Heads up: Scala libraries use :: (double colon) — that's a Scala-only shorthand for adding the Scala version suffix to the artifact ID. For Java libraries, always use a single :.

Then rerun bleep run myapp — bleep resolves the new dependency on the fly.

Step 6: Open it in your IDE​

bleep setup-ide

setup-ide writes a BSP configuration any BSP-aware editor can consume.

IntelliJ IDEA​

Open → select the project directory. IntelliJ detects the BSP configuration and imports in about a second. Don't use Import Project, and don't import as a Maven or Gradle project — bleep speaks BSP directly. This is the smoothest path for Java projects.

Both Community and Ultimate editions work; BSP support is built in to both. If your IntelliJ install ships with a corporate Maven plugin set as the default, you may need to disable it for this project so it doesn't try to take over the import.

VS Code with Metals​

Install the Metals extension and open the project folder. Metals detects the BSP server automatically. Metals is Scala-focused but its BSP integration handles Java sources too; for Java-only projects IntelliJ is usually the more polished choice.

Project structure​

my-first-bleep-project/
├── bleep.yaml
├── myapp/
│   └── src/
│       └── java/
│           └── com/
│               └── example/
│                   └── Main.java
└── myapp-test/
    └── src/
        └── java/
            └── com/
                └── example/
                    └── MainTest.java

Each project in bleep.yaml maps to a directory with src/java/ (or src/kotlin/, or src/scala/) underneath.

Coming from Maven? Bleep uses src/java/ rather than src/main/java/ because there is no src/test/java/ to contrast with — tests live in their own sibling project (myapp-test) rather than under a test/ subtree. Same files, shorter paths.

Next steps​