Skip to content

Latest commit

 

History

History
491 lines (352 loc) · 20.9 KB

CONTRIBUTING.md

File metadata and controls

491 lines (352 loc) · 20.9 KB

Contributing to par-term

Note: CLAUDE.md is the canonical development reference. It is kept up-to-date by AI-assisted tooling and covers build commands, architecture, debugging workflows, and common gotchas in more detail than this file. When the two documents disagree, CLAUDE.md takes precedence.

Guidelines for contributing to par-term, a cross-platform GPU-accelerated terminal emulator built in Rust.

Table of Contents

Overview

par-term is a cross-platform GPU-accelerated terminal emulator frontend written in Rust (Edition 2024). It uses the par-term-emu-core-rust library for VT sequence processing, PTY management, and inline graphics protocols (Sixel, iTerm2, Kitty). The frontend provides GPU-accelerated rendering via wgpu with custom WGSL shaders, including support for Ghostty/Shadertoy-compatible GLSL post-processing shaders.

Language: Rust (Edition 2024) License: MIT Platforms: macOS (Metal), Linux (Vulkan), Windows (DirectX 12)

Development Setup

Prerequisites

  • Rust stable toolchain — install via rustup:
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Make for build orchestration (available by default on macOS and most Linux distributions)
  • Git

Platform-Specific Requirements

macOS

No additional system libraries are required. The Metal GPU backend is used automatically.

Linux

Install the required GTK3, X11/Wayland, ALSA, and SSL development libraries before building. The package list below mirrors the Linux Dependencies section of the README; both must stay in sync.

Ubuntu/Debian:

sudo apt install libgtk-3-dev libxkbcommon-dev libwayland-dev \
  libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev \
  libasound2-dev libssl-dev pkg-config

Fedora/RHEL:

sudo dnf install gtk3-devel libxkbcommon-devel wayland-devel libxcb-devel \
  alsa-lib-devel openssl-devel pkg-config

Arch Linux:

sudo pacman -S gtk3 libxkbcommon wayland libxcb alsa-lib pkg-config

Windows

No additional steps are required beyond a working Rust stable toolchain. The DirectX 12 backend is used automatically.

Cloning and Initial Build

git clone https://github.com/paulrobello/par-term.git
cd par-term
make build

The first build downloads and compiles all dependencies, which takes several minutes. Subsequent incremental builds complete in roughly 1–2 seconds with make build.

Build Commands

Use make build for all day-to-day development. The dev-release Cargo profile (opt-level 2, no LTO, 16 codegen-units, incremental) delivers approximately 90–95% of full-release performance with ~1–2s incremental rebuilds. Only switch to make build-full when preparing distribution binaries.

Command Cargo Profile Compile Time Description
make build dev-release ~1-2s (incremental) Optimized, incremental. Preferred for development.
make build-full release ~3 min Full LTO, single codegen unit. Use for distribution.
make build-debug debug Fast Unoptimized, includes debug symbols. Use when stepping through code with a debugger.
make release release ~3 min Alias for make build-full.

Output binary locations:

Profile Binary
dev-release target/dev-release/par-term
release target/release/par-term
debug target/debug/par-term

Running the Application

make run            # Run in dev-release mode (preferred)
make run-release    # Run in full release mode

Warning: When stopping a running debug instance, never use killall par-term. This kills all par-term processes on the system, including the terminal session you are working in. Use pkill -f "target/debug/par-term" or kill by specific PID instead.

When testing your code changes, always run from the build output (make run, cargo run) rather than from an installed .app bundle. An installed bundle will not contain your local changes.

Testing

make test                        # Run all workspace tests
make test-one TEST=test_name     # Run a specific test by name
make test-verbose                # Run tests with captured output printed to the terminal
cargo test -- --include-ignored  # Run all tests, including PTY-dependent ones

PTY-Dependent Tests

Some tests require an active PTY session and are marked #[ignore]. The default make test run skips them. To include them explicitly:

cargo test -- --include-ignored

Integration Tests

Integration tests live in the tests/ directory and cover configuration loading, terminal state, and input handling. They use the tempfile crate for isolated temporary files and do not modify real user configuration.

