Homebrew

Homebrew Formula

Introduction

The Homebrew Formula for Numan provides a standardized distribution mechanism for macOS and Linux users to install the Numan package manager. Numan is a cross-platform package manager for Nushell that handles plugins, modules, scripts, and completions. The formula automates the retrieval of platform-specific pre-built binaries from GitHub Releases, verifies their integrity via SHA256 checksums, and installs the numan executable into the system's path.

Installation Methods

Users can install Numan via Homebrew through two primary methods: using the official tap or using a direct formula URL.

Tap Installation (Recommended)

The recommended method involves tapping the tonythethompson/numan repository. This allows for easier updates and management through standard Homebrew commands.

brew tap tonythethompson/numan
brew install numan

Direct Formula Installation

For users who do not wish to add a tap, the formula can be installed directly from the raw file in the master branch of the main repository.

brew install --formula https://raw.githubusercontent.com/tonythethompson/numan/master/packaging/homebrew/numan.rb

Formula Architecture and Logic

The Numan class inherits from Formula and defines the metadata, platform-specific resource locations, and installation logic.

Platform Support and Resource Resolution

The formula uses conditional blocks (on_macos, on_linux) and architecture checks (on_arm, on_intel) to select the correct binary artifact from GitHub.

Platform	Architecture	Target Triple
macOS	ARM (Apple Silicon)	aarch64-apple-darwin
macOS	Intel	x86_64-apple-darwin
Linux	Intel	x86_64-unknown-linux-gnu

Installation Process

The install method identifies the directory within the downloaded archive (expected to match the numan-* pattern) and moves the binary to the Homebrew bin directory.

graph TD
    Start[Download Archive] --> Extract[Extract Archive]
    Extract --> FindDir[Find numan-* Directory]
    FindDir --> Validate{Directory Found?}
    Validate -- No --> Error[Exit with odie]
    Validate -- Yes --> InstallBin[Install bin/numan]

Loading

The diagram shows the logic flow within the Ruby install method.

Release and Maintenance Workflow

Maintaining the Homebrew distribution involves updating version strings and checksums whenever a new release is cut.

Synchronization Script

The project includes a shell script, scripts/sync-homebrew-tap.sh, to synchronize the formula from the main repository to the dedicated tap repository.

#!/usr/bin/env bash
# scripts/sync-homebrew-tap.sh (abridged)
FORMULA_SRC="${ROOT}/packaging/homebrew/numan.rb"
TAP_REPO="${TAP_REPO:-${HOME}/src/homebrew-numan}"
cp "${FORMULA_SRC}" "${TAP_REPO}/Formula/numan.rb"

Update Procedure

Maintainers must perform the following steps for each release:

1. Update the version variable in numan.rb.
2. Update the sha256 values for each platform based on the SHA256SUMS file from the GitHub Release.
3. Sync the file to the homebrew-numan tap repository.
4. Commit and push the changes in the tap repository.

Testing the Formula

The formula includes a test block that executes numan --version to ensure the binary is correctly installed and functional.

test do
  assert_match version.to_s, shell_output("#{bin}/numan --version")
end

Summary

The Homebrew Formula is a critical component of Numan's distribution strategy, as outlined in Phase 7.6 of the project roadmap. It provides macOS and Linux users with a familiar interface for managing Numan installations while ensuring platform-specific binary compatibility and security through checksum verification.