Skip to content

SETUP.md

Latest commit

 

History

History
149 lines (100 loc) · 6.5 KB

SETUP.md

File metadata and controls

149 lines (100 loc) · 6.5 KB
Raw

Hum Setup

Date: 2026-07-06

Purpose

Hum should be easy to open from a terminal, VS Code, Cursor, PyCharm, IntelliJ, Neovim, Helix, Zed, or another editor without needing machine-specific paths.

The setup rule is:

portable defaults in the repo, personal editor state outside the repo

Beginner Path

  1. Install Git.
  2. Install Rust with rustup.
  3. Open a new terminal after installation so cargo is on PATH.
  4. From the repo root, run:
cargo test
cargo run -- version
cargo run -- doctor
cargo run -- check examples

If cargo is not found, fix the shell or editor environment so Cargo is on PATH. Do not copy a machine-specific Cargo path into docs, examples, scripts, or committed editor settings.

Distribution Stance

Cargo is normal for the Rust bootstrap compiler. It gives early contributors a boring way to build, test, and eventually install the CLI.

Cargo is not the whole adoption strategy. Hum should eventually offer:

  • prebuilt toolchains for Windows, macOS, and Linux
  • OS package manager paths such as winget, Homebrew, Scoop, and Linux packages
  • first-party hum, humfmt, hum lsp, hum graph, and nectar binaries
  • editor adapters that call the same first-party tools
  • setup docs that do not require Rust knowledge for beginners

Do not publish a public Cargo package until naming, license, README, security posture, release checks, and the first tag are intentional.

Full Local Verification

Run hum doctor first when you want a quick portable checkout health report. Run the full script before a serious commit, private push, public snapshot, or release-style handoff:

.\tools\check_all.ps1

Machine-readable setup health is available through:

cargo run -- doctor --format json

Before a tag, private-remote promotion, or public snapshot, run the clean-checkout smoke from a clean working tree:

.\tools\check_clean_checkout.ps1

Immediately before creating an annotated release tag, run:

.\tools\check_tag_readiness.ps1

That tag gate does not create a tag and does not touch remotes; it prints the exact human tag command only after the checks pass.

tools/check_clean_checkout.ps1 clones committed HEAD into an ignored target/clean-checkout directory and runs the same full preflight there. The normal preflight script runs Rust formatting, tests, clippy, example checks, reference fixture coverage, version, diagnostic-explain, diagnostic-catalog, graph, editor fixture recovery, and syntax JSON parsing, TextMate snapshot drift detection, whitespace checks, text hygiene, public readiness, and release readiness.

Hosted CI should call the same script, but the private pre-user repo uses guardrails to conserve hosted minutes. The current GitHub Actions workflow in ../.github/workflows/ci.yml runs on Windows and Linux for main pushes, v* tag pushes, and manual workflow_dispatch runs. It uses concurrency cancellation so a newer push cancels an older in-progress run on the same ref, and each matrix job has a 15-minute timeout. Pull-request CI stays off while the repo is private and single-maintainer.

Editor Setup

Hum does not require a blessed editor.

Use an editor that can:

  • open the repo root as a folder
  • respect .editorconfig
  • run Cargo commands from the integrated terminal or task runner
  • use rust-analyzer for the Rust bootstrap compiler
  • leave local workspace state uncommitted

Recommended editor behavior:

  • VS Code and Cursor: open the repo folder, install rust-analyzer, and keep local .vscode/, .cursor/, or workspace files untracked.
  • Visual Studio: use the integrated terminal or external tools for Cargo today. Keep .vs/, *.suo, *.user, and per-user launch state untracked. A VSIX should wait until hum lsp exists.
  • PyCharm, IntelliJ, Rider, RustRover, and other JetBrains IDEs: open the repo folder with Rust support enabled and keep .idea/ and *.iml files untracked.
  • Eclipse: use terminal Cargo commands today. Keep .metadata/, .settings/, .project, .classpath, .factorypath, and per-user .launch files untracked unless a future dedicated Eclipse adapter repo owns them.
  • Jupyter Notebook and JupyterLab: useful later for data and finance demos, but Milestone 0 has no execution kernel. Keep .ipynb_checkpoints/ untracked and do not commit exploratory notebooks to the core repo.
  • Neovim, Helix, Zed, Vim, Sublime Text, and similar editors: use rust-analyzer for Rust files and keep editor caches outside the repo.
  • Plain terminal users: Cargo commands are enough for Milestone 0.

Basic .hum syntax highlighting can start from ../editors/textmate/hum.tmLanguage.json, generated by tools/update_textmate_grammar.ps1 from hum syntax --format textmate. This grammar highlights the Milestone 0 surface only; until humfmt, chirp, and hum lsp exist, .hum files remain source sketches checked by the Rust bootstrap CLI.

Path Rules

Public docs, examples, tests, and scripts should use repo-relative paths:

examples/task_list.hum
docs/ARCHITECTURE.md
tools/check_text_hygiene.ps1

Avoid committing:

  • absolute Windows, macOS, Linux, WSL, or network-share paths
  • local home-directory paths
  • editor install paths
  • local Python, Rust, Java, or toolchain paths
  • per-user IDE task, launch, workspace, or interpreter files
  • shell-specific fixes that only work on one machine

If a command needs a local absolute path as a temporary workaround, keep it in your shell history, local editor settings, or private notes. The committed repo should show the portable command.

Troubleshooting

If Cargo works in a terminal but not in an editor, restart the editor after installing Rust. If it still fails, configure the editor's environment locally and leave that config uncommitted.

If Git warns about line endings, keep .gitattributes and .editorconfig in place. The repo normalizes text files to LF while allowing Windows batch files to use CRLF.

If a hygiene or public-readiness check fails, fix the named file and line before committing. These checks are meant to catch setup and pathing problems before new contributors inherit them.

Version And Tags

Current version: 0.0.1 pre-alpha. The bootstrap CLI reports this with:

cargo run -- version
cargo run -- version --format json

Before creating a release tag, run:

.\tools\check_release_readiness.ps1

See RELEASE_AND_VERSIONING.md for SemVer and tag policy.