Skip to main content

16  CLI and Package Manager (edva.ccl)

The edva binary provides single-file / modular compilation, interactive REPL and inline evaluation (-i, -e), AST/type inspection, canonical code formatting (edva fmt), Language Server Protocol support (edva lsp), and top-level package management (edva init, edva add, edva rm, edva build, edva run, edva test, edva fetch, edva update, edva tree, edva vendor, edva cache).

16.1 Compiler invocation and options

edva [options] [input.dva | dir] [output]
edva <command> [options] [args...]
edva -e "<code_string>" [options]
edva -i
edva fmt [--check] [--stdout] [--stdin] [path...]
edva lsp
Short / Long Option Argument Default Specification
-o, --output <str> <stem> Output binary, .o object, .so shared library, .wasm, or .ll path
-r, --run — <-> Run compiled binary immediately after linking (uses node for .wasm targets)
--ir — <-> Emit LLVM IR (.ll) only; do not invoke clang
-c, --compile-only — <-> Compile module to object file (.o) only (implies --no-main)
--shared — <-> Build a shared library (.so, implies --no-main)
--entry — <-> Compile as program entry module (emits main)
-m, --module <str> "" Compile as named module <str> (implies -c and --no-main)
-t, --target <str> Host triple Target triple (e.g. x86_64-unknown-linux-gnu, aarch64-linux-gnu, wasm32-unknown-unknown, wasm32-wasi)
-O, --opt <str> "2" Optimization level (0, 1, 2, 3, s, z, or -O0..-Oz)
-H, --header <str> "" Generate C header file at <str> from #export declarations
-e, --eval <str> "" Compile and evaluate inline Edva code string (auto-prints single non-unit expressions)
-i, --repl — <-> Start interactive terminal REPL (:q, :quit, exit, or Ctrl-D to exit)
--ast — <-> Print parsed AST of target program and exit
--ast-tree — <-> Print parsed AST as an indented tree and exit
--typed-ast — <-> Elaborate and verify typed AST, print elaboration stats, and exit
--typed-ast-tree — <-> Elaborate, verify, and dump typed AST tree
--no-main — <-> Emit main with internal linkage
--no-runtime — <-> Omit standard runtime emission
--import-map <str> "" Path to package import map (.edva/imports.ccl)
--cache <str> ~/.cache/edva/ir Compilation cache directory path
--no-cache — <-> Disable compilation cache
--cflag <str> () Pass additional flag to clang (repeatable, e.g. --cflag -lm --cflag -msimd128)
-v, --version — — Display compiler version (edva <version>) and exit
-h, --help — — Display formatted CLI help and exit

16.1.1 Environment variables

Variable Default Purpose
EDVA_PATH / EDVA_STDLIB <exe_dir>/std Overrides standard library directory resolution
XDG_CACHE_HOME ~/.cache Base directory for compilation cache (edva/ir) and package store (edva/store)
EDVA_STORE ~/.cache/edva/store Content-addressed package store directory
EDVA_OFFLINE "0" Set to "1" to enforce --offline mode across package commands
EDVA_NO_CACHE "0" Set to "1" to disable IR caching across compiler and package commands
EDVA_GIT "git" Git executable used when fetching git dependencies

16.2 Package and cache subcommands

All package and cache commands are first-class top-level subcommands (edva <command> --help shows command-scoped help):

