Superfile Build Process and Binary Distribution Method: Complete Guide

Superfile compiles as a single Go binary using platform-specific CGO settings, with release builds automated via shell scripts and distributed through GitHub Releases, Homebrew, Scoop, and Winget.

The yorukot/superfile repository maintains a robust pipeline for building and distributing its terminal file manager across multiple operating systems and architectures. Understanding the build process and binary distribution method for superfile helps developers contribute effectively and ensures users install the correct binary for their platform.

How Superfile Builds Work

Superfile uses a three-tier build system that accommodates local development, continuous integration, and production releases. Each tier handles CGO configuration differently based on platform requirements.

Local Development Builds

For everyday development, the build.sh script at the repository root handles compilation via the make build target. The script detects the host operating system and configures CGO accordingly:

• macOS (darwin): Sets CGO_ENABLED=1 because the zoxide dependency requires CGO linking on Apple platforms
• Linux and Windows: Sets CGO_ENABLED=0 for static compilation

The output lands in ./bin/spf (or ./bin/spf.exe on Windows). Developers can invoke this directly with ./dev.sh --skip-tests or manually run the build script.

Continuous Integration Builds

The repository validates every commit using GitHub Actions defined in .github/workflows/superfile-build-test.yml. This workflow executes go build -v ./... on Ubuntu, macOS, and Windows runners simultaneously. CI builds ensure cross-platform compatibility before code merges, catching platform-specific compilation errors early in the development cycle.

Release Builds for Multiple Architectures

Production releases rely on release/release.sh, which orchestrates multi-architecture compilation. The script iterates through target operating systems (darwin, linux, windows) and architectures (amd64, arm64), executing builds with explicit environment variables:

# Example from release.sh logic

GOOS=darwin GOARCH=arm64 CGO_ENABLED=1 go build ...
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build ...

Unix-like builds (Darwin and Linux) package as .tar.gz archives, while Windows builds use .zip format. All archives land in the dist/ directory with filenames following the pattern superfile-<os>-<version>-<arch>.<ext>.

Binary Distribution Channels

Superfile distributes pre-compiled binaries through four primary channels, all sourcing artifacts from the same release pipeline.

GitHub Releases

Every tagged version publishes release assets directly to the repository's GitHub Releases page. Users download the appropriate superfile-<os>-<version>-<arch>.tar.gz or .zip file, extract the spf executable, and place it in their $PATH. This serves as the upstream source for all other distribution methods.

Homebrew for macOS and Linux

The Homebrew formula pulls the latest macOS or Linux binary from GitHub Releases and installs it to the Homebrew prefix (typically /usr/local/bin). This method handles architecture detection automatically, selecting arm64 binaries for Apple Silicon and amd64 for Intel systems.

Scoop and Winget for Windows

Windows users enjoy two native package manager options:

• Scoop: Uses install.ps1 to download the Windows .zip asset, extract spf.exe, and add it to the system PATH
• Winget: The .github/workflows/winget.yml workflow automatically publishes the Windows ZIP to the Windows Package Manager Community Repository, enabling installation via winget install yorukot.superfile

Building Superfile From Source

You can produce identical binaries to the official releases using the repository's build scripts.

Build for Current Platform

# Clone repository

git clone https://github.com/yorukot/superfile.git
cd superfile

# Build binary (handles CGO settings automatically)

./build.sh

# Move to PATH (Unix)

sudo mv ./bin/spf /usr/local/bin

Build All Release Artifacts

# Generates dist/ with tar.gz and zip files for all platforms

# Note: Requires macOS host for Darwin builds due to CGO requirements

./release/release.sh

Install via Package Managers

# Homebrew (macOS/Linux)

brew install superfile

# Scoop (Windows)

scoop install superfile

# Winget (Windows)

winget install --id yorukot.superfile

Summary

• superfile compiles as a single static binary using Go, with CGO enabled only for macOS builds to support the zoxide dependency.
• The build.sh script handles local development compilation, while release/release.sh automates multi-architecture production builds for darwin, linux, and windows across amd64 and arm64.
• Unix binaries distribute as .tar.gz archives, while Windows uses .zip files, all generated in the dist/ directory.
• GitHub Releases hosts the primary artifacts, with secondary distribution through Homebrew (macOS/Linux), Scoop (Windows), and Winget (Windows).

Frequently Asked Questions

Does superfile require CGO to build?

CGO is required only when building for macOS (darwin), where the zoxide dependency needs CGO-linked system libraries. All other platforms (linux, windows) build with CGO_ENABLED=0 for static binaries. The build.sh and release.sh scripts handle this configuration automatically.

How do I install superfile on Windows?

Windows users have three options: download the .zip directly from GitHub Releases and extract spf.exe to your PATH, install via scoop install superfile, or use winget install yorukot.superfile. The Scoop and Winget methods automatically manage updates and PATH configuration.

What architectures are supported by superfile releases?

Official releases provide binaries for amd64 (x86_64) and arm64 (Apple Silicon/ARM64) across all three supported operating systems. The release script in release/release.sh builds six total combinations: darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, windows/amd64, and windows/arm64.

Can I build superfile without using the release scripts?

Yes. You can build directly using go build from the repository root, which produces a binary for your current platform. For example: go build -o spf ./.... However, using build.sh ensures correct CGO settings, and release/release.sh is required to generate the official cross-platform archives with proper naming conventions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}