From 44f4b1d2550c619277fe05a76abb5cd199dd54db Mon Sep 17 00:00:00 2001 From: Younghwan Chae <48156556+younghwan91@users.noreply.github.com> Date: Tue, 27 Oct 2026 21:19:43 +0900 Subject: [PATCH] docs(contributing): list the native toolchain and system libraries a first pnpm install needs (#31592) Local Setup named only Node, pnpm, and Bun. A first pnpm install also compiles node-pty and the native addons with node-gyp and loads them in Electron, and *.electron.test.ts fall back to xvfb-run on headless Linux. Document the per-platform build toolchain, the Linux Electron runtime libraries plus xvfb, and the Corepack/pnpm version caveats. Fixes #31589 Co-authored-by: Neil Co-authored-by: Claude Opus 5.5 --- .github/CONTRIBUTING.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c8b4a15f508..db5c627444d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -21,6 +21,27 @@ Install Node 24, pnpm, and the Bun version in [`config/.bun-version`](../config/ native PTYs, socket liveness, and V8 memory behavior. `pnpm test:node` runs the same suites entirely on Node. Builds and dependency installation still use Node and pnpm. +Use the pnpm version in `packageManager` in [`package.json`](../package.json): `corepack enable` +needs Corepack 0.34.5 or newer to start the pinned pnpm (`npm install -g corepack@latest`). On +Windows it writes shims next to `node.exe` and fails with `EPERM` outside an elevated shell when +Node is in `C:\Program Files\nodejs`; run `npm install -g pnpm@` instead. + +`pnpm install` compiles native modules such as `node-pty` with `node-gyp` and loads them in +Electron, so a fresh machine also needs: + +- **macOS**: Xcode Command Line Tools (`xcode-select --install`). +- **Windows**: Python 3 and Visual Studio Build Tools with the "Desktop development with C++" + workload. +- **Linux**: a C++ toolchain, Python 3, and the libraries Electron loads even on a headless + machine, plus `xvfb`, which the `*.electron.test.ts` files in `pnpm test` use when `DISPLAY` is + unset. On Ubuntu 24.04+ and Debian 13+: + + ```bash + sudo apt-get update && sudo apt-get install -y build-essential python3 xvfb libgtk-3-0 libnss3 libgbm1 libasound2t64 + ``` + + Older releases name the last package `libasound2`. + ```bash pnpm install pnpm dev