138 lines
2.9 KiB
Markdown
138 lines
2.9 KiB
Markdown
# Development
|
|
|
|
This document describes the development workflow for Decodal itself.
|
|
|
|
## Rust checks
|
|
|
|
Run the normal Rust checks from the repository root.
|
|
|
|
```sh
|
|
cargo fmt --check
|
|
cargo test
|
|
cargo check -p decodal-core --no-default-features
|
|
nix flake check
|
|
```
|
|
|
|
Regex support is optional and should be tested explicitly when touched.
|
|
|
|
```sh
|
|
cargo test -p decodal-core --features regex
|
|
cargo run -q -p decodal --features regex -- examples/regex/main.dcdl
|
|
```
|
|
|
|
## Web site and playground
|
|
|
|
The Svelte documentation site and browser playground are kept in:
|
|
|
|
```text
|
|
site/decodal-site/
|
|
```
|
|
|
|
The site imports Markdown files from `doc/manual/souce/` and renders them as mdBook-style pages.
|
|
The playground loads `decodal-wasm` and evaluates DCDL entirely in the browser.
|
|
|
|
Important files:
|
|
|
|
```text
|
|
site/decodal-site/src/App.svelte
|
|
site/decodal-site/src/Playground.svelte
|
|
site/decodal-site/src/lib/docs.js
|
|
crates/decodal-wasm/src/lib.rs
|
|
```
|
|
|
|
Build the WebAssembly package before building the site:
|
|
|
|
```sh
|
|
cd site/decodal-site
|
|
npm install
|
|
npm run build:wasm
|
|
npm run build
|
|
```
|
|
|
|
`npm run build:wasm` writes generated files into:
|
|
|
|
```text
|
|
site/decodal-site/src/wasm/
|
|
```
|
|
|
|
These generated files are committed so the site can be built without requiring every consumer to regenerate the wasm package first.
|
|
|
|
To run the site locally:
|
|
|
|
```sh
|
|
cd site/decodal-site
|
|
npm run dev
|
|
```
|
|
|
|
## Tree-sitter grammar
|
|
|
|
The Tree-sitter grammar is kept in:
|
|
|
|
```text
|
|
editors/tree-sitter-decodal/
|
|
```
|
|
|
|
Important files:
|
|
|
|
```text
|
|
editors/tree-sitter-decodal/grammar.js
|
|
editors/tree-sitter-decodal/queries/highlights.scm
|
|
editors/tree-sitter-decodal/queries/locals.scm
|
|
editors/tree-sitter-decodal/corpus/basic.txt
|
|
```
|
|
|
|
The grammar is intended to be portable across editors such as Zed, Neovim, Helix, and Emacs.
|
|
Zed support should consume this grammar rather than relying on a TextMate grammar.
|
|
|
|
## Tree-sitter commands
|
|
|
|
From the grammar directory:
|
|
|
|
```sh
|
|
cd editors/tree-sitter-decodal
|
|
npm install
|
|
npx tree-sitter generate
|
|
npx tree-sitter test
|
|
```
|
|
|
|
To inspect a parse tree:
|
|
|
|
```sh
|
|
npx tree-sitter parse ../../examples/advanced/main.dcdl
|
|
```
|
|
|
|
The generated parser files under `editors/tree-sitter-decodal/src/` are committed so editor integrations can consume the grammar without regenerating it first.
|
|
`node_modules/` is ignored and must not be committed.
|
|
|
|
## Updating the grammar
|
|
|
|
When the Decodal syntax changes:
|
|
|
|
1. Update `grammar.js`.
|
|
2. Run `npx tree-sitter generate`.
|
|
3. Add or update corpus tests in `corpus/`.
|
|
4. Update highlight queries in `queries/highlights.scm` if token names changed.
|
|
5. Run `npx tree-sitter test`.
|
|
6. Run Rust checks from the repository root if the language parser or examples also changed.
|
|
|
|
## Development shell
|
|
|
|
The Nix development shell includes Rust tooling, Node.js, Tree-sitter CLI tooling, and wasm-pack tooling.
|
|
|
|
```sh
|
|
nix develop
|
|
```
|
|
|
|
The shell provides:
|
|
|
|
- `cargo`
|
|
- `rustc`
|
|
- `rustfmt`
|
|
- `clippy`
|
|
- `node`
|
|
- `npm`
|
|
- `wasm-pack`
|
|
- `lld`
|
|
- `tree-sitter`
|
|
- `nixfmt`
|