Multi-Platform Binaries
Relevant source files
The following files were used as context for generating this wiki page:
Multi-platform binaries in the pubm project represent the pre-built native executables distributed across various operating systems and architectures. The system is designed to handle the build, compression, hashing, and distribution of these artifacts, primarily focusing on environments where Node.js might not be available, such as pure Rust projects.
The core of this system manages the lifecycle of a binary from its local build directory to its final destination as a GitHub Release asset and its inclusion in Homebrew formulae. This ensures that users on macOS (Intel and Apple Silicon) and Linux (various architectures and libc implementations like glibc and musl) can install the software using standard system package managers.
Sources: CLAUDE.md:14, plugins/pubm-plugin/skills/publish-setup/references/homebrew-setup.md:5-7
Architecture and Asset Pipeline
The asset pipeline is responsible for resolving platform-specific binaries from the project structure and preparing them for distribution. This process involves scanning designated directories, capturing platform metadata from path patterns, and performing integrity checks.
Platform Detection and Resolution
The system uses structured ParsedPlatform data to match local files to target environments. It supports path interpolation using placeholders like {platform} or {os}-{arch} to automatically detect the intended target from the filesystem layout.
The pipeline handles OS aliases (e.g., mapping macos to darwin or win to windows) and architecture variations to ensure compatibility with distribution channels like Homebrew.
Sources: packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:133-145, plugins/pubm-plugin/skills/publish-setup/references/homebrew-setup.md:95-105
Distribution Matrix
The system supports a wide array of platforms, specifically targeting common developer environments.
| Platform String | OS | Architecture | Libc/ABI | Extension |
|---|---|---|---|---|
darwin-arm64 | Darwin (macOS) | ARM64 (Apple Silicon) | N/A | .tar.gz |
darwin-x64 | Darwin (macOS) | x64 (Intel) | N/A | .tar.gz |
linux-arm64 | Linux | ARM64 | glibc | .tar.gz |
linux-arm64-musl | Linux | ARM64 | musl | .tar.gz |
linux-x64 | Linux | x64 | glibc | .tar.gz |
linux-x64-musl | Linux | x64 | musl | .tar.gz |
win-x64 | Windows | x64 | N/A | .zip |
Sources: packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:40-47, packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:160-165
Homebrew Integration
A critical component of the multi-platform binary strategy is the automated update of Homebrew formulae. This is handled by the brewTap and brewCore plugins, which bridge the gap between GitHub Release assets and the Homebrew ecosystem.
Formula Update Workflow
After a successful release, the system executes a hook to update the SHA256 checksums and URLs in the Ruby-based formula files.
- Asset Mapping: The plugin receives
ReleaseContextcontaining uploaded assets. It filters these assets to find matches foron_macosandon_linuxblocks in the formula. - Checksum Verification: The system replaces "PLACEHOLDER" values in the formula with real SHA256 hashes generated during the build process.
- Repository Sync: For
brewTap, changes are pushed directly to a custom tap repo. ForbrewCore, the plugin handles forkinghomebrew/homebrew-coreand opening a Pull Request.
Sources: packages/plugins/plugin-brew/src/brew-tap.ts:108-132, packages/plugins/plugin-brew/src/brew-core.ts:114-140, packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:80-90
Binary Preparation Logic
The project defines specific scripts and configurations for building these binaries, often organized by platform-specific subdirectories within the packages/pubm/platforms/ hierarchy.
// Example of asset pipeline configuration for binaries
const assetConfig = [
{
files: [
{
path: "platforms/{platform}/bin/myapp",
compress: "tar.gz",
name: "myapp-{platform}",
},
],
},
];
Sources: CLAUDE.md:14, packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:93-102
Error Handling and Integrity
To maintain release reliability, the multi-platform binary system includes pre-publish validation and automatic rollback capabilities.
Prerequisites and Preflight Checks
Before binary assets are touched or updated, the system verifies:
- Registry Availability: Pinging registries to ensure they are online.
- Credentials: Validating
PUBM_BREW_GITHUB_TOKENorGITHUB_TOKENfor repository access. - Tooling: Checking for the presence of the
gh(GitHub CLI) for PR operations.
Rollback Mechanism
If a binary fails to publish to one registry in a multi-registry setup, the system can perform rollbacks. In the context of binaries and Homebrew, if a PR was opened to homebrew-core but the overall release failed, the plugin registers a rollback function to close the PR automatically.
Sources: packages/core/src/i18n/locales/en.json:15-25, packages/plugins/plugin-brew/src/brew-core.ts:192-205, packages/plugins/plugin-brew/src/brew-tap.ts:168-180
Summary
The Multi-Platform Binaries system provides a robust pipeline for distributing native executables. By integrating platform detection directly into the asset pipeline and automating the maintenance of Homebrew formulae via specialized plugins, pubm ensures that native tools remain synchronized with their source releases across diverse operating environments. This automation is backed by preflight checks and a rollback system that protects the repository and distribution channels from inconsistent release states.