Bubbles and project layout

A Bubble is Pop’s compilation and visibility unit. A project manifest describes a package, and conventional paths identify its library, executable, tests, examples, and benchmarks.

project/
├── bubble.toml
└── src/
    ├── lib.pop
    ├── main.pop
    └── bin/
        ├── admin.pop
        └── worker/
            └── main.pop

The discovered source roles are:

• src/lib.pop — the package library Bubble;
• src/main.pop — the default binary Bubble;
• src/bin/*.pop — additional flat binaries;
• src/bin/<name>/main.pop — additional directory-based binaries;
• flat files under tests/, examples/, and benchmarks/ — conventional auxiliary Bubbles.

In 0.1.0-rc.6, manifest execution can check, lint, format, build, document, run, test, and benchmark the discovered roles. run still requires one selected binary; test and benchmark selections are explicit when a Package contains multiple candidates.

The manifest

The implemented manifest requires:

[package]
name = "Example.App"
version = "0.1.0"
edition = "2026"

Package names contain dot-separated PascalCase components. Version values use dotted decimal components, and the edition contains decimal digits. Values in the implemented parser are quoted strings.

The [dependencies] section resolves declared local or locked Packages into a verified Bubble graph. Registry transport and toolchain installation are still separate concerns; a manifest never grants visibility beyond a dependency’s public API.

Direct files and projects

pop check file.pop, pop run file.pop, and pop build file.pop --output app compile a direct source entry. pop run --manifestPath bubble.toml uses project discovery. Start with a direct file for experiments; use a manifest when the conventional layout helps organize a program.