$ show pkgxdev/pkgx
pkgx is a standalone CLI package runner (~4 MiB) that can run any open-source tool without modifying the host system. It resolves dependencies, downloads pre-built tarballs from a distribution server (dist.pkgx.dev), installs them to ~/.pkgx, and injects the correct environment (PATH, MANPATH, PKG_CONFIG_PATH, etc.) before executing the requested command. The codebase is a Rust workspace split into a CLI crate (crates/cli) handling argument parsing, querying, and execution, and a library crate (crates/lib) providing core logic: local cellar management, pantry YAML parsing with platform-aware deserialization, SQLite-backed pantry indexing, async installation with atomic extraction and file locking, dependency graph hydration with support for multi-version projects (e.g., OpenSSL 1.1 vs 3), and environment variable construction (including moustache template expansion for runtime env vars). The architecture is monolithic but well-modularized, with clear separation of concerns. It demonstrates high craftsmanship in areas like cross-platform environment handling, progress visualization, and robust concurrent installation. The repository is actively maintained with comprehensive CI/CD pipelines, tests, and code quality checks.
The LLM identified 5 files worth highlighting for reuse:
Implements a custom iterator that walks the pantry directory structure, parsing package YAML metadata. Features serde deserialization with custom platform-aware context: the `Deps` struct merges platform-specific dependency constraints (linux/darwin/windows) and the `Runtime` struct filters environment variables by platform and architecture. The `Provides` deserializer handles both list and platform-keyed map formats. This is a self-contained, reusable module for any tool that needs to parse a hierarchical YAML-based package index with platform-specific overrides.
Topologically hydrates a dependency graph from a list of `PackageReq` inputs using a supplied callback to fetch per-project dependencies. Supports multi-version projects (e.g., unicode.org, openssl.org, abseil.io) by allowing non-intersecting version lines to co-exist as separate `PackageReq` entries. Uses a tree of `Node` structs to track parentage and compute topological depth for sorting. The `condense` function merges compatible constraints and pushes non-intersecting ones into an additional list. This implements a non-trivial dependency resolution pattern that handles real-world ABI incompatibilities, reusable for any versioned dependency system.
Constructs a merged environment map from a list of installed packages. Uses an `OrderedSet` to deduplicate and preserve insertion order of paths for each environment variable (PATH, MANPATH, etc.). Handles cross-platform path separators, system fallback paths (e.g., /usr/share/man), and platform-specific keys (DYLD_FALLBACK_LIBRARY_PATH on macOS). The `mix_runtime` function merges runtime environment declarations from the pantry, supporting moustache template expansion ({{prefix}}, {{version}}, deps.*). Runtime env values can reference parent env with $KEY or be wrapped with default fallback syntax. This module is reusable for any tool that needs to compute a hermetic toolchain environment.
Performs async download of `.tar.xz` packages from the distribution server with progress callbacks. Uses exclusive file locking (via `fs2`) on the package shelf directory to prevent concurrent installations. Downloads into a temporary directory, extracts via `tokio_tar::Archive` and `async_compression::XzDecoder`, then atomically renames to the final versioned path. After installation, creates symlinks for major, minor, and latest version aliases (v*, v1, v1.2) using version range logic (caret for minor, strict for major). Cross-platform: Windows uses symlink_dir for directories, Unix uses std::os::unix::fs::symlink. This is a self-contained, production-grade package installation module.
Provides a configurable CLI spinner/progress bar using the `indicatif` crate. Supports quiet/silent modes, dynamic message updates, and a `ProgressBarExt` trait for abstracting progress feedback used by the multi-install module. Includes helper functions for human-readable byte sizes (pretty_size) and adaptive decimal precision (precision). The progress bar template shows elapsed time, a custom progress character (⚯), percentage, bytes/sec, and formatted size. This module is decoupled and could be extracted as a reusable CLI progress utility.