Skip to main content

proto v0.20 - New shims and binaries management

· 3 min read
Miles Johnson
Founder, developer

In this release, we're reworking how shims and binaries work.

Shims and Binaries (breaking)

Since proto's inception, we've used shims as a way to execute installed tools. This allowed us to wrap the underlying tool binary to provide additional functionality, such as automatic version detection, runtime hooks, and more. However, this approach has some limitations, such as:

  • Shims are forced onto you and there's no way to use proto without shims.
  • Shims are slower than executing the native binary, upwards of 10x slower. While this equates in milliseconds, it can be noticeable dependending on the tool.
  • For Windows, our shim files are .cmd and not .exe. This causes a lot of weird and unexpected problems when an environment expects a real executable, or uses a hard-coded .exe extension.

To remedy this, we're introducing both a shim and non-shim approach, which has resulted in a pretty big breaking change. Shims are now generated in ~/.proto/shims (instead of ~/.proto/bin), while ~/.proto/bin will now store symlinks to native binaries. To migrate to this new pattern, we're introducing a new proto migrate command (this only needs to be ran once).

$ proto upgrade
$ proto migrate v0.20 --log debug

How it works

When installing proto for the first time, or running the proto migrate command, we prepend PATH with $PROTO_HOME/shims:$PROTO_HOME/bin. This allows shims to be executed first and fallthrough to native binaries if a shim does not exist (for example, .exe on Windows).

Furthermore, if you'd prefer to only use shims, or only use binaries, you can update PATH and remove the unwanted directory path.

And lastly, if shims are causing problems, you can now easily reference the native binaries directly. This was rather complicated before.


Created asScripts that run proto runSymlinks to the native binary
Version executedDetects version at runtimeLast version that was installed + pinned
Supported forAll toolsOnly tools that support native execution (may not work for .js files)
Additional filesCreates extra files (like bunx, node-gyp, etc)Only links the primary binary

Support for minisign checksums

When proto installs a tool, it runs a process known as checksum verification, where we ensure the download hasn't been modified maliciously in anyway. Historically we only supported SHA256 checksums, but now, we also support the new minisign tool, used by popular tools like Zig.

If you're building a plugin for a tool that uses minisign, you can use the new checksum_public_key (WASM) or install.checksum-public-key (TOML) field to provide the public key for use in verification.

When the checksum URL ends in a .minisig extension, proto will automatically use minisign for checksum verification!

checksum-url = ""
checksum-public-key = "untrusted comment: ..."

Other changes

View the official release for a full list of changes.

  • Updated proto use to install tools in parallel.
  • Updated proto plugins and proto tools to load plugins in parallel.
  • Updated proto run to error when the tool attempts to self-upgrade outside of proto.
  • Rust plugin
    • Will now attempt to install rustup if it does not exist on the current machine.
    • Will now respect the RUSTUP_HOME environment variable when locating the .rustup store.
  • Schema plugin
    • Added install.checksum_public_key for defining the public key used to verify checksums.
    • Added metadata.self_upgrade_commands for defining which sub-commands should be blocked for self-upgrades.