docs: add Cursor Cloud dev environment setup notes to AGENTS.md

Co-authored-by: Xuanwo <github@xuanwo.io>
2026-08-26 07:58:31 +00:00 · 2026-08-07 08:02:38 +00:00
1 changed files with 51 additions and 0 deletions
@@ -152,3 +152,54 @@ Please consider the following when reviewing code contributions.
 ### Documentation
 * New features must include updates to the rust documentation comments. Link to
  relevant structs and methods to increase the value of documentation.
+
+## Cursor Cloud specific instructions
+
+The VM snapshot already has the Rust `1.97.0` toolchain (auto-selected by
+`rust-toolchain.toml`), `protoc`, `uv` (on `PATH` via `~/.bashrc`), the Rust
+debug build artifacts, the Python editable extension, and `nodejs/node_modules`.
+The startup update script only refreshes dependencies (`uv sync` for Python and
+`pnpm install` for Node); it deliberately does NOT rebuild the native
+extensions. After changing Rust or PyO3/napi binding code you must rebuild the
+affected binding yourself (see per-binding rebuild commands below).
+
+Non-obvious caveats discovered during setup:
+
+* The documented Python bootstrap `uv run --extra tests --extra dev maturin
+  develop --extras tests,dev` does not work as-is here: `maturin` is not
+  installed as a CLI in the uv environment, and `maturin develop --extras`
+  runs its own dependency resolution that cannot find the prerelease
+  `pylance==9.0.0rc1` (it lacks the extra package index that `uv` uses via
+  `uv.lock`). Because `uv run --extra tests --extra dev` already installs those
+  extras, the working command is:
+  `cd python && uv run --extra tests --extra dev --with maturin maturin develop`
+  (note: `--with maturin`, and no `--extras`). This is the Python binding
+  rebuild command.
+* Rust core, the Python extension (maturin), and the Node addon (napi) all
+  compile into the SHARED `/workspace/target`. Cargo feature unification differs
+  between `maturin develop` and `pnpm build`, so alternating between building
+  the Python and Node bindings forces a full recompile of shared crates
+  (`lancedb`, `datafusion`, `lance-*`) — roughly 6-7 min each way on this
+  4-core VM. Build one binding at a time to avoid the churn.
+* The `_lancedb` release build (triggered when `uv run`/`uv sync` installs the
+  `lancedb` project itself) uses `lto = "fat"` + `opt-level = 3`, needs ~11 GB
+  RAM, and takes ~20 min cold on this VM. To avoid it, the update script uses
+  `uv sync --no-install-project --inexact` (the `--inexact` flag is required so
+  the sync does not uninstall the editable extension). Prefer the debug
+  `maturin develop` (~6 min cold, seconds when warm) for iteration.
+* `cargo check` only produces metadata, so the first `cargo run --example ...`
+  or `cargo test` after a check triggers a large codegen/link compile.
+* Node binding rebuild: `cd nodejs && pnpm build` (napi debug build + `tsc`).
+  The native addon lands at `nodejs/dist/lancedb.linux-x64-gnu.node`.
+
+Verified working (local backend, no cloud credentials needed):
+
+* Rust: `cargo check/clippy --features remote --tests --examples`,
+  `cargo test --features remote -p lancedb --lib`, `cargo run --features remote
+  --example simple`.
+* Python: `cd python && uv run --extra tests pytest python/tests/test_table.py`,
+  `uv run --directory python --extra dev ruff check python`.
+* Node: `cd nodejs && pnpm lint`, `pnpm test __test__/connection.test.ts`.
+
+Java (`java/`) is optional; its integration tests need LanceDB Cloud
+credentials (`LANCEDB_DB`, `LANCEDB_API_KEY`) and were not set up here.