Getting started › The CLI
The CLI
The compiler is a single binary. It takes one entry file, compiles the whole pipeline down to a native artifact, and — outside --hovercraft mode — runs it immediately.
Package commands live under a second group on the same binary, hover hpm ... — see Packages & hpm. Because hover <file>.hvr is the primary positional form, no subcommand is ever named like a file; the .hvr extension is what disambiguates the two.
What happens
Given an entry file, hover:
- Loads it and every (non-transitive)
import, lexes and parses each file independently. - Runs semantic analysis, then elaborates the circuit graph, resolving imports.
- Generates C++ (
sim.cpp). - Compiles it with
zig c++against the prebuilt runtime — see Build targets. - Runs the resulting binary as a subprocess, streaming its stdout/stderr straight through, and it writes
simulation_output.csv.
Flags
| (none) | Compile, then run — the default. |
-o <path> | Write the built artifact to <path> instead of the default name (sim / sim.exe, or libhovercraft.so / hovercraft.dll with --hovercraft). -o=<path> is also accepted. The generated sim.cpp is always written to the current directory regardless of -o. |
--hovercraft | Switches codegen and build to library-output mode: instead of a one-shot binary that runs and exits, the compiler emits a reusable C-ABI shared library you link from C/C++/Python. See Calling C++ & embedding Hover. Recognized anywhere in the argument list, not just position 2. |
--dump-ast | Print the entry file's AST and exit without compiling. |
--setup | Check for a usable Zig toolchain and fix it up if not: on Windows, downloads one into ./toolchain/zig; on Linux, reports whether one is already on PATH. Run this once after extracting a release, or any time a compile fails with a "Zig not found" error. Takes no other arguments. |
Output
A normal run leaves behind the generated sim.cpp, the compiled binary, and simulation_output.csv (the columns named in the source's .save directive — see .save / .tran / .solver) in the working directory.