chore: scaffold Cargo workspace for the Ghostty rewrite
Start of the full Rust rewrite of Ghostty 1.3.1 (reference source in
../ghostty). Sets up a workspace whose crates mirror Ghostty's Zig modules
(vt, unicode, datastruct, os, input, config, terminal, font, renderer,
termio, core, apprt-gtk) so porting work can proceed in parallel per crate.
Also adds:
- docs/rewrite/{ARCHITECTURE,PLAN,STATUS,AGENT_GUIDE}.md: crate map, core
design decisions (safe Rust, slab-based PageList, logical capacity
accounting), phased plan, progress tracker, and porting rules.
- Workspace clippy config relaxing pedantic lints that are pure noise for
low-level terminal code (casts, long functions).
- Shared vt types needed by several work packages up front: kitty
keyboard flags (kitty/key.rs) and the CSI separator bitset (SepList).
Test Plan:
- cargo test -p ghostty-vt (3 tests pass)
- cargo clippy -p ghostty-vt --all-targets -- -D warnings
This commit is contained in:
1 parent
e04991c1f5
commit
987f2957ad
34 files changed
+759
-4
No files matched your search
@@ -0,0 +1,56 @@
|
||||
# Guide for porting agents
|
||||
|
||||
You are porting part of Ghostty 1.3.1 (Zig) to Rust. Read
|
||||
`docs/rewrite/ARCHITECTURE.md` first.
|
||||
|
||||
- Zig source (read-only reference): `../../../ghostty/src`
|
||||
- Rust workspace: `../..`
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Stay in your lane.** Only edit the crate/modules assigned to you. If you
|
||||
need something from another crate that doesn't exist yet, write a minimal
|
||||
local version, mark it `// TODO(integration): ...`, and mention it in your
|
||||
report. Never rewrite other agents' modules. You MAY add dependencies to your
|
||||
own crate's `Cargo.toml` (prefer well-known crates; use `cargo add -p <crate>`).
|
||||
2. **Faithful port.** Preserve behaviour, edge cases, defaults and naming
|
||||
(snake_case of the Zig names). Port doc comments (they are user-visible for
|
||||
config/actions). Don't "improve" semantics. Idiomatic Rust structure is fine
|
||||
(enums for tagged unions, traits for comptime interfaces, `Result` for error
|
||||
unions) as long as behaviour matches.
|
||||
3. **Port the tests.** Every Zig `test "name"` in files you port becomes a
|
||||
`#[test] fn name_snake_case()` in a `#[cfg(test)] mod tests` of the
|
||||
corresponding Rust module. Tests that are about Zig-only concerns
|
||||
(allocator failure injection, comptime, C ABI, Metal/macOS) may be skipped —
|
||||
list them in your notes file. Add extra tests when behaviour is subtle.
|
||||
4. **No `unsafe`** unless your crate is explicitly allowed (renderer, termio,
|
||||
apprt-gtk), and then only minimal + `// SAFETY:` comments.
|
||||
5. **Quality gate before you finish** (must all pass for your crate):
|
||||
- `cargo build -p <crate>`
|
||||
- `cargo test -p <crate>`
|
||||
- `cargo clippy -p <crate> --all-targets -- -D warnings`
|
||||
- `cargo fmt -p <crate>` (rustfmt.toml in repo root; if nightly-only options
|
||||
warn, ignore the warnings)
|
||||
No `todo!()`/`unimplemented!()` left in code paths that are reachable,
|
||||
unless documented in your notes as deferred.
|
||||
6. **Do NOT run `git commit`** or any git command that changes state. The
|
||||
orchestrator commits.
|
||||
7. Other agents work concurrently in other crates of the same workspace. If the
|
||||
*workspace* build breaks because of another crate, use `-p <crate>` and
|
||||
ignore it. Cargo may block briefly on the build-directory lock; that's normal.
|
||||
8. **Write notes** to `docs/rewrite/notes/<crate>-<topic>.md`: what was ported
|
||||
(file → module), skipped tests with reasons, deviations, TODO(integration)
|
||||
items, known gaps.
|
||||
9. **Final report** (your last message): ≤ 25 lines — modules done, test counts
|
||||
(ported / skipped), quality-gate status, open issues. The orchestrator reads
|
||||
only this, so be precise and honest about anything incomplete.
|
||||
|
||||
## Conventions
|
||||
|
||||
- `pub mod` per Zig file; file names snake_case (`PageList.zig` → `page_list.rs`).
|
||||
- Error types: `thiserror` is fine; `anyhow` only in binaries/CLI.
|
||||
- Logging: the `log` crate (`log::warn!` etc.) where Zig uses `std.log`.
|
||||
- Integer types: keep the Zig widths (u16 for cell counts `CellCountInt`, etc.).
|
||||
- Zig `packed struct` bitfields → plain structs unless memory layout matters
|
||||
(documented in ARCHITECTURE for `Cell`/`Row`).
|
||||
- Prefer `std` collections; `hashbrown`/`smallvec`/`bitflags` OK.
|
||||
Reference in new issue
Block a user