Install Netsuke

Netsuke requires Ninja on PATH. A source build also requires the dated Rust nightly toolchain pinned in rust-toolchain.toml because Netsuke builds with the Polonius borrow checker, which nightly enables by default.

Inside a checkout, rustup automatically selects the pinned toolchain from rust-toolchain.toml; no command-line argument is required.

Netsuke v0.1.0-beta4 is available from crates.io. Where cargo binstall is available, prefer it: it fetches a prebuilt release binary and avoids the toolchain requirement below.

cargo binstall netsuke-build

Building from the registry instead runs outside a repository checkout, so the pinned toolchain is not picked up automatically; select it explicitly:

rustup toolchain install nightly-2026-08-23
cargo +nightly-2026-08-23 install netsuke-build

Pre-built installers are available from the v0.1.0-beta4 GitHub release:

Download the package for the host architecture, then install it with the platform tool. Replace PACKAGE with the downloaded filename:

• Debian or Ubuntu: sudo apt install ./PACKAGE.deb
• Fedora, Rocky Linux, or another RPM-based distribution: sudo dnf install ./PACKAGE.rpm
• macOS: sudo installer -pkg ./PACKAGE.pkg -target /
• Windows: msiexec.exe /i PACKAGE.msi

The Linux packages install the binary under /usr/bin, add the netsuke.1 manual page and declare ninja-build as a dependency. The macOS packages install the binary under /usr/local/bin, along with the manual page and licence. Ninja must be installed separately when using the macOS or Windows installer. The Windows MSI installs to C:\Program Files\netsuke and does not update PATH.

Linux package metadata comes from [package] in Cargo.toml: the first authors entry supplies the maintainer, while homepage, license, and description supply the corresponding package fields.

The MSI installer supports pre-release SemVer versions such as 0.1.0-beta4: the pre-release suffix cannot be represented in an MSI product version, so the installer carries the numeric release triple (0.1.0) while the full version remains in the package and release names. Because successive beta and final releases share that numeric version, installing a later beta or final MSI replaces the existing installation for that version series rather than installing alongside it.

Repositories that call Netsuke's reusable release workflow can select the WixToolset.UI.wixext version with the wix-extension-version input in the caller job's with: block:

with:
  wix-extension-version: '7'

The workflow supplies 7 when the value is omitted or empty. The resolved version is used for Windows WiX packaging. The Python resolver rejects an unexpectedly empty value and values containing carriage returns or line feeds.

SHA-256 checksum files accompany standalone binaries and staged help, completion, and licence files. Installer packages do not have checksum sidecars in v0.1.0-beta4. Windows PowerShell help files are published beside each MSI as sidecar artefacts rather than embedded in the installer.

Each standalone release archive also contains generated shell completion sidecars under completions/<shell>/ for Bash, Elvish, Fish, PowerShell, and Zsh. These files are portable and separate from the executable and installer payloads. To use one, extract the matching archive and copy the file for the chosen shell into that shell's normal completion directory, or load it through the shell's documented completion mechanism. The package installation commands above do not install completion files; completion directory names and activation steps vary by shell and platform.

Install the current source checkout with Cargo. The clone supplies the pinned nightly toolchain, so it is not given here — unlike the registry install above, which runs outside a checkout:

git clone https://github.com/leynos/netsuke.git
cd netsuke
cargo install --path .

That command runs inside the checkout, so it inherits the repository's build standard: the parallel rustc frontend, and on Linux the mold linker. A cargo install --path . therefore needs the same two prerequisites as make build:

• the pinned nightly from rust-toolchain.toml, which rustup provisions automatically because the file is present;
• mold, on Linux only, reachable through PATH or gcc's own search directories. make install-build-tools installs the pinned release; a distribution mold also works for a local install, though the development gates additionally check the version against tools/mold/VERSION. The installer unpacks into $(BUILD_TOOLS_PREFIX)/bin, ~/.local/bin by default, and does not edit any shell profile; the make targets add that directory to PATH for the recipes they run, so a shell the make targets do not drive needs that directory added before installing.

The linker is named explicitly rather than left to gcc's default, so a Linux host without mold fails the link rather than quietly falling back. The platform default linker is used instead on macOS and Windows — where the configuration names no linker — or when .cargo/config.toml has been removed before installing. A registry install — cargo install netsuke-build — builds from packaged source, where neither .cargo/config.toml nor rust-toolchain.toml is present, so no linker flag applies and mold is not needed on any platform. The pinned nightly is still required, and with no rust-toolchain.toml to supply it the command selects it explicitly: see the crates.io commands earlier in this section.

The MSI does not add its installation directory to PATH. Add it to the current user's persistent PATH, update the current PowerShell session, then verify that the command resolves:

$netsukeDirectory = Join-Path $env:ProgramFiles 'netsuke'
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
$userEntries = @($userPath -split ';' | Where-Object { $_ })
if ($userEntries -notcontains $netsukeDirectory) {
    $newUserPath = (($userEntries + $netsukeDirectory) -join ';')
    [Environment]::SetEnvironmentVariable('Path', $newUserPath, 'User')
}
if (($env:Path -split ';') -notcontains $netsukeDirectory) {
    $env:Path = "$env:Path;$netsukeDirectory"
}
netsuke --version

The release publishes PowerShell help separately for each Windows architecture. The following script downloads the matching module script, manifest, Microsoft Assistance Markup Language (MAML) help, and about-help file. It then restores the versioned module layout under the current user's standard PowerShell module directory and imports the module. Set $architecture to match the downloaded MSI:

$architecture = 'amd64' # Use 'arm64' for the Arm64 MSI.
$releaseUri = 'https://api.github.com/repos/leynos/netsuke/releases/tags/v0.1.0-beta4'
$release = Invoke-RestMethod -Uri $releaseUri

$documents = [Environment]::GetFolderPath('MyDocuments')
$editionDirectory = if ($PSVersionTable.PSEdition -eq 'Desktop') {
    'WindowsPowerShell'
} else {
    'PowerShell'
}
$moduleRoot = Join-Path $documents "$editionDirectory\Modules"
$moduleDirectory = Join-Path $moduleRoot 'Netsuke\0.1.0-beta4'
$helpDirectory = Join-Path $moduleDirectory 'en-US'
New-Item -ItemType Directory -Path $helpDirectory -Force | Out-Null

$patterns = @{
    'Netsuke.psm1' = '*Netsuke.psm1'
    'Netsuke.psd1' = '*Netsuke.psd1'
    'Netsuke-help.xml' = '*en-US-Netsuke-help.xml'
    'about_Netsuke.help.txt' = '*en-US-about_Netsuke.help.txt'
}
$localizedFiles = @('Netsuke-help.xml', 'about_Netsuke.help.txt')
foreach ($fileName in $patterns.Keys) {
    $pattern = "*windows-$architecture*$($patterns[$fileName])"
    $asset = $release.assets | Where-Object { $_.name -like $pattern } | Select-Object -First 1
    if ($null -eq $asset) {
        throw "Release asset not found: $pattern"
    }
    $destinationDirectory = if ($localizedFiles -contains $fileName) {
        $helpDirectory
    } else {
        $moduleDirectory
    }
    $destination = Join-Path $destinationDirectory $fileName
    Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $destination -UseBasicParsing
}

Import-Module (Join-Path $moduleDirectory 'Netsuke.psd1') -Force

The versioned directory is discoverable in later PowerShell sessions. After the import, inspect the external help with:

Get-Help Netsuke -Full