Build and run a single file¶

2 min read

Use dream for a standalone .dream file. Use Dreamer for projects with packages, project settings, and generated launchers.

dream run hello.dream
dream build hello.dream
dream run hello.dream -- first second

The first command builds and runs the file. The second only builds it. The third passes arguments to the program. With no file, Dream uses the entry file from the nearest dream.toml.

Common commands¶

Command	Purpose
`dream build file.dream`	Build without starting the program
`dream run file.dream`	Build and run on your computer
`dream test tests/`	Build a test project's `@test` functions into one runner and run it (`--node` for Node)
`dream fmt src/`	Format source files in place
`dream fmt --check src/`	Check formatting without changing source
`dream debug-adapter`	Start the service used by an editor's debugger
`dream --help`	List current commands and options
`dream --version`	Show the installed version

Choose output and build settings¶

Option	Purpose
`--release`	Build an optimized version
`--release -O0` through `-O4`, `-Os`, `-Oz`	Choose the release optimization setting; requires `--release`
`--release -O`	Use size optimization when no level follows
`-g`, `--debug-info`	Include debugger information and favor stepping through source and inspecting locals
`--release --perf-symbols`	Include source and function names for profiling while keeping release optimizations
`-o path`, `--output path`	Choose an output path
`-v`, `--verbose`	Show more build progress
`--relocatable`	Put required native libraries beside the program for sharing
`--crate-type lib` or `bin`	Choose a library or runnable program
`--release --profile`, `--release --use-profile[=path]`	Record or use measurements to improve native builds

Debug builds (no --release) always compile without optimization so they can count allocations and print the exit-time leak report; passing -O, --profile or --use-profile without --release is an error. Release builds contain no allocation tracking.

Native output normally goes under target/debug/ or target/release/. Browser output goes under target/web/. Build and run explains profile-guided builds. Library output explains exported libraries.

Use --perf-symbols for sampling profiles. It requires --release and cannot be combined with -g; it emits optimized source/function information without debugger local preservation. Both settings participate in build-cache identity.

Browser and Node¶

Use --web or --node to build the program and its corresponding launcher support. These select WebAssembly output and imply --runtime. --wasm requests WebAssembly output without that generated support.

--runtime-target native, web, or node selects the availability rules checked for your code; it is separate from a platform target. Read integration before creating your own launcher.

Another platform¶

--target takes a target triple identifying a platform and architecture. --min-os sets a minimum macOS version. Building an executable for another platform may require its SDK and target-specific libraries.

dream --object --target aarch64-unknown-linux-gnu -o hello.ll hello.dream

--object stops before linking. It writes an object and its description for later linking; it does not create a runnable executable. Inspect full build requirements with dreamer toolchain doctor --target aarch64-unknown-linux-gnu.

Foreign executables cannot be started with run, test, or the debug adapter on a different platform. Compiler-development output options belong in the contributor handbook.