LILYLILYDOCS
HomepageLogin
Docs/CLI/compile

lly compile

Compile a source file to a .brick bundle.

lly compile turns a single source file into a portable brick. The CLI inspects the source extension, hands the file to the matching frontend plugin, and writes a content-addressed WASM bundle to the path you give it. The same brick runs locally with lly run and ships to the fleet with lly void deploy.

Synopsis

lly compile [OPTIONS] --output <OUTPUT> <SOURCE>

SOURCE is one input file. For multi-file projects use a frontend plugin such as nextjs or invoke lly-cxx with object inputs.

Options

  • -o, --output <PATH> — output brick path. Required. Convention is .brick.
  • -f, --force — overwrite OUTPUT if it already exists. Without this the command refuses to clobber.
  • -I, --include-path <DIR> — add an extra include directory for C and C++ inputs. Repeatable.
  • --profile <NAME> — compatibility profile passed to the frontend plugin. C and C++ accept c11, c17, c++17, c++20. JS accepts es2022, es2023.
  • --plugin <NAME> — force a specific frontend plugin and skip extension dispatch. Useful when the file has a non-standard suffix or when you have multiple frontends installed for the same language.
  • -v, --verbose — print each compilation stage with timing. Use it twice (-vv) for plugin-level debug output.
  • --target <TRIPLE> — currently fixed to wasm32-wasi; reserved for future targets.

Examples

compile a C source file
$ lly compile hello.c -o hello.brick → dispatch: .c → frontend-c v0.8.2 parse 1 TU · 42 LOC 12 ms lower bir 318 nodes 4 ms codegen wasm32-wasi · 1 module 31 ms ✓ wrote hello.brick (38 KB, sha256:9a4f…c1b2)

The same flow for JavaScript dispatches to frontend-js. The output is a single-brick bundle with one WASM module and a manifest.

compile a JS source file
$ lly compile app.js -o app.brick --profile es2023 → dispatch: .js → frontend-js v0.11.4 (profile=es2023) parse 1 module · 184 LOC 8 ms lower bir 1102 nodes 11 ms codegen wasm32-wasi · 1 module 87 ms ✓ wrote app.brick (146 KB, sha256:2c11…77ae)

Extension dispatch

Without --plugin, the CLI picks a frontend based on the source extension:

  • .c → frontend-c
  • .cc, .cpp, .cxx → frontend-cpp
  • .h, .hpp → rejected (headers are not compilation units)
  • .js, .mjs, .cjs → frontend-js
  • .ts, .tsx → frontend-js with TS lowering enabled

If a frontend plugin is missing the CLI prints the install command. Run lly plugin list to see what is registered, and lly plugin which .c to ask which plugin owns a given extension.

Include paths

C and C++ inputs accept -I the same way cc does. Paths are searched in the order given, before the bundled libc and libcxx roots.

lly compile main.c -I./include -I./vendor -o main.brick

Exit codes

  • 0 — success. The brick was written.
  • 2 — usage error. Missing argument, unknown flag, unsupported extension, or refusing to overwrite without --force.
  • 3 — compile failure. The frontend rejected the source. Diagnostics are printed to stderr.
  • 4 — plugin error. The selected frontend plugin is missing, corrupt, or crashed.

For a full mapping see troubleshooting.

Reproducibility

Bricks are content-addressed. Two builds of the same source with the same flags and the same plugin version produce byte-identical output. The sha256 printed on success is the manifest digest you will see again in lly bundle inspect and in the platform dashboard after deploy.

See also

  • lly run — execute a brick locally through the runtime plugin.
  • lly bundle inspect — read manifest, modules and assets out of a brick.
  • lly plugin — manage frontend and util plugins.
  • Bricks — what is inside the bundle.