Building PiCode

Building PiCode

PiCode's source is this repository: the VS Code-derived editor with every PiCode change committed as code, and the product identity in product.json at the root. There is nothing to download and nothing to apply — the tree already is PiCode. Releases are built from it, CI builds it, and a change in editor behaviour is written in TypeScript, in the tree, and compiled.

This page is for contributors. If you only want to use PiCode, take a prebuilt release — see Getting PiCode.

Where the pieces live: the build engine and its scripts are in build/, the first-run defaults and the pinned pi runtime in build/distribution/, and the VS Code version the tree descends from is recorded in host/upstream/stable.json. The fetch-and-patch machinery of the early days was deleted on 2026-09-27: anything it once produced is now ordinary code.

🔧 What you need on Windows

The scripts are Bash: run them from Git Bash (included in Git for Windows). PowerShell cannot run them.

Tool	Why	Install
Git for Windows	Git and Git Bash	winget install --id Git.Git -e
Node.js 24.20.0 (what .nvmrc says)	npm ci and the gulp tasks	nvm install 24.20.0
Python 3.11	VS Code's build asks for it for the native modules (node-gyp)	python.org
Rustup	Compiles the CLI and some native modules; it rewrites PATH, so restart the shell	winget install --id Rustlang.Rustup -e
7-Zip	Packs the .zip	winget install --id 7zip.7zip -e
Visual Studio 2022 (Community or Build Tools) with Desktop development with C++ and the Spectre libraries	node-gyp compiles with MSBuild; without Spectre the install stops with MSB8040	Visual Studio Installer

jq is not needed: the build reads and writes its JSON with node.

🏗️ The build

./build/build.sh        # install what is missing, compile, pack, stage
./build/build.sh -o     # check the source and stop — seconds, nothing installed or compiled
./build/build.sh -i     # install dependencies even if the recorded state still matches

Phase	What happens
1 · Prepare	Checks the source and the identity, installs dependencies only when the recorded state stops matching, and seals the release channel into product.json
2 · Connector	Compiles the extensions/picode connector
3 · Compile	Compiles the editor (the fast esbuild route, with a type-check gate)
4 · Pack	Produces PiCode-Win32-x64/
5 · Stage	build/stage-distribution.sh: portable data/ profile, first-run settings, icons and names, the pi runtime and the memory engine

A local build produces only the portable pack. The Windows installer is built only when it is asked for explicitly (PICODE_SKIP_INSTALLER=no), which is what the release pipeline does. build/build-window.cmd drives the same pipeline through a small window.

Where everything lands

Path	What it is
./ (the repository root)	PiCode's source. Edited, committed, and living here
./PiCode-Win32-x64	The pack output (phases 4 and 5), gitignored
./PiCode-Win32-x64/PiCode.exe	The executable built from source

A channel build (PICODE_CHANNEL=stable|beta|experimental) stamps its channel into product.json for the build and puts the original back when it ends — success, failure or Ctrl-C — so the tree is clean afterwards.

⬆️ Bringing a newer VS Code

A newer VS Code is a merge against the tree, not a download:

1. Fetch the new upstream tag and merge it into a working branch.
2. Resolve the conflicts — they are only where PiCode changed the same lines.
3. Update tag and commit in host/upstream/stable.json.
4. Check the tree is still what the build expects: ./build/build.sh -o.
5. Build, and confirm the editor starts.

The version a release carries is read from product.json, its only home.

🩺 If it fails

• MSB8040 → the Spectre libraries are missing (see the table above).
• npm ci failing once and then continuing → normal, the pipeline retries.
• The editor built but behaves oddly → see the verification checklist in Distribution and Licensing; a PiCode.exe reading ARM64 binaries on x64 passes every file-level check, so verify the PE machine type of any archive you build on.

PiCode builds for Windows only today.

---

Related: Architecture · CI and Releases · Distribution and Licensing