Command Arguments & Options Behavior Diagnostics
edva init [dir] [-n/--name <name>] [--lib] Scaffolds edva.ccl, src/<name>.dva, and (unless --lib) src/main.dva in [dir] (default: .) E7020: edva.ccl already exists
edva add [<alias>] <spec> [--as <alias>] [--rev <r>]
[<alias>] --path <p>
[<alias>] --git <url> [--rev <r>]
[<alias>] --url <u> --hash <h>		 Transactionally adds dependency to edva.ccl (auto-inferring alias from edva.ccl name or repo/dir basename when omitted, supporting <spec>@<rev>, owner/repo, and host/owner/repo shorthand), resolves graph, and updates edva.lock.ccl (rolls back edva.ccl on failure) E7021: rollback on fetch/resolve failure
edva rm <alias> [dir] (alias remove) Removes <alias> from edva.ccl and updates edva.lock.ccl and .edva/imports.ccl E7004: dependency not found
edva build [dir \| file.dva] [-o <out>] [-t <triple>] [-O <opt>] [--cflag <f>] [--locked] [--offline] [--store <d>] [--cache <d>] [--no-cache] Dual-mode: builds package targets from edva.ccl (or src/main.dva \(\to\) ./<name>) or compiles a single .dva file E5039: missing pkg-config lib
edva run [dir \| file.dva] [options] [-- <args...>] Dual-mode: builds and executes the package binary or single .dva file, forwarding arguments after -- to the program E7019: missing source or target
edva test [dir \| file.dva] [--locked] [--offline] [--store <d>] [--cache <d>] [--no-cache] Compiles and runs all tests/*.dva in a package, or a single test .dva file if specified —
edva fetch [dir] [--locked] [--offline] [--store <d>] [--cache <d>] [--no-cache] Resolves dependencies, populates content store, writes edva.lock.ccl and .edva/imports.ccl E7007: lockfile out of date (--locked)
edva update [pkg_name] [dir] Refreshes moving Git branches/tags in edva.lock.ccl (all or single <pkg_name>) —
edva tree [dir] (alias graph) Prints ASCII dependency tree with provenance, duplicate versions, and cycle checks —
edva vendor [dir] Materializes external dependencies into vendor/<id>/ + vendor/vendor.ccl for air-gapped --offline --locked builds E7005: tree hash mismatch
edva cache [dir \| ls \| clean] [--cache <d>] Prints cache directory (default), lists cached .ll entries, or cleans cached IR artifacts —

16.3 Formatter and Language Server (edva fmt, edva lsp)

Command Arguments & Options Behavior
edva fmt [--check] [--stdout] [--stdin] [path...] Canonical Edva source formatter. Normalizes block indentation, delimiter spacing, blank lines, and trailing whitespace while preserving intentional horizontal alignment and verifying AST equivalence via show::show_expr. Formats . recursively when no paths are given. --check exits 1 if any file differs; --stdin formats stdin to stdout
edva lsp — JSON-RPC 2.0 Language Server Protocol server over stdio (Content-Length framing). Provides live diagnostics (textDocument/publishDiagnostics), inferred-type hover (textDocument/hover), same-file and cross-module go-to-definition (textDocument/definition), document symbols (textDocument/documentSymbol), completion (textDocument/completion), and canonical formatting (textDocument/formatting)

16.3.1 edva fmt formatting rules

Rule Construct Indentation / Behavior
Standard blocks (+3 spaces) Function/lambda bodies (=>, !=>, | x =>), cycle bodies (@, @@, >--), [guard] arm bodies, choice arms relative to the choice head, and #type / #foreign / #public / #private blocks Indented by +3 spaces relative to the enclosing statement or inline-started block opener (my_fn = a, b => first_line followed by second_line at +3 spaces)
Inline choice arm bodies (+2 spaces) Choice arm starting on the same line as | or !| (| first_line) Subsequent statements of the arm block indent by +2 spaces relative to |, aligning directly under first_line
Expression continuations (+2 spaces) Multi-line expressions wrapped after a trailing binary or continuation operator (+, -, *, /, &&, ||, ,, $, etc.) Indented by +2 spaces relative to the statement’s starting column
Horizontal alignment Multi-space column alignment in [guard] tables, #type / #foreign declarations, and inline comments Preserved intact

16.4 Package directory layout and edva.ccl manifest schema

16.4.1 Standard package layout

Path Role
edva.ccl Package manifest (name, version, dependencies, native libs, build targets)
edva.lock.ccl Deterministic lockfile pinning commit hashes and canonical sha256-<hex> tree digests
.edva/imports.ccl Generated import map linking @alias imports (#use @pkg) to resolved store/vendor paths
src/<name>.dva Root library module imported when dependents write #use @<name>
src/main.dva Default executable entry point when targets = is omitted
tests/*.dva Independent test executables discovered by edva test

16.4.2 edva.ccl configuration keys

The manifest uses CCL (Categorical Configuration Language) syntax (key = value with indentation-scoped sections):

Section / Key Example Specification
name, version, edva name = my_app Package identifier, semantic version, and minimum compiler version
dependencies.<alias>.path path = ../math_utils Local relative or absolute directory containing edva.ccl
dependencies.<alias>.git / rev git = https://...
rev = v1.2.0		 Git repository URL and branch, tag, or commit (pinned with tree hash in edva.lock.ccl)
dependencies.<alias>.url / hash url = https://.../a.tar.gz
hash = sha256-<hex>		 Tarball archive verified against sha256-<hex> digest
overrides.<alias> path = ../local_fork Root-manifest override replacing direct or transitive dependency <alias> across the graph
native.libs = m
= pthread		 List of system libraries forwarded as -l<lib> to Clang
native.pkg-config = libssl List of packages resolved via pkg-config --libs <name> (E5039 if missing on host)
targets.<id>.src src = src/client.dva Entry .dva source file for build target <id> (default: src/main.dva)
targets.<id>.out out = dist/client.wasm Output binary path for build target <id> (default: <id>)
targets.<id>.target target = wasm32-unknown-unknown Target triple passed via -t / --target
targets.<id>.opt opt = -O3 Optimization level (0..3, s, z, or -O0..-O3)
targets.<id>.cflags = -msimd128 List or space-separated string of flags forwarded via --cflag 
// Importing external packages declared in edva.ccl:
#use @term
#use @term/colors

term::print("ok")