diff options
Diffstat (limited to 'Zig.novaextension')
| -rw-r--r-- | Zig.novaextension/README.md | 142 |
1 files changed, 54 insertions, 88 deletions
diff --git a/Zig.novaextension/README.md b/Zig.novaextension/README.md index 72865ee..355c194 100644 --- a/Zig.novaextension/README.md +++ b/Zig.novaextension/README.md @@ -1,118 +1,84 @@ -# Zig for Nova +# Zig ⚡️ Nova -Zig language support – ZLS, LLDB, Tree-Sitter grammar +**Write, build, test and debug Zig projects natively in Nova** -## Requirements +- Grammar, syntax highlighting, folding, navigation +- Language intelligence provided by ZLS +- Nova tasks for building, running, testing and debugging Zig code +- Auto-detection of build steps in `build.zig` +- Debugging provided by LLDB -- [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`) +This is a personal project to learn Zig, but using Nova to do so. Feedback and problem reports are greatly appreciated, you can send them to bugs@dcz<!--.example-->.at. If something doesn’t work for you, please let me know. -\* optional but recommended for full experience +## Installation -## Why +- [Zig](https://ziglang.org) +- [ZLS](https://github.com/zigtools/zls)\* for language intelligence +- [Xcode Command line tools](https://developer.apple.com/documentation/xcode/installing-the-command-line-tools/#Install-the-Command-Line-Tools-package-in-Terminal)\* for debugging -A personal project to learn Zig without leaving Nova and without giving up the comfort of language server and debugging features. +\* optional but recommended for full experience -This extension is not endorsed by, affiliated with, or associated with the [Zig Software Foundation](https://ziglang.org/zsf/) or the Zig core team in any way. It is maintained by an independent person, for fun. +The extension resolves the executables automatically via the PATH environment variable or `xcrun`. But you can also manually configure them in the extension settings (global) or workspace settings (which overrides the extension settings so you can have different Zig versions for different projects). ## 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, code actions, formatting (all via ZLS) -- Inline compiler errors from `zig build` - -### Tasks - -Four templates expose the `zig build` surface — pick one in **Project Settings > Tasks > New Task**: - -- **Zig Package**: build and run a Zig package. Configurable optimize mode, target triple, custom `-D` user options, run step, build/program arguments, and console (Internal Console or External Terminal). -- **Zig Debug**: build and launch under lldb-dap. Same flag surface as Zig Package, plus program path (auto-detected from `build.zig.zon` when blank), console, and stop-on-entry. -- **Zig Test**: run `zig build test` with optional `--test-filter`, `--summary`, plus optimize/target/user-options. -- **Zig Watch**: run `zig build --watch` with configurable step, debounce, and incremental flag. - -Every runnable template also exposes a clean action that removes `.zig-cache`, `zig-cache`, and `zig-out`. Clean refuses to run when the working directory resolves to `/`, `$HOME`, or anywhere outside the workspace; when the project's `build.zig` exposes an `uninstall` step, it runs first. - -Two ad-hoc tasks appear automatically: - -- **Current Zig File**: run via `zig run <file>` and clean the nearest `build.zig` ancestor. -- **Zig Build: \<step\>**: one task per step discovered from `zig build --list-steps`. The list is cached and refreshed when `build.zig` or `build.zig.zon` changes. +### Code Editing -The legacy **Zig Package (macOS Terminal)** template is preserved for backward compatibility. New configurations should use **Zig Package** with Console set to External Terminal. +- **Syntax highlighting** for `.zig` and `.zon` files +- [**Completions**](https://help.nova.app/editor/overview/#completions) +- [**Code folding**](https://help.nova.app/editor/overview/#code-folding) +- [**Code structure headers**](https://help.nova.app/editor/overview/#code-structure-headers) +- **Type and function separators** +- [**Path bar**](https://help.nova.app/editor/overview/#path-bar) +- **Compiler issues and warnings** displayed inline upon compilation +- **Language intelligence** via ZLS: + - [Completions](https://help.nova.app/editor/overview/#completions) + - [Hovers](https://help.nova.app/editor/language-servers/#hovers) + - [Signature help](https://help.nova.app/editor/language-servers/#signature-help) + - [Issues and Warnings](https://help.nova.app/editor/issues-and-warnings/) -#### Watch-mode caveat +### Building & Testing -Nova issue matchers fire only on the first build cycle of a long-running task. With `zig build --watch`, errors from later cycles will not appear inline — re-run the task to refresh the issue overlay. +- [**Tasks templates**](https://help.nova.app/tasks/task-templates/#task-templates): compile, debug, run, test +- **Current Zig file** – compile and run the active `.zig` file +- **Auto-discovery of build steps** via `zig build --list-steps` ### Debugging -- Breakpoint support in Zig source files -- LLDB-based debug adapter, auto-discovered via `xcrun` or `PATH` +- **Debug** with the **Zig Debug** task template via LLDB (Xcode Command line tools required) +- [**Breakpoints**](https://help.nova.app/debugging/debug-sidebar/#setting-breakpoints) +- [**Execution control**](https://help.nova.app/debugging/debug-sidebar/#execution-controls) +- [**Variable inspection**](https://help.nova.app/debugging/debug-sidebar/#inspecting-variables) +- **Performance information** +- **Manual lldb commands** -## Configuration +### Configuration -Global settings live under **Nova Preferences > Extensions > Zig**. -Per-workspace overrides live under **Project Settings > Zig** and take precedence. +The extension strives to keep the configuration options as short as possible but as flexible as needed. If you are missing a configuration option, please let me know. -### Tooling +## Troubleshooting -Paths to the `zig`, `zls`, and `lldb-dap` executables. Leave any blank to discover from `PATH`. +### Auto-discovered tasks wont’t open the report automatically -### Language Server +The _Current Zig file_ and auto-discovered `zig build` tasks are created programmatically. Nova’s API doesn’t support auto-opening the report for them at the moment. -- Enable or disable ZLS -- Allow ZLS to run its build/check on save -- Log ZLS traffic to the Extension Console (for troubleshooting) +### ZLS isn’t working -## Known Issues +- Confirm ZLS is installed: `which zls` +- Configure the path to ZLS manually +- Check the extension console for errors +- Confirm ZLS and Zig are version-compatible -### Auto-discovered tasks cannot open the report automatically +### Debugging isn’t working -The **Current Zig File** and **zig build \<step\>** tasks are provided programmatically by the extension. Nova’s extension API does not expose the report-opening setting for tasks created this way. Open the report manually or use a task template (**Project Settings > Tasks > New Task**) if automatic report opening matters. +Make sure that the [Xcode Command line tools](https://developer.apple.com/documentation/xcode/installing-the-command-line-tools/) are installed or set the path to `lldb-dap` manually in the extension or workspace settings. -### 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, 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 <ref> # specific tag, branch, or SHA -``` - -Validate the extension bundle: +## License -```sh -/Applications/Nova.app/Contents/SharedSupport/nova extension validate Zig.novaextension/ -``` +This extension is a personal project and is not endorsed by or affiliated with the [Zig Software Foundation](https://ziglang.org/zsf/). -## License +The extension’s source code is licensed under the BSD 2-Clause License. -The extension's source code is licensed under the BSD 2-Clause License -(see [`LICENSE`](LICENSE)). Bundled assets and vendored third-party -code carry their own licenses, documented in -[`NOTICES.md`](NOTICES.md): +The Zig logo is the original work of the [Zig Software Foundation](https://ziglang.org). It and the icon assets derived from it remain licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). -- The Zig logo and the icon/image assets derived from it - (`extension.png`, `extension@2x.png`, `Images/zig-mark/*.png`, - `Resources/Zig@32px.af`) are the work of the - [Zig Software Foundation](https://ziglang.org) and remain licensed - under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). -- 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) - and is distributed under the MIT License. +The bundled 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) and is distributed under the MIT License. |