Building a package manager might seem straightforward until you confront the intricate edge cases of dependency resolution, path management, and user experience. XerWoho’s journey creating zeP—both a Zig package manager and version manager—offers a masterclass in why such tooling demands meticulous planning and relentless iteration. Currently in pre-release, zeP’s development highlights universal challenges faced by infrastructure tools.

The Planning Paradox

The project’s earliest lesson? Code second, think first. XerWoho admits that premature implementation led to avoidable rewrites. One seemingly minor oversight—naming the executable zeP with a capital ‘P’—proved problematic for Linux users accustomed to lowercase commands. This forced a late-stage rename, underscoring how foundational design choices ripple through user workflows.

Taming the PATH Beast

Initial Zig version management inadvertently bloated users’ PATH variables. Each installed version appended a new path (e.g., ~/zig-0.15.1/x86-windows/), causing conflicts where newer versions overshadowed older ones:

# Problematic PATH accumulation
~/zig-0.15.1/x86-windows/:~/zig-0.13.0/x86-windows:...

The solution? Centralized symlinks. zeP now maintains a single ~/.local/bin/zig symlink, dynamically updated to point to the active Zig version. This eliminated path pollution and version collisions—a cleaner approach inspired by pnpm’s efficient use of symlinks for package deduplication.

Symlinks and the Dangling Dilemma

Adopting pnpm’s symlink strategy introduced another challenge: uninstalling a package could break dependent projects by leaving dangling symlinks. zeP’s answer was a manifest.json tracking package-to-project relationships. Uninstalls now:
1. Check the manifest for active dependents
2. Only delete the package if zero projects rely on it
3. Otherwise, simply unlink the requesting project

This reference-counting mechanism prevents orphaned symlinks without sacrificing space efficiency.

Listening to the Users

Community feedback proved invaluable. An early zeP feature redrew the entire terminal screen for progress bars—a “hijacking” behavior users disliked. The revamped output system now selectively clears only zeP’s own lines, preserving other terminal content. As XerWoho notes:

Building a package manager requires not just personal testing, but actively incorporating community feedback. It transforms theoretical design into practical resilience.

The Takeaway

zeP’s evolution underscores that effective package management isn’t just about resolving dependencies—it’s about resolving human frustrations. From capitalization quirks to path hygiene and unobtrusive UI, every detail matters. For tooling developers, the lesson is clear: anticipate edge cases early, but build alongside your users. zeP remains pre-release, but its journey already offers a blueprint for balancing ambition with pragmatism in infrastructure development.

Source: GitHub - XerWoho/zeP and Hacker News Discussion