111 lines
5.5 KiB
Markdown
111 lines
5.5 KiB
Markdown
# Install CraftOS-PC
|
|
|
|
CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft. See [ADR-0005](adrs/adr-0005-craftos-pc-harness.md) 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`](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.
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](https://github.com/MCJack123/craftos2/releases/latest) 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](https://github.com/MCJack123/craftos2/releases/latest), make it executable, and symlink it into `$PATH`:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`).
|
|
|
|
Pass CraftOS-PC flags directly after the recipe name, for example:
|
|
|
|
```sh
|
|
just trapos --headless --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'
|
|
just craftos --headless --exec 'print(_HOST); os.shutdown()'
|
|
```
|
|
|
|
See [`docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md`](adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md) 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](https://www.craftos-pc.cc/docs/cli) for `--headless`, `--exec`, `--script`, `--rom`, and `--mount-*`. See [Error Messages](https://www.craftos-pc.cc/docs/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.
|