From ddf2de739068b5ff0866ccb1d067f3cb53a4fc55 Mon Sep 17 00:00:00 2001 From: David Czihak Date: Thu, 7 May 2026 14:33:19 +0200 Subject: Initial commit --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..46218d9 --- /dev/null +++ b/README.md @@ -0,0 +1,87 @@ +# Zig for Nova + +Zig language support – ZLS, LLDB, Tree-Sitter grammar + +## Requirements + +- [Zig](https://ziglang.org/download/) installed and on `PATH` (or configured in extension preferences) +- [ZLS](https://github.com/zigtools/zls)\* for language intelligence +- [LLDB DAP](https://lldb.llvm.org/use/lldbdap.html)\* for debugging (discovered automatically via `xcrun` or `PATH`; install the Xcode Command Line Tools if absent: `xcode-select --install`) + +\* optional but recommended for full experience + +## Why + +A personal project to learn Zig without leaving Nova and without giving up the comfort of language server and debugging features. + +## Features + +### Editing + +- Syntax highlighting for `.zig` and `.zon` +- Code folding for blocks, declarations, and control-flow expressions +- Document symbols (outline, breadcrumbs, Go to Symbol) +- Diagnostics, completion, hover, go to definition, find references, select all references, formatting (all via ZLS) +- Inline compiler errors from `zig build` + +### Tasks + +- **Zig Package**: build and run a Zig package in the Nova console +- **Zig Package (macOS Terminal)**: build and run in the external Terminal app for interactive CLIs +- **Zig Debug**: build in Debug mode and launch under the debugger, with configurable console and stop-on-entry +- A clean action on every runnable template that removes `.zig-cache`, `zig-cache`, and `zig-out` + +### Debugging + +- Breakpoint support in Zig source files +- LLDB-based debug adapter, auto-discovered via `xcrun` or `PATH` + +## Configuration + +Global settings live under **Nova Preferences > Extensions > Zig**. +Per-workspace overrides live under **Project Settings > Zig** and take precedence. + +### Tooling + +Paths to the `zig`, `zls`, and `lldb-dap` executables. Leave any blank to discover from `PATH`. + +### Language Server + +- Enable or disable ZLS +- Allow ZLS to run its build/check on save +- Log ZLS traffic to the Extension Console (for troubleshooting) + +## Troubleshooting + +### A large part of the file turns red after one error + +The parser may report a broad recovery range when it hits an incomplete expression (for example, `MyError.`), and Nova highlights that entire range. Fix the first syntax error shown and the overlay should narrow to the real error locations. + +## Development + +The Tree-sitter parser is built from the vendored grammar snapshot under `vendor/tree-sitter-zig`. The pinned upstream commit is recorded in `vendor/tree-sitter-zig/VENDORING.md`. + +Rebuild the parser dylib: + +```sh +./Scripts/build-parser.sh +``` + +Bump the vendored snapshot (and rebuild): + +```sh +./Scripts/update-parser.sh # upstream HEAD +./Scripts/update-parser.sh # specific tag, branch, or SHA +``` + +Validate the extension bundle: + +```sh +/Applications/Nova.app/Contents/SharedSupport/nova extension validate . +``` + +## Attributions + +The Zig logo is the work of the [Zig Software Foundation](https://ziglang.org) and is licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). The zig-debug@2x.png is a derivative of the original logo, improving pixel alignment at 32px size. + +The Tree-sitter grammar for Zig is sourced from [github.com/tree-sitter-grammars/tree-sitter-zig](https://github.com/tree-sitter-grammars/tree-sitter-zig). -- cgit v1.3