Specialized Testing Targets

make test-fonts         # Comprehensive text shaping and font rendering test suite
make benchmark-shaping  # Text shaping performance benchmarks
make test-text-shaping  # Run font tests and benchmarks together
make test-graphics      # Graphics protocol tests with DEBUG_LEVEL=4 logging
make test-animations    # Kitty animation protocol tests

Code Quality

Run the full quality suite before every commit:

make checkall    # Format, lint, and test — required before committing

Individual targets:

Command Tool Description
make fmt cargo fmt Format all code with rustfmt
make fmt-check cargo fmt -- --check Check formatting without modifying files
make lint cargo clippy -- -D warnings Lint with warnings treated as errors
make lint-all cargo clippy --all-targets -- -D warnings Lint all targets (bins, tests, examples, benches)
make check cargo check Type-check without producing a binary
make checkall fmt-check + lint + typecheck + test The fast local gate (make check-all is a deprecated alias)

Pre-Commit and CI Targets

make pre-commit    # fmt-check + lint + test — run this locally before pushing
make ci            # fmt-check + lint-all + check-nomux + test + line-count, budget, and terminology gates
make checkall-ci   # ci + cargo-deny — the CI-parity gate to pass before pushing
make all           # fmt + lint + test + build

Optional Tools

make coverage      # Test coverage report via cargo-tarpaulin (must be installed separately)
make audit         # Dependency security audit via cargo-audit (must be installed separately)
make profile       # CPU profiling with cargo-flamegraph (must be installed separately)
make doc-open      # Generate and open rustdoc documentation in a browser

Debug Logging

par-term uses a custom debug macro system that writes to par_term_debug.log in the system temp directory ($TMPDIR on macOS, /tmp on Linux, %TEMP% on Windows). The standard log crate macros (log::info!(), log::warn!(), etc.) write to stdout and will not appear in the debug log file.

Running with Debug Output

In one terminal, start par-term with debug logging enabled:

make run-debug    # DEBUG_LEVEL=3 — standard debug output → $TMPDIR/par_term_debug.log
make run-trace    # DEBUG_LEVEL=4 — most verbose, includes trace events

In a second terminal, monitor the log in real time:

make tail-log          # Stream all log entries
make watch-graphics    # Stream only graphics-related log entries

Debug Macro Reference

Always use these project-specific macros when adding log output to source code:

crate::debug_error!("CATEGORY", "message {}", var);  // DEBUG_LEVEL ≥ 1 — errors
crate::debug_info!("CATEGORY", "message {}", var);   // DEBUG_LEVEL ≥ 2 — informational
crate::debug_log!("CATEGORY", "message");            // DEBUG_LEVEL ≥ 3 — standard debug
crate::debug_trace!("CATEGORY", "message");          // DEBUG_LEVEL = 4 — trace/verbose

Common log categories: TAB, TAB_BAR, TAB_ACTION, MOUSE, RENDER, SHADER, TERMINAL, APP

For the full logging documentation, see docs/LOGGING.md.

ACP Agent Debugging

When debugging the Assistant Panel (Claude/Ollama ACP integration):

make acp-harness ARGS="--list-agents"   # Verify agent discovery and config loading
make acp-smoke                           # Run the reproducible shader prompt smoke test

See docs/ACP_HARNESS.md for full usage details and transcript capture.

Architecture Overview

For a detailed description of the codebase structure, data flow, threading model, and GPU rendering pipeline, see docs/architecture/ARCHITECTURE.md.

Key layers:

App (src/app/)
  └── Terminal (par-term-terminal/src/)
        └── Renderer (par-term-render/src/)
              └── GPU Shaders (par-term-render/src/shaders/)

Data flow:

Window Events → Input Handler → PTY → VT Parser → Styled Segments
  → GPU Renderer (three passes: cells → graphics → egui overlay)

Key implementation patterns:

  • Tokio runtime for async PTY I/O; sync wrappers bridge to the winit event loop
  • Glyph atlas with instanced rendering for efficient text output
  • RGBA texture caching for inline graphics (Sixel, iTerm2, Kitty)
  • Scrollback buffer with viewport offset rendering

Code Style

