Free games for graphing calculators: NumWorks, TI-Nspire CX, Casio fx-CG50 and soon TI-84 Plus CE. Balatro, Celeste, Hollow Knight, Minecraft and more.
C calculatorcalculator-gamescasiochesscrossy-roaddrive-madfx-cg50gamesgeometry-dashgraphing-calculatorndlessnumworksnumworks-appsnumworks-calculatornumworks-gamenumworks-gamestetristi-84-plus-ceti-nspire
#!/usr/bin/env python3
"""Build NumPlay .nwa files on Windows, macOS and Linux.
Requirements: Git for Windows (Git Bash), GNU Make 4.4.1 for Windows, Node.js/npm,
Python, Rust/rustup and a native Windows arm-none-eabi-gcc toolchain.
Run from PowerShell (Windows) or a terminal (macOS/Linux):
python tools/build.py --doctor
python tools/build.py --launcher-only --skip-languages -j2
python tools/build.py --organize-only
python tools/build.py --watch --launcher-only --skip-languages -j2
It keeps Make's intermediate outputs under build/data/ and atomically
exports finished calculator apps into top-level build/compiled/, including the stable
live-emulator input build/compiled/NumPlay.nwa. `--watch` monitors source edits and
rebuilds incrementally, publishing only after successful builds. `--organize-only`
exports an existing successful build with no toolchain necessary.
It also finds an existing Rustup installation under the current user's
.cargo/bin even when VS Code did not refresh PATH; no permanent environment
changes are needed. The Tetris nwlink.exe bridge and Windows-specific
dependency installers are preserved unchanged. This script does not modify emulator code.
"""
from __future__ import annotations
import argparse
import hashlib
import re
import time
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
import urllib.error
import urllib.request
import zipfile
ROOT = Path(__file__).resolve().parent.parent
TOOL_VERSION = "15.2.1-1.1" # Same xPack GCC version as CI on Oct 19, 2026.
TOOL_NAME = f"xpack-arm-none-eabi-gcc-{TOOL_VERSION}-win32-x64.zip"
TOOL_URL = ("https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/"
f"download/v{TOOL_VERSION}/{TOOL_NAME}")
TOOL_SHA256 = "bae6a3d1667697ce750c3b13d6d26d80973ecedc2cc87bf04869e83447fd93ea"
ARM_BASE = Path(os.environ.get("LOCALAPPDATA", Path.home())) / "NumPlay" / "toolchains"
OUTPUT = ROOT / "build" / "compiled"
RUST_TARGET = "thumbv7em-none-eabihf"
# GnuWin32 Make 3.81 (often installed by winget) can crash with 0xc0000005
# before running any recipe on Windows 11. Prefer portable GNU Make 4.4.1.
MAKE_VERSION = "4.4.1"
MAKE_ARCHIVE = "make-4.4.1-without-guile-w32-bin.zip"
MAKE_URL = ("https://sourceforge.net/projects/ezwinports/files/"
f"{MAKE_ARCHIVE}/download")
# Published by SourceForge and Chocolatey's verified GNU Make 4.4.1 package.
MAKE_SHA256 = "fb66a02b530f7466f6222ce53c0b602c5288e601547a034e4156a512dd895ee7"
MAKE_BASE = ARM_BASE.parent / "make"
MAKE_ROOT = MAKE_BASE / f"make-{MAKE_VERSION}"
def where(name: str) -> Path | None:
candidate = shutil.which(name)
# Rustup's Windows command proxies (rustc.exe, cargo.exe, etc.) may be
# links to rustup.exe. Their invoked file name is important: rustup.exe
# behaves differently from rustc.exe. Never resolve proxy links here.
return Path(os.path.abspath(candidate)) if candidate else None
def ensure_rust_on_path() -> Path | None:
"""Use the current user's *installed* Windows Rust tools despite a stale PATH.
The Rustup installer normally places cargo.exe and rustup.exe in
%USERPROFILE%\\.cargo\\bin. VS Code's integrated terminal can inherit an
older process environment after the user PATH was updated. Prepending the
verified installation to this script's process PATH also makes it visible
to Cargo and Git Bash subprocesses. This does not modify the registry or
require administrative rights. Never replace the rustup proxy filenames
with their resolved filesystem targets.
"""
if os.name != "nt":
return None
if (where("cargo.exe") or where("cargo")) and (where("rustup.exe") or where("rustup")):
return None
cargo_home = Path(os.environ.get("CARGO_HOME", str(Path.home() / ".cargo"))).expanduser()
cargo_bin = cargo_home / "bin"
if not (cargo_bin / "rustup.exe").is_file() or not (cargo_bin / "cargo.exe").is_file():
return None
# PATH here is only changed inside this running Python process (and its
# children), never for PowerShell, Windows or other apps.
existing = os.environ.get("PATH", "")
normalized = lambda p: os.path.normcase(os.path.normpath(p.strip('"')))
if normalized(str(cargo_bin)) not in {normalized(p) for p in existing.split(os.pathsep) if p}:
os.environ["PATH"] = str(cargo_bin) + os.pathsep + existing
return cargo_bin
def git_bash() -> Path | None:
# Never accidentally launch the WSL bash.exe from System32.
candidates = []
for env in ("ProgramFiles", "ProgramFiles(x86)", "LOCALAPPDATA"):
base = os.environ.get(env)
if base:
candidates += [Path(base) / "Git" / "bin" / "bash.exe",
Path(base) / "Programs" / "Git" / "bin" / "bash.exe"]
g = where("git.exe") or where("git")
if g:
# git.exe normally lives in Git/cmd/, Git/bin/ or Git/mingw64/bin/.
for folder in (g.parent, *list(g.parents)[:3]):
candidates += [folder / "bin" / "bash.exe", folder / "usr" / "bin" / "bash.exe"]
b = where("bash.exe")
if b and "system32" not in str(b).lower():
candidates.append(b)
return next((x for x in candidates if x.is_file()), None)
def make_version(exe: Path) -> tuple[int, int, int] | None:
"""Probe actual GNU Make version; PATH presence alone is not enough."""
try:
p = subprocess.run([str(exe), "--version"], capture_output=True,
text=True, timeout=10, check=False)
except (OSError, subprocess.TimeoutExpired):
return None
if p.returncode:
return None
import re
m = re.search(r"GNU Make\s+(\d+)\.(\d+)(?:\.(\d+))?", p.stdout)
if not m:
return None
return (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
def make_supported(exe: Path | None) -> bool:
version = make_version(exe) if exe else None
return version is not None and version >= (4, 0, 0)
def find_make() -> tuple[Path | None, str]:
# Prefer the verified portable version even when GnuWin32 make.exe appears
# earlier on PATH (e.g., C:\Program Files (x86)\GnuWin32\bin).
candidates: list[Path] = []
preferred = os.environ.get("NUMPLAY_MAKE_EXE")
if preferred:
candidates.append(Path(preferred).expanduser())
candidates.extend([MAKE_ROOT / "bin" / "make.exe",
MAKE_ROOT / "make.exe",
*(list(MAKE_ROOT.rglob("make.exe")) if MAKE_ROOT.is_dir() else []),
Path.home() / "scoop/apps/make/current/bin/make.exe",
Path.home() / "scoop/shims/make.exe"])
for name in ("make.exe", "make", "mingw32-make.exe", "mingw32-make"):
p = where(name)
if p:
candidates.append(p)
candidates.extend([
Path(os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")) / "GnuWin32/bin/make.exe",
Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "GnuWin32/bin/make.exe",
])
seen: set[str] = set()
old: Path | None = None
for candidate in candidates:
key = str(candidate).lower()
if key in seen or not candidate.is_file():
continue
seen.add(key)
version = make_version(candidate)
if version and version >= (4, 0, 0):
return candidate, candidate.stem
if version and old is None:
old = candidate
return (old, old.stem) if old else (None, "make")
def install_make(archive_override: Path | None = None) -> Path:
"""Install verified portable Windows GNU Make; never touch system PATH."""
if os.name != "nt":
raise RuntimeError("The Windows Make installer must run on Windows.")
existing = MAKE_ROOT / "bin" / "make.exe"
if make_supported(existing):
print("Modern GNU Make is already installed:", existing)
return existing
MAKE_BASE.mkdir(parents=True, exist_ok=True)
archive = MAKE_BASE / MAKE_ARCHIVE
if archive_override is not None:
archive = archive_override.expanduser().resolve()
if not archive.is_file():
raise RuntimeError(f"GNU Make ZIP not found: {archive}")
if not archive.is_file():
print("Downloading portable GNU Make 4.4.1 for Windows (~400 KB):")
print(MAKE_URL)
# SourceForge responds with a mirror redirect. A verified SHA-256 guards
# against a mirror returning HTML or unexpected/untrusted bytes.
request = urllib.request.Request(MAKE_URL,
headers={"User-Agent": "NumPlay-Windows-Builder/3"})
try:
with urllib.request.urlopen(request, timeout=90) as response, archive.open("wb") as f:
total = 0
while block := response.read(64 * 1024):
total += len(block)
if total > 16 * 1024 * 1024:
raise RuntimeError("Unexpectedly large GNU Make archive; aborted")
f.write(block)
except Exception:
archive.unlink(missing_ok=True)
raise
print("Verifying GNU Make archive SHA-256...")
with archive.open("rb") as f:
digest = hashlib.file_digest(f, "sha256").hexdigest()
if digest != MAKE_SHA256:
if archive_override is None:
archive.unlink(missing_ok=True)
raise RuntimeError("GNU Make ZIP SHA-256 mismatch (or HTML mirror page). "
"Try downloading the ZIP from SourceForge in your browser "
"and passing --make-zip PATH.")
# Reject arbitrary path traversal as a defense in depth.
with zipfile.ZipFile(archive) as z:
members = z.infolist()
if any(name.filename.startswith(("/", "\\")) or ".." in Path(name.filename).parts
or ":" in name.filename for name in members):
raise RuntimeError("Unexpected paths in the GNU Make ZIP")
z.extractall(MAKE_ROOT)
found = [p for p in MAKE_ROOT.rglob("make.exe") if make_supported(p)]
if not found:
raise RuntimeError("GNU Make executable was not found in the archive")
exe = found[0]
print("Installed portable GNU Make:", exe)
return exe
def find_arm() -> Path | None:
hint = os.environ.get("NUMPLAY_ARM_GCC_BIN")
if hint:
p = Path(hint).expanduser()
if (p / "arm-none-eabi-gcc.exe").is_file():
return p
gcc = where("arm-none-eabi-gcc.exe") or where("arm-none-eabi-gcc")
if gcc:
return gcc.parent
candidates = [ARM_BASE / f"xpack-arm-none-eabi-gcc-{TOOL_VERSION}" / "bin"]
candidates += list(ARM_BASE.glob("*/bin")) if ARM_BASE.is_dir() else []
roaming = Path(os.environ.get("APPDATA", Path.home())) / "xPacks" / "arm-none-eabi-gcc"
candidates += list(roaming.glob("*/bin")) if roaming.is_dir() else []
return next((p for p in candidates if (p / "arm-none-eabi-gcc.exe").is_file()), None)
def rust_target_installed() -> bool:
if not where("rustup.exe") and not where("rustup"):
return False
try:
result = subprocess.run(["rustup", "target", "list", "--installed"],
text=True, capture_output=True, timeout=20, check=False)
return result.returncode == 0 and RUST_TARGET in result.stdout.splitlines()
except (OSError, subprocess.TimeoutExpired):
return False
def python_packages() -> list[str]:
missing = []
for name, module in (("pillow", "PIL"), ("numpy", "numpy"),
("zopfli", "zopfli"), ("pyelftools", "elftools")):
try:
__import__(module)
except ImportError:
missing.append(name)
return missing
def doctor() -> bool:
print("\nNumPlay Windows build tool check (native Windows; no WSL)")
print("Repository:", ROOT)
b = git_bash()
make, _ = find_make()
version = make_version(make) if make else None
make_ok = make_supported(make)
arm = find_arm()
node = where("node.exe") or where("node")
npx = where("npx.cmd") or where("npx")
cargo = where("cargo.exe") or where("cargo")
rustup = where("rustup.exe") or where("rustup")
tools = [("Git Bash", b), ("GNU Make 4+", make if make_ok else None),
("ARM GCC (Windows)", arm / "arm-none-eabi-gcc.exe" if arm else None),
("Node.js", node), ("npx", npx), ("Cargo", cargo), ("rustup", rustup)]
for name, value in tools:
if name == "GNU Make 4+" and not value and make is not None:
print(f" OLD {name:<18} {make} (version {'.'.join(map(str, version)) if version else 'broken'})")
else:
print(f" {'OK ' if value else 'MISSING'} {name:<18} {value or ''}")
rt = rust_target_installed()
print(f" {'OK ' if rt else 'MISSING'} Rust target {RUST_TARGET}")
missing = python_packages()
print(f" {'MISSING' if missing else 'OK '} Python packages {', '.join(missing) if missing else 'all installed'}")
show_instructions = not all(v for _, v in tools) or not rt or bool(missing)
print("\nMissing-tool instructions:" if show_instructions else "\nAll required tools detected.")
if not b:
print(" Git for Windows: https://git-scm.com/downloads/win (includes Git Bash; NOT Linux)")
if not make_ok:
print(" GNU Make 4.4.1: python tools/build.py --install-make")
print(" (Portable Windows binary; ~400 KB; no administrator privileges or PATH change)")
if not arm:
print(" ARM compiler: python tools/build.py --install-arm")
print(" (Downloads official xPack Windows compiler, about 320 MB, SHA-256 verified)")
if not node or not npx:
print(" Node.js: winget install --id OpenJS.NodeJS.LTS -e")
if not rustup or not cargo:
print(" Rust: https://rustup.rs/ (choose the Windows toolchain)")
elif not rt:
print(f" rustup target add {RUST_TARGET}")
if missing:
print(f" {sys.executable} -m pip install {' '.join(missing)}")
ok = (os.name == "nt" and all(v for _, v in tools) and rt and not missing)
if os.name != "nt":
print(" This helper intentionally runs only on native Windows.")
print("\n" + ("Ready to build!" if ok else "Complete the missing requirements above, then rerun --doctor."))
return ok
def install_arm() -> Path:
existing = find_arm()
if existing:
print("ARM GCC is already installed:", existing)
return existing
if os.name != "nt":
raise RuntimeError("The Windows compiler installer must run on Windows.")
ARM_BASE.mkdir(parents=True, exist_ok=True)
archive = ARM_BASE / TOOL_NAME
if not archive.is_file():
print("Downloading the official Windows ARM compiler (~320 MB):")
print(TOOL_URL)
with urllib.request.urlopen(TOOL_URL, timeout=120) as response, open(archive, "wb") as out:
total = 0
while block := response.read(1024 * 1024):
out.write(block)
total += len(block)
if total % (32 * 1024 * 1024) == 0:
print(f" {total // (1024 * 1024)} MB received", flush=True)
print("Checking the official archive SHA-256...")
digest = hashlib.sha256()
with archive.open("rb") as src:
for block in iter(lambda: src.read(4 * 1024 * 1024), b""):
digest.update(block)
if digest.hexdigest() != TOOL_SHA256:
archive.unlink(missing_ok=True)
raise RuntimeError("ARM compiler SHA-256 mismatch: archive removed; installation aborted.")
print("Extracting ARM compiler into", ARM_BASE)
with zipfile.ZipFile(archive) as z:
z.extractall(ARM_BASE)
installed = find_arm()
if not installed:
raise RuntimeError("Extracted compiler not found. Check the archive layout.")
print("ARM compiler ready:", installed)
return installed
def ensure_build_directories(build: Path | None = None) -> tuple[Path, ...]:
"""Repair an incomplete build tree without deleting any existing outputs.
The root Makefile creates build/data/arm, build/data/modules, etc. inside the recipe
for the `build` directory. If build/data/ *already exists* (for example after
an interrupted attempt, or after a previous failed Make invocation), Make
skips that recipe. Parallel ARM compiler jobs then fail with an interleaved
`can't create build/data/arm/*.o: No such file or directory` error.
These directories are always safe to create ahead of Make, and the rest
remain governed by the repo's Makefile. Creating them before starting
any parallel build jobs also removes a directory-creation race.
"""
build = ROOT / "build" / "data" if build is None else build
relative = ("modules", "gen", "arm", "apps", "sim", "variant",
"tetris", "gen-upsilon", "arm-upsilon", "lang")
created = []
build.mkdir(parents=True, exist_ok=True)
for name in relative:
folder = build / name
if not folder.is_dir():
folder.mkdir(parents=True, exist_ok=True)
created.append(folder)
return tuple(created)
# The Rust Tetris build script calls Command::new("nwlink") at build.rs:16.
# Unlike a shell, Rust's Windows process launcher does not find npm's .cmd
# shims from that extensionless name. Supply an actual nwlink.exe on PATH.
# We compile it with the Windows rustc the project already requires.
# The adapter delegates to the exact pinned nwlink package used by Make.
NWLINK_BRIDGE_RS = r"""
use std::env;
use std::process::{Command, Stdio};
fn main() {
let mut child = Command::new("npx.cmd");
child.args(["--yes", "--", "[email protected]"]);
child.args(env::args_os().skip(1));
child.stdin(Stdio::inherit())
.stdout(Stdio::inherit())
.stderr(Stdio::inherit());
match child.status() {
Ok(status) => std::process::exit(status.code().unwrap_or(1)),
Err(e) => {
eprintln!("NumPlay nwlink bridge could not launch npx.cmd: {e}");
std::process::exit(1);
}
}
}
"""
def create_nwlink_bridge(shims: Path) -> Path:
"""Make a *Windows* nwlink.exe for Cargo's direct process invocation.
The source is fixed, generated locally and built with the user's own
installed Rust compiler; it has no external dependencies or downloads.
Both source and exe live in the temporary helper folder and are removed
when the build ends. It never edits games/tetris/tetris/build.rs.
"""
# Don't use Path.resolve() on ~/.cargo/bin/rustc.exe: it can resolve
# Rustup's rustc proxy to rustup.exe. Rustup then receives --edition as
# its own argument and fails with "unexpected argument '--edition'".
# `rustup which rustc` instead locates the real host compiler binary.
rustup = shutil.which("rustup.exe") or shutil.which("rustup")
if not rustup:
raise RuntimeError("Rustup was not found in PATH; ensure .cargo\\bin is on PATH")
located = subprocess.run([rustup, "which", "rustc"],
text=True, capture_output=True, check=False)
if located.returncode:
raise RuntimeError("Rustup could not locate the host Rust compiler. "
"Try: rustup default stable\n"
+ (located.stderr or located.stdout))
rustc = Path(located.stdout.strip().strip('"'))
if not rustc.is_file():
raise RuntimeError(f"Rustup reported a missing Rust compiler: {rustc}")
src = shims / "numplay_nwlink_bridge.rs"
exe = shims / "nwlink.exe"
src.write_text(NWLINK_BRIDGE_RS, encoding="utf-8", newline="\n")
print("Preparing temporary Windows nwlink.exe bridge for Tetris...", flush=True)
try:
completed = subprocess.run([str(rustc), "--edition=2021",
"--crate-name", "numplay_nwlink_bridge",
"-C", "opt-level=0", str(src), "-o", str(exe)],
cwd=ROOT, text=True, capture_output=True, check=False)
except OSError as exc:
raise RuntimeError(f"Could not start Rust compiler {rustc}: {exc}") from exc
if completed.returncode or not exe.is_file():
raise RuntimeError("Could not compile Windows nwlink bridge using rustc.\n"
+ (completed.stderr or completed.stdout or "unknown error"))
return exe
def run_bash(bash: Path, make: Path, make_name: str, arm: Path, jobs: int,
*, apps: bool, check: bool, langs: bool, target_args: list[str] | None = None) -> None:
# Ensure make's directories exist even when build/ was created by an
# interrupted earlier run. Keep all existing compiled files for a retry.
created = ensure_build_directories()
if created:
print(f"Prepared {len(created)} missing build directories "
f"(including build/arm); keeping existing build files.", flush=True)
# Git Bash supplies sh/cp/mkdir/wc/etc., but every compiler and runtime
# launched by it is the normal Windows executable, not a Linux program.
with tempfile.TemporaryDirectory(prefix="numplay-win-") as td:
shims = Path(td)
python3 = shims / "python3"
python3.write_text('#!/bin/sh\nexec "$NUMPLAY_PYTHON_POSIX" "$@"\n', encoding="utf-8", newline="\n")
# 'nwlink' in Tetris's Rust build.rs is launched without a .cmd
# extension, so give Cargo a real executable to find in PATH.
create_nwlink_bridge(shims)
env = os.environ.copy()
env.update({"NUMPLAY_MAKE_BIN": str(make.parent), "NUMPLAY_ARM_BIN": str(arm),
"NUMPLAY_PYTHON_EXE": sys.executable, "NUMPLAY_SHIMS": str(shims)})
prefix = r'''set -e
export NUMPLAY_PYTHON_POSIX="$(cygpath -u "$NUMPLAY_PYTHON_EXE")"
export PATH="$(cygpath -u "$NUMPLAY_SHIMS"):$(cygpath -u "$NUMPLAY_ARM_BIN"):$(cygpath -u "$NUMPLAY_MAKE_BIN"):$PATH"
chmod +x "$(cygpath -u "$NUMPLAY_SHIMS")/python3"
command -v sh >/dev/null || { echo 'Git Bash sh is unavailable'; exit 1; }
command -v arm-none-eabi-gcc >/dev/null || { echo 'ARM GCC is unavailable from Git Bash'; exit 1; }
command -v node >/dev/null || { echo 'Node.js is unavailable from Git Bash'; exit 1; }
command -v python3 >/dev/null || { echo 'Python is unavailable from Git Bash'; exit 1; }
command -v nwlink >/dev/null || { echo 'Tetris nwlink bridge is unavailable from Git Bash'; exit 1; }
'''
common = ["NWLINK=npx --yes -- [email protected]", "SHELL=sh"]
def invoke(args: list[str]) -> None:
import shlex
command = " ".join(shlex.quote(arg) for arg in [make_name, *args, *common])
print("\nBuilding: ", command, flush=True)
completed = subprocess.run([str(bash), "--noprofile", "--norc", "-c", prefix + "\n" + command],
cwd=ROOT, env=env, check=False)
if completed.returncode:
raise RuntimeError(f"GNU Make exited with code {completed.returncode} (build stopped)")
if target_args is not None:
invoke([f"-j{jobs}", *target_args])
else:
targets = ["nwa"]
if apps or check:
targets.append("apps")
if check:
targets.append("check")
invoke([f"-j{jobs}", *targets])
if langs:
invoke(["lang"])
# Publish end-user .nwa files outside Make's internal build/data directory.
# The root Makefile uses B = build/data.
# The stable live path can later be supplied to emulator.py for auto-reload.
LIVE_DIR = "live"
VARIANT_DIR = "variants"
GAME_DIR = "games"
LANGUAGE_DIR = "languages"
LANGUAGE_VARIANTS = ("NumPlay-French.nwa", "NumPlay-Chinese.nwa")
def destination_for(name: str, output: Path) -> Path:
if name == "NumPlay.nwa":
return output / name
if name in LANGUAGE_VARIANTS:
return output / name
if name.startswith("NumPlay-") and name.endswith(".nwa"):
return output / name
return output / GAME_DIR / name
def atomic_copy(src: Path, dest: Path) -> None:
"""Do not expose partly written files to a future live emulator.
Windows can temporarily block os.replace when another process has the file
open. Keep the old export on such failures and retry briefly.
"""
dest.parent.mkdir(parents=True, exist_ok=True)
# Unique temporary file in the destination directory ensures atomic rename.
tmp_name = None
try:
with tempfile.NamedTemporaryFile(prefix="." + dest.name + ".",
suffix=".tmp", dir=dest.parent,
delete=False) as temp:
tmp_name = Path(temp.name)
with src.open("rb") as source:
shutil.copyfileobj(source, temp, length=1024 * 1024)
temp.flush()
os.fsync(temp.fileno())
for attempt in range(10):
try:
os.replace(tmp_name, dest)
tmp_name = None
return
except PermissionError:
if attempt == 9:
raise
time.sleep(0.2)
finally:
if tmp_name:
tmp_name.unlink(missing_ok=True)
def collect_sources(*, apps: bool, langs: bool) -> list[Path]:
build = ROOT / "build" / "data"
# Never include existing build/compiled/ files: only fresh Makefile output sources.
sources = list(sorted(build.glob("NumPlay*.nwa")))
if not langs:
sources = [p for p in sources if p.name not in LANGUAGE_VARIANTS]
if apps:
sources.extend(sorted((build / "apps").glob("*.nwa")))
return sources
def publish_outputs(*, apps: bool, langs: bool, output: Path = OUTPUT,
verbose: bool = True) -> list[Path]:
"""Organize completed binaries, leaving compiler artifacts in build/data/.
If a build fails this function isn't called, so the last successful live
binary remains untouched. No .nwa source or compiler object is deleted.
"""
sources = collect_sources(apps=apps, langs=langs)
if not sources:
raise RuntimeError("No .nwa files found inside build/data/. Run a build first.")
# Keep these generated binary exports out of git status without touching
# the project's tracked root .gitignore. A lone '*' ignores this file too.
output.mkdir(parents=True, exist_ok=True)
ignore = output / ".gitignore"
if not ignore.exists():
ignore.write_text("*\n", encoding="utf-8")
published: list[Path] = []
# Publish user-facing variants and standalone games first.
# Publish the stable live file *last*, marking the completed build.
main_src = None
ordered_sources = [p for p in sources if p.name != "NumPlay.nwa"]
ordered_sources += [p for p in sources if p.name == "NumPlay.nwa"]
for src in ordered_sources:
if src.name == "NumPlay.nwa":
main_src = src
dest = destination_for(src.name, output)
atomic_copy(src, dest)
published.append(dest)
if verbose:
print(f"\nSUCCESS: organized {len(sources)} calculator app(s) in:", output)
for path in published:
print(" " + str(path.relative_to(output)))
if main_src:
print("\nStable live-emulator input: " + str(output / "NumPlay.nwa"))
return published
def safe_remove_legacy_duplicates(output: Path = OUTPUT) -> None:
"""Opt-in cleanup of only byte-identical earlier exports in build/windows-nwa.
Do not delete anything that wasn't safely copied into build/compiled/. No recursive
deletion; unknown or changed files are left exactly as they were.
"""
legacy = ROOT / "build" / "windows-nwa"
if not legacy.is_dir():
print("No old build/windows-nwa/ export folder to tidy.")
return
count = 0
for path in sorted(legacy.iterdir()):
if not path.is_file() or path.suffix.lower() != ".nwa":
print("Kept unknown legacy entry:", path)
continue
newer = destination_for(path.name, output)
if not newer.is_file() or newer.stat().st_size != path.stat().st_size:
print("Kept unmatched legacy file:", path.name)
continue
def sha256(p: Path) -> str:
with p.open("rb") as f:
return hashlib.file_digest(f, "sha256").hexdigest()
if sha256(path) != sha256(newer):
print("Kept changed legacy file:", path.name)
continue
path.unlink()
count += 1
if not any(legacy.iterdir()):
legacy.rmdir()
print(f"Tidied {count} byte-identical old .nwa export(s) from build/windows-nwa/.")
# Watch *inputs* only. Ignore intermediate compiler output, Rust target/, npm
# install directories, exported files, and emulator screenshots. Otherwise a
# rebuild could detect its own outputs and create an infinite rebuild loop.
WATCH_IGNORED_DIRS = frozenset({
".git", ".venv", "venv", "__pycache__", "build", "dist", "target",
"node_modules", "output", ".idea", ".pytest_cache", ".mypy_cache",
".ruff_cache", ".tox", ".next", ".cache", ".vs", "windows-nwa",
})
WATCH_EXTS = frozenset({
".c", ".h", ".s", ".rs", ".py", ".json", ".toml", ".lock",
".mk", ".ld", ".txt", ".png", ".ppm", ".jpg", ".jpeg",
".svg", ".webp", ".gif", ".bin", ".ttf", ".otf", ".sh",
".js", ".ts", ".yml", ".yaml", ".ini", ".csv",
})
WATCH_NAMES = frozenset({"Makefile", "makefile", "GNUmakefile", "VERSION"})
def is_source_file(name: str) -> bool:
if name.startswith(("~", ".#")) or name.endswith(("~", ".swp", ".tmp")):
return False
if name in WATCH_NAMES:
return True
if name.startswith("."):
return False
# .nwi/.nppm are generated by Rust's build.rs; avoid output-trigger loops.
if name.lower().endswith((".nwi", ".nppm")):
return False
return Path(name).suffix.lower() in WATCH_EXTS
def source_snapshot(root: Path = ROOT) -> dict[str, tuple[int, int]]:
result: dict[str, tuple[int, int]] = {}
# Exclude the build helper while it is running; edits to it require restart.
own = Path(__file__).resolve()
for folder, directories, files in os.walk(root):
directories[:] = [d for d in directories
if d not in WATCH_IGNORED_DIRS and
(not d.startswith(".") or d == ".cargo")]
for name in files:
if not is_source_file(name):
continue
p = Path(folder) / name
if p == own:
continue
try:
st = p.stat()
except OSError:
continue
result[p.relative_to(root).as_posix()] = (st.st_mtime_ns, st.st_size)
return result
def differences(a: dict, b: dict) -> list[str]:
return sorted(k for k in (a.keys() | b.keys()) if a.get(k) != b.get(k))
def run_watch(build_once, *, interval: float = 1.0,
settle: float = 1.0, root: Path = ROOT, game: str | None = None) -> None:
"""Debounce editor save bursts; rebuild and publish only on success.
No extra watchdog package needed. Capture the baseline after a build so
files generated inside source folders don't retrigger it immediately.
"""
if interval <= 0 or settle <= 0:
raise ValueError("watch interval and settle time must be positive")
print("\nWatching NumPlay source files. Save an edit to rebuild; Ctrl+C to stop.")
print("Build failures keep the previous build/compiled/NumPlay.nwa untouched.\n")
def snapshot():
files = source_snapshot(root)
if game is None:
return files
prefixes = (f"games/{game}/", "games/common/", "tools/")
shared = {"Makefile", "VERSION", "games/games.json"}
return {name: st for name, st in files.items()
if name in shared or name.startswith(prefixes)}
baseline = snapshot()
pending: dict[str, tuple[int, int]] | None = None
last_change = 0.0
while True:
time.sleep(interval)
current = snapshot()
now = time.monotonic()
if current == baseline:
pending = None
continue
if pending != current:
pending = current
last_change = now
continue
if now - last_change < settle:
continue
changed = differences(baseline, current)
print("\nDetected edits ({} file(s)):".format(len(changed)), flush=True)
for name in changed[:12]:
print(" " + name)
if len(changed) > 12:
print(f" ... plus {len(changed) - 12} more")
try:
build_once()
except (OSError, RuntimeError, subprocess.CalledProcessError, ValueError) as exc:
print("\nBuild failed; keeping last good build/compiled/ app:", exc,
file=sys.stderr, flush=True)
# Rescan after build. Generated files, if any, become the new baseline.
# A human edit made during the build may need a further save to trigger.
baseline = snapshot()
pending = None
print("\nWatching for the next edit...", flush=True)
# ---- Universal build entry point: native Windows, macOS and Linux ----
def _nwlink() -> str:
found = shutil.which("nwlink")
if found:
return found
local = Path.home() / ".numplay" / "node_modules" / ".bin" / "nwlink"
if local.exists():
return str(local)
return "npx --yes -- [email protected]"
def _run_make(args: list[str], *, jobs: int) -> None:
print("Building:", " ".join(["make", f"-j{jobs}", *args]), flush=True)
if os.name == "nt":
make, make_name = find_make()
bash, arm = git_bash(), find_arm()
if not (make and make_name and bash and arm and make_supported(make)):
raise RuntimeError("Windows toolchain missing; run python tools/build.py --doctor")
run_bash(bash, make, make_name, arm, jobs, apps=False, check=False, langs=False,
target_args=args)
else:
ensure_build_directories()
cmd = ["make", f"-j{jobs}", *args, "NWLINK=" + _nwlink()]
subprocess.run(cmd, check=True, cwd=ROOT)
def _game_output(game: str) -> tuple[str, Path]:
import json
import re
manifest = json.loads((ROOT / "games" / "games.json").read_text(encoding="utf-8"))
labels = {g["id"]: g["app"] for g in manifest if g.get("app")}
for match in re.finditer(r"(?m)^APP_(\w+)\s*=\s*([^:\n]+):(\S+\.nwa)\s*$",
(ROOT / "Makefile").read_text(encoding="utf-8")):
labels[match.group(1)] = match.group(3)
if game not in labels:
raise ValueError(f"Unknown standalone game '{game}'. Choices: " + ", ".join(sorted(labels)))
game_dir = ROOT / "games" / game
if not game_dir.is_dir():
raise ValueError(f"Missing game directory: {game}")
file = labels[game]
# Conventional Makefiles can put all standalone intermediates in build/data.
# Special layouts still use their original output paths until migrated.
makefile = (game_dir / "Makefile").read_text(encoding="utf-8") if (game_dir / "Makefile").exists() else ""
active = "\n".join(line for line in makefile.splitlines()
if not line.lstrip().startswith("#"))
conventional = ("output/" not in active) and any(
re.search(rf"(?m)^{variable}\s*=\s*output\s*$", makefile)
for variable in ("BUILD_DIR", "OUT"))
candidate = ([ROOT / "build" / "data" / "games" / game / f"{game}.nwa"]
if conventional else [game_dir / "output" / f"{game}.nwa",
game_dir / "output" / "device" / f"{game}.nwa",
game_dir / "build" / f"{game}.nwa"])
if game == "tetris":
candidate = [ROOT / "build" / "data" / "apps" / "Tetris.nwa"]
return file, next((p for p in candidate if p.is_file()), candidate[0])
def _publish_game(game: str) -> Path:
name, src = _game_output(game)
if not src.is_file():
raise RuntimeError(f"No successful game build found at {src}")
dst = OUTPUT / "games" / name
atomic_copy(src, dst)
print("Stable live-emulator input:", dst.relative_to(ROOT), flush=True)
return dst
def _build_once(a) -> None:
if a.game:
if a.game == "tetris":
# Dedicated Cargo target: do not compile all NumPlay games.
# The Make recipe uses the existing Windows nwlink.exe bridge.
_run_make(["tetris-app"], jobs=a.jobs)
_publish_game("tetris")
return
_game_output(a.game) # Fail before launching a compiler on invalid IDs.
source_makefile = (ROOT / "games" / a.game / "Makefile").read_text(encoding="utf-8")
active = "\n".join(x for x in source_makefile.splitlines()
if not x.lstrip().startswith("#"))
variable = next((v for v in ("BUILD_DIR", "OUT")
if re.search(rf"(?m)^{v}\s*=\s*output\s*$", source_makefile)), None)
make_args = ["-C", f"games/{a.game}", "build"]
if variable and "output/" not in active:
make_args.append(f"{variable}=../../build/data/games/{a.game}")
_run_make(make_args, jobs=a.jobs)
_publish_game(a.game)
return
if os.name == "nt":
if not doctor():
raise RuntimeError("Windows requirements are not yet ready")
make, make_name = find_make()
bash, arm = git_bash(), find_arm()
assert make and make_name and bash and arm
run_bash(bash, make, make_name, arm, a.jobs,
apps=not a.launcher_only, check=not a.skip_check and not a.launcher_only,
langs=not a.skip_languages)
else:
targets = ["nwa"]
if not a.launcher_only:
targets += ["apps"]
if not a.skip_check and not a.launcher_only:
targets += ["check"]
_run_make(targets, jobs=a.jobs)
if not a.skip_languages:
_run_make(["lang"], jobs=a.jobs)
sources = collect_sources(apps=not a.launcher_only, langs=not a.skip_languages)
publish_outputs(apps=not a.launcher_only, langs=not a.skip_languages)
if (ROOT / "build" / "compiled" / "NumPlay.nwa").is_file():
print("Stable live-emulator input: build/compiled/NumPlay.nwa", flush=True)
def main() -> int:
ap = argparse.ArgumentParser(description="NumPlay unified build + live watch (Windows, macOS, Linux)")
ap.add_argument("--doctor", action="store_true")
ap.add_argument("--install-arm", action="store_true", help="Windows: install verified ARM compiler")
ap.add_argument("--install-make", action="store_true", help="Windows: install portable GNU Make")
ap.add_argument("--make-zip", type=Path)
ap.add_argument("--game", metavar="ID", help="compile one standalone game")
ap.add_argument("--launcher-only", action="store_true")
ap.add_argument("--skip-check", action="store_true")
ap.add_argument("--skip-languages", action="store_true")
ap.add_argument("--organize-only", action="store_true", help="publish existing successful .nwa files")
ap.add_argument("--watch", action="store_true", help="rebuild when source files change")
ap.add_argument("--once", action="store_true", help="alias for a normal one-time build")
ap.add_argument("--clean", action="store_true", help="make clean; removes generated build files")
ap.add_argument("--watch-interval", type=float, default=1.0)
ap.add_argument("-j", "--jobs", type=int, default=2)
a = ap.parse_args()
if a.jobs < 1 or a.jobs > 32 or a.watch_interval <= 0:
ap.error("jobs must be 1..32 and watch interval must be positive")
if os.name == "nt":
# Older PowerShell windows may not inherit ~/.cargo/bin in their PATH.
ensure_rust_on_path()
if a.doctor:
if os.name == "nt":
return 0 if doctor() else 1
return subprocess.call([sys.executable, str(ROOT / "tools" / "setup.py"), "--check"])
if a.install_arm or a.install_make:
if os.name != "nt":
ap.error("Windows installers are Windows-only; use tools/setup.py")
if a.install_arm:
install_arm()
if a.install_make:
install_make(a.make_zip)
return 0
if a.clean:
# Do not call `make clean`: several game recipes erase local build/
# folders also used by host tests (including host-saves).
for location in (ROOT / "build" / "data", OUTPUT):
if location.is_symlink():
raise RuntimeError(f"Refusing to clean symlink: {location}")
if location.is_dir():
shutil.rmtree(location)
print("Removed disposable build directory:", location.relative_to(ROOT))
print("Kept game-local folders and ~/.numplay-emulator/ (saves and settings).")
return 0
if a.organize_only:
publish_outputs(apps=True, langs=True)
return 0
if a.game and a.launcher_only:
ap.error("--game and --launcher-only are mutually exclusive")
try:
_build_once(a)
except (OSError, RuntimeError, subprocess.CalledProcessError, ValueError) as exc:
print("Build failed; the last good .nwa stays untouched:", exc, file=sys.stderr, flush=True)
if not a.watch:
return 1
if a.watch and not a.once:
try:
run_watch(lambda: _build_once(a), interval=a.watch_interval, game=a.game)
except KeyboardInterrupt:
return 0
return 0
if __name__ == "__main__":
sys.exit(main())