Skip to content

Latest commit

 

History

History
326 lines (250 loc) · 13 KB

install.md

File metadata and controls

326 lines (250 loc) · 13 KB

Install

Install a published Semaprax release, then run a first project. You do not need to clone the repository, install Rust, or compile anything for this route, and you do not need a model account, API key, or editor extension.

One-command installation

macOS and GNU/Linux (no administrator rights):

curl -fsSL https://github.com/wavect/semaprax/releases/latest/download/install.sh | sh

Windows PowerShell 5.1 or 7 (no administrator rights):

irm https://github.com/wavect/semaprax/releases/latest/download/install.ps1 | iex

Open a new terminal afterward. To inspect before running, download the script, read it, and run sh install.sh --version v0.9.0 or .\install.ps1 -Version v0.9.0. These install the compiler and daemon together. They check archive hashes and, when GitHub CLI is installed, the publisher attestation. Add --require-publisher-verification or -RequirePublisherVerification to require that check. A checksum alone does not authenticate the publisher.

For a different location use --prefix "$HOME/tools/semaprax" or -InstallDir "$env:LOCALAPPDATA\Programs\Semaprax". Use --no-modify-path or -NoModifyPath to leave shell startup files/user PATH unchanged. The scripts print the command needed to use the installation in the current terminal. Rerun with an exact version to upgrade or select an older release. Remove a script-managed installation with sh install.sh --uninstall or .\install.ps1 -Uninstall, using the same custom location if you chose one. Projects and credentials are retained. See the installer reference.

WinGet registration is pending moderator review; use PowerShell or the manual ZIP route until the public index serves it.

Pick your download

The current published release is listed at github.com/wavect/semaprax/releases/latest. That address always moves to the newest release, so use it only to find out which version is current. The commands below name one exact tag, v0.9.0, so every download in a session comes from the same release.

