Skip to content

Set up Cursor Cloud dev environment (AGENTS.md) #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
zinoe-1 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Set up Cursor Cloud dev environment (AGENTS.md) #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# AGENTS.md

## Cursor Cloud specific instructions

ScratchV is a pure-Python educational compiler (ONNX → RISC-V RV32IM machine code, plus an LLVM-IR path). There is no long-running server or web app; everything runs as CLI tools / pytest. The interactive "course site" and performance "dashboard" are static HTML files opened directly in a browser (`file://` paths), not a served application.

Standard commands live in the `Makefile`, `README.md`, and `CLAUDE.md` — refer to those rather than duplicating. Notable: `make test`, `make bench`, `make bench-cnn`, `make bench-tinyfive`, `make bench-ci`.

Non-obvious caveats discovered during setup:

- **Python**: the VM already has Python 3.12 as `python3`; use it directly (no venv needed). The dependency-refresh update script installs the package and dev tooling.
- **Dev/test tooling is NOT declared in `pyproject.toml`**: `pytest`, `flake8`, `mypy`, `black`, `isort`, `ruff` are installed by the update script, not by `pip install -e .`. `markdown` is only needed for building the docs HTML site (`scripts/build_docs_html.py`).
- **`~/.local/bin` is not on `PATH`**: invoke tools as modules, e.g. `python3 -m pytest`, `python3 -m ruff`, `python3 -m flake8`.
- **`tests/test_simulator.py` has 2 pre-existing failures** (`NameError: name 'load_asm' is not defined` in `scratchv/simulator/tinyfive.py`). CI deliberately skips this file. Run the suite the CI way: `python3 -m pytest tests/ --ignore=tests/test_simulator.py`.
- **`models/` is gitignored** but `models/graph/cnn.onnx` is present in the VM. If it is ever missing, regenerate a minimal model with `python3 scripts/gen_minimal_cnn.py`.
- **External RISC-V toolchains are not installed** (`llc`, `riscv64-*-gcc`, `spike`, `qemu-riscv32`). The core ScratchV native path and the `llvmlite`-based LLVM-IR generation both work without them, but the "LLVM vs ScratchV comparison" step in `make bench-ci` and some Spike/QEMU sim helpers will report `failed`/warnings. This is expected in this environment, not a regression.
- **Lint is best-effort and reports many pre-existing style findings** (ruff/flake8 E501/E741 etc.). Treat the tooling as "runs successfully"; do not attempt to fix pre-existing style issues unless asked.
- The `scratchv` package installs in editable mode, so source edits take effect immediately without reinstalling.