Install CraftOS-PC

CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft. See ADR-0005 for why.

CraftOS-PC is the emulator; craftos is the command-line executable it installs. For the broader upstream documentation index, see craftos_pc_glossary.md.

Minimum version: v2.8.3. just install runs craftos --version to verify it is on $PATH and recent enough; it also checks that jq, luacheck, and openssl are installed.

The upstream installation page is https://www.craftos-pc.cc/docs/installation. The notes below pin the version we test against and add a SHA-256 verification step.

macOS

There is no Homebrew cask, so the install is a manual drag-to-Applications from the official GitHub release.

# 1. Download the dmg and the published hashes.
curl -L -o ~/Downloads/CraftOS-PC.dmg \
  https://github.com/MCJack123/craftos2/releases/download/v2.8.3/CraftOS-PC.dmg

# 2. Verify the SHA-256.
curl -sL https://github.com/MCJack123/craftos2/releases/download/v2.8.3/sha256-hashes.txt \
  | grep CraftOS-PC.dmg
shasum -a 256 ~/Downloads/CraftOS-PC.dmg
# The two hashes must match.

# 3. Mount, install, unmount.
hdiutil attach ~/Downloads/CraftOS-PC.dmg -nobrowse
rm -rf /Applications/CraftOS-PC.app
cp -R "/Volumes/CraftOS-PC/CraftOS-PC.app" /Applications/
hdiutil detach "/Volumes/CraftOS-PC"

# 4. Clear Gatekeeper quarantine so the first launch is not blocked.
xattr -dr com.apple.quarantine /Applications/CraftOS-PC.app

The binary is not on $PATH by default. Add a symlink so just check-craftos can find it:

ln -sf /Applications/CraftOS-PC.app/Contents/MacOS/craftos /usr/local/bin/craftos

User data (computer state, settings) lives in ~/Library/Application Support/CraftOS-PC and survives a reinstall. The steps above only touch the .app bundle.

When running headless tests on macOS, prefer passing the app bundle's resource directory explicitly if craftos is reached through the /usr/local/bin/craftos symlink:

craftos --headless --rom /Applications/CraftOS-PC.app/Contents/Resources --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'

Windows

Download CraftOS-PC-Setup.exe from the latest release and run it. The installer puts craftos.exe on %PATH%.

User data: %appdata%\CraftOS-PC.

Linux

Download CraftOS-PC.x86_64.AppImage from the latest release, make it executable, and symlink it into $PATH:

chmod +x ~/Downloads/CraftOS-PC.x86_64.AppImage
sudo ln -sf "$HOME/Downloads/CraftOS-PC.x86_64.AppImage" /usr/local/bin/craftos

User data: ~/.local/share/craftos-pc.

Verify

craftos --version

Must report CraftOS-PC v2.8.3 or newer. Once this works, just install will succeed.

To verify that CraftOS-PC can boot a computer, not only print its executable version, run:

craftos --headless --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'

On macOS, use the --rom form shown above if the command fails with Could not mount ROM.

Running tests

just test runs /programs/runtest.lua headlessly through CraftOS-PC. The runner discovers tests under /tests, while the Justfile only owns host launch flags, timeout, and success-marker checks. On macOS the recipe passes --rom /Applications/CraftOS-PC.app/Contents/Resources because the /usr/local/bin/craftos symlink loses ROM auto-discovery; on Linux and Windows no flag is needed. just ci runs the same tests after luacheck.

Repository-local launches

just trapos launches CraftOS-PC with the TrapOS dev environment: persistent save data rooted at .craftos instead of the platform default user-data directory, and read-only mounts of the repository at /trapos plus each shipped top-level directory at its ComputerCraft root path (such as /apis, /programs, /servers, /startup, and /tests). Generated files live under .craftos/config/ and .craftos/computer/, while the root .gitignore keeps that state untracked.

just craftos launches a vanilla CraftOS-PC with no mounts, persistent under .craftos-vanilla/ (also gitignored). Use it when a probe should not see TrapOS files — for example, to confirm a behavior is upstream rather than TrapOS-specific.

just trapos-install exercises the real ccpm bootstrap (install-ccpm.lua → ccpm update → ccpm install trapos) end-to-end on a fresh, ephemeral CraftOS-PC state. Network-dependent and slower than just test, so not part of just ci. Override the watchdog with TRAP_CCLIBS_INSTALL_TIMEOUT_SECONDS (default 60).

For automated probes, use the safe wrappers. They mount the right environment, shut down the machine after completion or Lua errors, and kill the host process if the snippet blocks before shutdown:

just trapos-exec 'print("__TRAPOS_TEST_OK__")'
just craftos-exec 'print(_HOST)'

Override the watchdog with TRAP_CCLIBS_HEADLESS_TIMEOUT_SECONDS (default 10). Pass CraftOS-PC flags directly after just trapos or just craftos only for manual launches where you want raw emulator control.

See ADR-0005 for the canonical headless probe pattern used to verify hypotheses about CC:Tweaked behavior.

just repl delegates to just trapos --cli for human interactive use only. LLM agents must not run just repl.

See Command-Line Flags for --headless, --exec, --script, --rom, and --mount-*. See Error Messages for Could not mount ROM and other boot-time failures.

Updating

Repeat the steps above against the newer release. The bundle replacement is in-place; the user data directory is preserved.

5.8 KiB Raw Blame History