Your computer Archive to download Runtime requirement
macOS on Apple Silicon (M1 or newer) semaprax-v0.9.0-aarch64-apple-darwin.tar.gz macOS 11.0 or newer (the binary's recorded minimum).
Linux on x86-64 semaprax-v0.9.0-x86_64-unknown-linux-gnu.tar.gz GNU/Linux with glibc 2.35 or newer. The distribution is built and tested on glibc 2.35; musl systems such as Alpine are unsupported.
Windows on x86-64 semaprax-v0.9.0-x86_64-pc-windows-msvc.zip 64-bit Windows.

| macOS on Intel | semaprax-v0.9.0-x86_64-apple-darwin.tar.gz | The archive records its macOS deployment minimum. | | Linux on ARM64 | semaprax-v0.9.0-aarch64-unknown-linux-gnu.tar.gz | GNU/Linux with glibc 2.35 or newer. |

All five native downloads passed the v0.9.0 release installation gate. Alpine/musl and native Windows ARM64 are unsupported; use Install from source there.

GitHub also shows Source code (zip) and Source code (tar.gz) under every release. Those are automatically generated snapshots of the repository, not Semaprax programs you can run. Download the archive named in the table.

Each archive unpacks to a directory named after itself. It contains semaprax (the full build of the command-line tool), semapraxd (the daemon), LICENSE, README.md, a per-archive release-manifest.json, and a smoke/ program. On Windows the two programs are semaprax.exe and semapraxd.exe.

Homebrew (Apple Silicon and Intel macOS)

Homebrew installs the matching native v0.9.0 archive on Apple Silicon or Intel macOS; it does not compile Semaprax.

brew install wavect/tap/semaprax
semaprax --version

Upgrade and remove with Homebrew:

brew update
brew upgrade wavect/tap/semaprax
brew uninstall semaprax

Homebrew owns semaprax and semapraxd in its bin directory (/opt/homebrew/bin on Apple Silicon, /usr/local/bin on Intel). If you also installed by hand or with the installer, the first semaprax on your PATH wins; check which with command -v semaprax and type -a semaprax. Homebrew never overwrites another manager's files, so remove or reorder the other entry rather than expecting it to be replaced.

To install without Homebrew, use the archive steps below.

macOS and Linux

The steps below use the Apple Silicon archive. For Linux, replace the target with x86_64-unknown-linux-gnu and shasum -a 256 -c - with sha256sum -c -.

  1. Download the one archive for your computer and the checksum list. Do not download the other platforms' archives.

    TAG=v0.9.0
    TARGET=aarch64-apple-darwin
    BASE=https://github.com/wavect/semaprax/releases/download/$TAG
    curl -fLO "$BASE/semaprax-$TAG-$TARGET.tar.gz"
    curl -fLO "$BASE/SHA256SUMS"
  2. Verify the archive you downloaded. SHA256SUMS lists every platform, so select only your archive's line; checking the whole file would report the archives you did not download as missing.

    grep " semaprax-$TAG-$TARGET.tar.gz$" SHA256SUMS | shasum -a 256 -c -

    It must print semaprax-v0.9.0-aarch64-apple-darwin.tar.gz: OK. If it prints FAILED or nothing at all, delete the download and start again; do not unpack it.

  3. Optional: verify who built it. A checksum only shows that the file matches the list published beside it. If you have the GitHub CLI, this also checks the publisher's attestation:

    curl -fLO "$BASE/release-attestation-$TARGET.json"
    gh attestation verify "semaprax-$TAG-$TARGET.tar.gz" \
      --bundle "release-attestation-$TARGET.json" --repo wavect/semaprax
  4. Unpack it somewhere permanent. This example uses ~/.local/opt.

    mkdir -p "$HOME/.local/opt"
    tar -xzf "semaprax-$TAG-$TARGET.tar.gz" -C "$HOME/.local/opt"
    ls "$HOME/.local/opt/semaprax-$TAG-$TARGET"

    You should see LICENSE, README.md, release-manifest.json, semaprax, semapraxd, and smoke. If you downloaded the archive in a web browser instead of with curl, macOS may refuse to open the unsigned program; the archives are not notarized, so verify the checksum first and then clear the download flag with xattr -dr com.apple.quarantine "$HOME/.local/opt/semaprax-$TAG-$TARGET".

  5. Put that directory on your PATH. For the current terminal only:

    export PATH="$HOME/.local/opt/semaprax-$TAG-$TARGET:$PATH"

    To keep it for every new terminal, add the same line, with the tag and target written out, to your shell's startup file, then open a new terminal:

    Shell Add this line To this file
    zsh (the macOS default) export PATH="$HOME/.local/opt/semaprax-v0.9.0-aarch64-apple-darwin:$PATH" ~/.zshrc
    bash the same export line ~/.bashrc (and ~/.bash_profile on macOS)
    fish fish_add_path $HOME/.local/opt/semaprax-v0.9.0-aarch64-apple-darwin run once; fish remembers it

    A new version unpacks to a new directory, so update this line when you upgrade.

Windows (PowerShell)

  1. Download the archive and the checksum list, then verify only that archive. SHA256SUMS lists every platform, so select your archive's line.

    $Tag = "v0.9.0"
    $Target = "x86_64-pc-windows-msvc"
    $Name = "semaprax-$Tag-$Target.zip"
    $Base = "https://github.com/wavect/semaprax/releases/download/$Tag"
    Invoke-WebRequest "$Base/$Name" -OutFile $Name
    Invoke-WebRequest "$Base/SHA256SUMS" -OutFile SHA256SUMS
    
    $Line = Get-Content SHA256SUMS | Where-Object { $_ -match "  $([regex]::Escape($Name))$" }
    $Expected = ($Line -split "\s+")[0]
    $Actual = (Get-FileHash $Name -Algorithm SHA256).Hash.ToLower()
    if (-not $Expected -or $Actual -ne $Expected) { throw "Checksum mismatch for $Name - do not unpack it" }
    "$Name : OK"
  2. Optional publisher verification, if the GitHub CLI is installed:

    Invoke-WebRequest "$Base/release-attestation-$Target.json" -OutFile "release-attestation-$Target.json"
    gh attestation verify $Name --bundle "release-attestation-$Target.json" --repo wavect/semaprax
  3. Unpack it somewhere permanent and add it to PATH:

    $Dest = "$env:LOCALAPPDATA\Programs\semaprax-manual"
    Expand-Archive $Name -DestinationPath $Dest
    $Bin = "$Dest\semaprax-$Tag-$Target"
    Get-ChildItem $Bin   # semaprax.exe and semapraxd.exe are here
    
    # This terminal:
    $env:Path = "$Bin;$env:Path"
    # Every new terminal (your user account only):
    $UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
    if (($UserPath -split ";") -notcontains $Bin) {
      [Environment]::SetEnvironmentVariable("Path", "$UserPath;$Bin".TrimStart(";"), "User")
    }

    Windows only reads the saved Path when a terminal starts, so open a new PowerShell window to see it there.

Run your first project

From any directory, with nothing checked out:

semaprax --version
semaprax new first-semaprax
semaprax check first-semaprax/semaprax.toml
semaprax test first-semaprax/semaprax.toml
semaprax run first-semaprax/semaprax.toml

With the v0.9.0 macOS archive these print the version and commit, created calculator project first-semaprax, verified project first-semaprax (sha256:...), project tests passed, and finally 42. new needs a destination that does not exist yet. Continue with your first program or the first project.

semapraxd is the same release's daemon. You do not start it for the steps in this handbook; keep it beside semaprax.

Fix “command not found”

  • Open a new terminal, or run the current-terminal export or $env:Path line from the step above.
  • Check which executable your shell finds: command -v semaprax on macOS and Linux, Get-Command semaprax in PowerShell. If it is not the one you unpacked, an earlier directory on PATH is shadowing it.
  • version 'GLIBC_2.35' not found on Linux means the host's C library is older than the v0.9.0 build requires; use the source route below.

Install from source

Choose this to follow the latest main, to contribute, or when no archive fits your computer. It needs Git and Rust/Cargo 1.88 or newer. Clang is needed only when you build native executables, and Node.js 22 or newer only for the web-package tooling. The checker and interpreter path needs neither Clang nor Node.js, and nothing here needs an API key.

git --version
rustc --version
cargo --version

Clone the repository and run the starter example without installing anything:

git clone --branch main https://github.com/wavect/semaprax.git
cd semaprax
cargo run --locked -p semaprax -- check examples/meaning.spx
cargo run --locked -p semaprax -- run examples/meaning.spx

check reports a verified file and run prints 42. The -- separates Cargo's options from Semaprax's. Cargo downloads dependencies and compiles on the first run.

To get the short semaprax command, install from the checkout. Each command installs different programs:

Command, run in the repository root Installs
cargo install --locked --path . semaprax (the standalone build) and semapraxd.
cargo install --locked --path . --bin semaprax Only the standalone semaprax.
cargo install --locked --path crates/semaprax-toolchain Only semaprax-full, the full build, under that name.
cargo install --locked --git https://github.com/wavect/semaprax --tag v0.9.0 semaprax The v0.9.0 standalone semaprax and semapraxd, without a checkout.

A release archive's semaprax is the full build, the same code as semaprax-full, renamed when packaged. A source-installed semaprax is the standalone build, which has fewer commands; the technical install reference lists the difference. Use semaprax-full from source when a chapter needs a command the standalone build lacks.

Cargo installs into ~/.cargo/bin. If semaprax is not found afterwards, add it for the current terminal:

export PATH="$HOME/.cargo/bin:$PATH"
$env:Path = "$env:USERPROFILE\.cargo\bin;$env:Path"

To reproduce the exact source this edition of the handbook was reviewed against, run the following in a clean clone before installing, and create a branch before you develop:

git switch --detach 508b851a5fda25002ec27453bb559755a6a0d930

Latest main can contain features that no published release has yet. A command absent from semaprax help all may need a newer build or the full toolchain.

Find help for your build

semaprax help run
semaprax help build
semaprax help diagnostic SPX-T208

Use the help of the executable you installed rather than guessing a flag.

Next: Write your first program, or configure VS Code.