File Size Targets

  • Target: Keep all source files under 500 lines.
  • Refactor threshold: Any file exceeding 800 lines must be split into sub-modules.
  • Follow the existing patterns: src/app/, par-term-terminal/src/, par-term-render/src/.
  • Centralize constants; avoid magic numbers scattered across files.
  • Prefer composition over duplication; create helper traits for shared functionality.

Documentation Standards

Use /// doc comments for all public API items (structs, enums, traits, public functions and methods). Use // inline comments for implementation notes and non-obvious logic. Focus comments on why rather than what — the code already shows what is happening.

/// Renders all visible cells for the current viewport into the GPU instance buffer.
///
/// Must be called once per frame before `submit_render_pass`.
pub fn upload_cells(&mut self, cells: &[StyledCell]) { ... }

// Skip zero-width cells — they have no visual representation and will corrupt
// the atlas packing algorithm if submitted.
if cell.width == 0 {
    continue;
}

Concurrency Rules

  • Use try_lock() from synchronous contexts when accessing tab.terminal (tokio::sync::Mutex).
  • For user-initiated operations (e.g., start/stop coprocess), use blocking_lock() instead.
  • Never call process::exit() directly — use the graceful shutdown path.

macOS-Specific Notes

  • GPU backend: Metal
  • Platform-specific code: src/macos_metal.rs
  • App bundle commands:
    make bundle          # Create par-term.app in target/release/bundle/
    make bundle-install  # Install .app to /Applications, binary to ~/.cargo/bin, and ACP bridge
    make run-bundle      # Build and launch the .app (shows the correct dock icon)
  • When testing code changes, always run from the build output (make run) rather than the installed .app bundle. The bundle will not reflect your local changes.

Linux-Specific Notes

  • GPU backend: Vulkan
  • Both X11 and Wayland display servers are supported.
  • Install the required system libraries listed in Platform-Specific Requirements before your first build.

Windows-Specific Notes

  • GPU backend: DirectX 12
  • No additional system libraries are required beyond the Rust stable toolchain.

Configuration

The configuration file uses the XDG base directory convention:

  • Linux / macOS: ~/.config/par-term/config.yaml
  • Windows: %APPDATA%\par-term\config.yaml

See par-term-config/src/config/config_struct/mod.rs for all available settings and their defaults. For a human-readable reference, see docs/CONFIG_REFERENCE.md.

To generate an example configuration file:

make config-example    # Writes config.yaml.example to the project root

Common Development Workflows

Adding a Configuration Option

  1. Add the field to the sub-config for its area, par-term-config/src/config/config_struct/<area>_config.rs, not to the root Config in config_struct/mod.rs, with a serde default attribute:
    #[serde(default = "default_my_option")]
    pub my_option: MyType,
  2. Implement the default_my_option function and use the same expression in that sub-config's Default impl.
  3. Use the config value in the relevant component.
  4. Required: Add UI controls in the appropriate settings tab (par-term-settings-ui/src/<name>_tab/). Set settings.has_changes = true and *changes_this_frame = true when the value changes.
  5. Settings search finds the new control by its label and tooltip automatically, as long as it is drawn inside a collapsing_section/keyword_section. Add .search_tag(&["my_option"]) to its response so the YAML key is searchable too.

Adding a Keyboard Shortcut

  1. Add key handling in src/app/input_events/ (a directory with 6+ files; the main dispatch logic is in keybinding_actions.rs).
  2. If the shortcut generates a terminal sequence, add sequence generation in par-term-input/src/key_encoding.rs; InputHandler is defined in par-term-input/src/lib.rs.

For snippet or action keybindings, see docs/features/SNIPPETS.md. Key points:

  • Snippets use snippet:<id>, actions use action:<id> as keybinding action names.
  • Bindings are auto-generated during config load via generate_snippet_action_keybindings().
  • execute_keybinding_action() in src/app/input_events/keybinding_actions.rs handles execution.

Sub-Crate Architecture

par-term is organized as a Cargo workspace with 13 sub-crates plus the root application crate. The dependency graph is a strict layered DAG.

Dependency Layers

