Installing Peko

Everything lives under ~/.Peko. One command puts it there:

peko setup

PEKO_ROOT_PATH overrides the location if you want it elsewhere.

What setup does

In order:

1. Installs the compiler SDK: LLVM 18 for your host, the Android build tools, and the bundled JDK.
2. Places the running peko binary at Compiler/bin/peko/peko. Setup never downloads a CLI; it copies the one you ran.
3. Installs the linux and android toolchain payloads, plus the shared GTK and WebKit headers the linux targets reference.
4. Links the Apple SDKs through xcrun, on a macOS host only. Apple's license does not allow redistributing them, so these are links into Xcode rather than downloads, and Apple targets cannot be built anywhere else.
5. Installs the Windows toolchain, if asked. See below.
6. Installs the toolchain descriptors, applied last so the canonical toolchain.toml files win over any copy inside a payload.
7. Installs std and pekoui globally.
8. Writes versions.json, the manifest the toolchain resolver reads.
9. Configures PATH, then certifies the install with peko check --rehash.

Restart your shell afterwards, or source the env file it wrote.

The layout

~/.Peko/
  Compiler/
    bin/peko/peko        the CLI itself
    llvm18/              clang and lld, one directory per host platform
    java/                the bundled JDK, used for Android signing
    bundling/ include/
    toolchains/          android, ios, linux/{arm,x86_64,gtk},
                         macos/{arm64,x86_64}, windows
  registry/src/          unpacked package sources, shared by every project
  global/                the global manifest and lock
  versions.json
  env                    the PATH script sourced from your shell profile

Updating

Re-run peko setup. It compares the release tags recorded in versions.json against the newest stable releases and skips anything unchanged, so a no-op re-run takes seconds instead of downloading gigabytes.

peko setup --check     # report whether an update is available, then exit
peko setup --force     # reinstall every component

Because the comparison is by release tag rather than by content, deleting a toolchain directory by hand will not cause it to be reinstalled while the tag still matches. --force is the way out of that.

Version selection resolves the newest stable release. Prereleases and non-version tags are skipped, so a release candidate is only installed by naming it: peko setup --sdk-version v2.0.3.

Windows

The MSVC runtime and Windows SDK are under Microsoft's license, so they are opt-in and gated:

peko setup --windows --accept-microsoft-license

Passing --windows without accepting the license stops setup rather than skipping Windows, so pass both together. This step also fetches the WebView2 SDK headers, which pekoui needs on Windows.

What setup changes outside the root

On a Unix host it writes <root>/env and appends a source line to .zshrc, .bashrc, and .profile. On Windows it sets PEKO_ROOT_PATH and prepends to the user PATH through PowerShell. It also writes LICENSE and THIRD-PARTY-NOTICES.txt into the root, because an install is a distribution of the linked components.

Through Peko Studio

Studio checks the toolchain on first run and shows a setup screen when it is missing or unhealthy. It runs the same peko setup --json underneath and streams the progress events, including a Windows toolchain checkbox gated on the license.

Verifying

peko check           # is the installation intact
peko check --rehash  # re-certify after changing files under the root
peko toolchain list  # which toolchains are installed and parse

peko check hashes the installation layout. The vendored subtrees (toolchains, llvm18, java, and the binary itself) are excluded, so it verifies the shape of the install rather than the contents of every SDK.