92 lines
3.7 KiB
Markdown
92 lines
3.7 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.
|
|
|
|
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("__READY__"); 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("__READY__"); os.shutdown()'
|
|
```
|
|
|
|
On macOS, use the `--rom` form shown above if the command fails with `Could not mount ROM`.
|
|
|
|
## Running tests
|
|
|
|
`just test` runs the headless smoke tests in `tests/` through CraftOS-PC. 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`.
|
|
|
|
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.
|