Layer Crates Notes
Layer 0 par-term-acp, par-term-ssh, par-term-mcp No internal deps; bump in any order
Layer 1 par-term-config Foundation; a pure-data crate with no workspace dependencies. It does not depend on par-term-emu-core-rust — the Unicode types it needs are defined locally in src/types/.
Layer 2 par-term-fonts, par-term-input, par-term-keybindings, par-term-scripting, par-term-settings-ui, par-term-terminal, par-term-tmux, par-term-update All depend on par-term-config
Layer 3 par-term-render Depends on par-term-config and par-term-fonts
Layer 4 par-term (root) Depends on all of the above

Version Bump Checklist

When bumping sub-crate versions for crates.io publishing, follow dependency order. Update both the crate's own version field and any version = "..." in dependents' Cargo.toml references.

  1. Bump par-term-config version and update references in all Layer 2/3 crates
  2. Bump Layer 0 crate versions
  3. Bump Layer 2 crate versions
  4. Bump par-term-render version and update its par-term-fonts reference
  5. Update all version references in root Cargo.toml
  6. Run cargo check to verify

PR Guidelines

  1. Fork the repository and create a feature branch from main.
  2. Make atomic commits — one logical change per commit.
  3. Run make checkall and confirm it passes without errors before pushing.
  4. Open a pull request against main.
  5. Describe your changes clearly in the PR body. The PR title and description become the squash commit message on main.
  6. PRs are merged via squash merge to keep the main branch history linear. Feature branches are deleted after merge.

What "Atomic" Means

Each commit should:

  • Compile and pass all tests on its own
  • Have a single, clear purpose that can be stated in one sentence
  • Not mix refactoring with behavior changes

Before Submitting

  • make checkall passes without errors or warnings
  • New behavior is covered by tests where practical
  • Public API additions carry /// doc comments
  • Settings additions update both the settings tab and the search keywords

Commit Message Format

<type>(<scope>): <subject>

[optional body — 72-character wrapped lines explaining what and why]

[optional footer — e.g., Closes #123]

Commit Types

Type When to use
feat A new feature
fix A bug fix
perf A performance improvement
refactor Code restructuring with no behavior change
test Adding or correcting tests
docs Documentation only
style Formatting or whitespace, no logic change
chore Build system, dependency updates, tooling

Rules

  • Subject line: maximum 50 characters, imperative mood ("add", "fix", "remove"), no trailing period.
  • Body: wrap at 72 characters; explain why, not what.
  • Footer: reference issues with Closes #123 or Fixes #456.

Examples

feat(tab-bar): add drag-and-drop reordering for tabs

Users can now drag tabs to reorder them within the tab bar.
Reorder state is persisted to the session arrangement file
so it survives restarts.

Closes #247
fix(renderer): clamp scrollback offset to valid range

A race between the PTY reader and the render thread could
produce a viewport offset larger than the scrollback buffer,
causing an out-of-bounds read in the cell upload path.
perf(render): pre-allocate GPU instance buffers

Avoids per-frame Vec reallocation for the cell and graphics
instance arrays by reserving capacity at startup based on
the initial terminal dimensions.

Release Checklist

When cutting a release, verify documentation stays internally consistent. GitHub strips punctuation and lowercases heading text to form anchors, so a heading rename silently breaks TOC links.

  • Release notes — replace the contents of the README's ## What's New section with the new release's highlights; do not append a second section. The heading is deliberately version-free so its #whats-new anchor never goes stale, and every earlier release already lives in CHANGELOG.md. Put the version in the ### subheading beneath it.
  • TOC anchors — after editing any heading in README.md, confirm every [link](#anchor) in the Table of Contents still resolves to a heading. make doc-check catches this automatically.
  • Version sync — Cargo.toml (version) and the top of CHANGELOG.md must agree before tagging. CLAUDE.md deliberately carries no version line: it had no consumer, silently fell two releases behind, and duplicating a version outside manifests and changelogs is what docs/DOCUMENTATION_STYLE_GUIDE.md advises against. Do not reintroduce one.
  • Tag the release — git tag v<X.Y.Z> <release-commit> && git push origin v<X.Y.Z>. Homebrew SHA, the self-update checker, and git describe all require the tag to be pushed.

Related Documentation