# Compiling Apps
One command produces an image. Point it at a source file, or let it
resolve a package the way the launcher does.
## Compiling a File
```sh
deft compile app.dft # -> app.dftc beside the source
deft compile app.dft -o build/app.dftc
````
`deft compile <file.dft>` walks the file's static import closure,
compiles every module, and writes the image. The output defaults to the
entry path with a `c` suffix (`app.dft` → `app.dftc`).
## Compiling a Package (`--app`)
```sh
deft compile --app flappy # -> dist/flappy/
deft compile --app deft/editor # owner/name
deft compile --app deft/editor@0.1.0 # version pin
deft compile --app ./path/to/pkg # direct path
deft compile --app editor --pkg-root ~/packages
deft compile --app deft/editor -o editor.dftc # image only
````
`--app <ref>` resolves a package the way the launcher does:
1. a direct path (`./pkg`, `pkg/package.dft`, an existing directory);
2. a mount key (`deft/editor`, `deft/editor@0.1.0`, nested packages);
3. a name searched under `--pkg-root <dir>` roots, the prelude `:pkgs`
roots, `.deft/packages`, `apps`, and `~/packages` — flat
(`<root>/<name>`), owner-scoped (`<root>/<owner>/<name>`), and
versioned layouts.
The entry is the manifest `main`, else `src/<name>.dft` (legacy
`<name>.dft`). The default output is the bundle directory
`dist/<name>/`; `-o <dir>` writes the bundle elsewhere, and
`-o <something>.dftc` writes only the image.
## What Gets Compiled In
- Static imports — `import "…"`, `from "…" import …` / `as`, and
`refer` forms anywhere in a module, walked recursively.
- Top-level `source "file"` — resolved and inlined at compile time,
recursively. The sourced statements compile into the importing module
(same namespace, same position), and each inlined chunk keeps its own
source path so relative imports inside it still anchor to its
directory. `source`d files are therefore embedded exactly like
imports.
- Compile-time macros — `require "…"` loads macros at compile time;
only those macro effects are captured in the image.
- Dynamic imports — names built at runtime cannot be discovered by
the static walk. Force-embed them with `--embed <module>` (name or
path) and the compiled importer will find the pre-registered
namespace.
## Flags
| Flag | Effect |
|---|---|
| `--app <ref>` | Compile a package (resolver above) instead of a file |
| `--pkg-root <dir>` | Extra package root for `--app` (repeatable) |
| `-o`, `--out <path>` | Output file or directory (`*.dftc` = image only) |
| `--embed <module>` | Force-embed a module for dynamic imports (repeatable) |
| `--requires a,b` | Record host capability requirements in the manifest |
| `--execute-top-level` | Run statements during compilation, for the rare macro whose expansion reads a runtime global defined earlier in the file |
## The Bundle
`deft compile --app` prints a summary and writes:
```
dist/editor/
├── editor.dftc the AOT image (code only)
├── bundle.dft %DeftApp{...} metadata + image sha256
├── package.dft copied from the package (launcher/package-tool compat)
├── icon.svg copied when the package has one
└── assets/ the package's assets/ tree, copied recursively
````
The image is runnable by itself. `bundle.dft` and `package.dft` carry
the metadata an installer or launcher needs — see
Bundles and Manifests for the field-by-field
comparison, and Running Images for how to launch the
result.