Tooling#

One executable holds the checker, formatter, build system, documentation generator, language server, profiler, and interop tools. The checker, editor, and build share the type system and incremental engine; documentation uses the same lossless parser without invoking the checker.

nupp check
nupp build
nupp test

Every command takes -h, and nupp help <command> prints the same reference.

Command	Purpose	More
`check`	Type-check the project	nupp command
`build`	Build configured Lua, native, Wasm, or packaged artifacts	Build system
`run`	Compile and run; profile behind a flag	Profiling
`bc --check`	Find deterministic LuaJIT recorder blockers	LuaJIT trace checking
`test`	Build, then run the bundled or configured suite	Testing
`fmt`	Format; fixed style	fmt.md
`doc`	Generate an API site from the parse	doc.md
`lsp`	Language server, and CLI equivalents	lsp.md
`explain`	Describe a diagnostic code	Diagnostics
`lints`	List the lints and their levels	Lints
`import-c`	Turn a C header into declarations	c-interop.md
`export-c`	Export Nupp struct layouts and entry declarations	c-interop.md
`migrate`	Convert annotated Lua into gradual Nupp	Gradual typing
`aot`	Inspect verified AOT IR and target artifacts	Ahead-of-time compilation
`reference`	Print focused language and tool reference	Diagnostics
`ownership-audit`	Report resource obligations and transfers	ownership.md
`coverage`	Aggregate Nupp coverage data	Testing
`completions`	Generate shell completion definitions	nupp command
`rock`	Create and package typed Lua rocks	LuaRocks
`tasks`	List or inspect manifest targets	Build system
`task`	Run a configured project task	Project tasks
`clean`	Remove configured build outputs	Build system
`fixpoint`	Verify the self-hosting rebuild	Distribution
`ast`	Dump a parsed syntax tree	nupp command
`version`	Print the compiler version	nupp command

Checking#

nupp check              # the whole configured project
nupp check --strict     # hold every file to the strict floor, .g.nupp included
nupp check src/app.nupp # one file

Check the whole project rather than the file you changed. That is what lets Nupp verify module boundaries, ownership contracts, and project lint settings together. See gradual typing for what the strict floor adds, and modules for the boundaries it checks.

Machine-readable output#

Every command that produces data takes --format json (written --json), and each one also takes --schema, which prints the JSON Schema of that output. A test runs each command for real and validates its output against its own schema, so the two cannot drift.

nupp check --json
nupp check --schema
nupp build --json      # diagnostics, the target, and every path written
nupp test --json       # a record per test: name, status, duration, failure

Color is off whenever output is not a terminal, so a pipe never carries escape codes. --color=always forces it back on; NO_COLOR, CLICOLOR_FORCE, and TERM=dumb are honored. See JSON and schemas for the options every command shares.

Diagnostics#

Every diagnostic has a stable code, a source span, and often a machine-applicable fix. nupp explain turns the code into the rule, a program that reports it, and the same program corrected:

nupp explain NUPP2119

See diagnostics for the format and the JSON shape, and lints for the ones a project can configure or suppress.

Editors#

nupp lsp serve speaks LSP over stdio. It provides diagnostics, hover, completion, signature help, go-to-definition, references, rename, document and workspace symbols, semantic tokens, folding, selection ranges, formatting, and the checker's code-action quick fixes.

The same operations are available without an editor, which is what makes them usable from a script or an agent:

nupp lsp inspect --json FILE LINE COLUMN
nupp lsp definition --json FILE LINE COLUMN
nupp lsp references --json --include-declaration FILE LINE COLUMN
nupp lsp symbols --json [--file FILE] [PATTERN]
nupp lsp rename FILE LINE COLUMN NEW_NAME    # previews; --write applies
nupp lsp actions --json --only quickfix FILE LINE COLUMN
nupp lsp trace-check --json FILE LINE COLUMN

Positions are 1-based byte line and column numbers, matching the compiler's diagnostics.

Formatting#

nupp fmt              # list what is unformatted, project-wide
nupp fmt --write      # rewrite in place
nupp fmt --check      # report only; exits 1 if anything is unformatted
nupp fmt src/x.nupp   # format one file to stdout

The formatting rules are fixed. --width controls the code wrap column, while --no-method-parens and fmt.methodParens = false preserve Lua's unparenthesized method-call sugar. The formatter guarantees the output re-lexes to an identical token sequence, so it cannot change a quote style, numeric literal, or trailing comma. See formatter for what each way of calling it does with its result.

Building#

nupp build                    # the default manifest target
nupp build --target docs      # a named target
nupp build -O2                # optimize
nupp tasks                    # what targets exist
nupp clean --dry-run          # what clean would remove

Builds are incremental across processes. A source edit rechecks and regenerates that module; dependents are only invalidated when its exported interface changes. See build system for the manifest, targets, caching, and native dependencies.

Profiling#

nupp run --profile app.nupp      # where the time went   -> profile.out
nupp run --jit-aborts app.nupp   # what the JIT refused  -> jit-aborts.csv

The second answers a question a sampling profiler structurally cannot: whether the hot code was compiled at all.

Hot reload#

nupp run --watch app.nupp

At a safe loop boundary, call nupp.hotreload.poll(). Compatible named-function body edits commit without recreating application state; broken or structural edits leave the last good generation running. Watch is an -O0 development target, not a release-performance build. See hot reload for which edits commit and which need a restart.

Documentation#

nupp doc site -o build/docs src
nupp doc markdown -o docs/api.md src

nupp doc reads the parser's lossless CST and never invokes the checker or the code generator, so a documentation build costs parsing and rendering alone. This site is built by it. See documentation generator for the doc-comment tags, the public surface rule, and how handwritten pages join the generated ones.