Soar 0.13

0.13.0

Soar 0.13.0 reads the declarative package format, stops requiring a package id, and gives packages installed from a URL a way to update themselves.

Breaking Changes

A package id is no longer required. Repositories publishing the declarative format have none, so pkg_id is optional throughout. What tells two identically-named packages apart is the family, the project a package comes from, and the query syntax follows. Where two projects both publish a command called cat:

soar install busybox/cat     # family/name
soar install cat#busybox     # deprecated, still parses and warns

packages.toml gained family, and deprecated two fields. pkg_id still works and warns; install_patterns is only applied by the OCI download path and is ignored by the declarative format.

[packages]
cat = { family = "busybox" }

soar remove '<name>#all' is gone. It selected every variant and then removed only the one you chose, which is what a bare name already does. Use --all to remove every variant:

soar remove --all cat

The metadata database schema changed. This is the database soar keeps locally for each repository, and what a repository has to do about it depends on what it publishes.

• A JSON index: nothing. Soar builds the database from the index, so it is built to the current schema. Fields soar no longer keeps, pkg_webpage, tags, version_upstream and binaries, are ignored rather than rejected, and an index in the original bare-array form is still read.
• A prebuilt SQLite database: nothing immediately. One built by an older soar is brought up to the current schema when it is fetched, so it keeps working until the repository publishes a new one.

Packages install by path. Where a repository says what a package contains, each file lands where it belongs inside the package directory, and soar links manual pages and shell completions onto the system alongside the commands.

Updating Packages Installed From a URL

A package installed from a URL now records where it came from, and can be updated. You can name it by that URL or by the name it installed under:

soar install https://github.com/owner/repo/releases/download/v1.2.3/tool-linux-x86_64.AppImage
soar update tool
soar remove https://github.com/owner/repo/releases/download/v1.2.3/tool-linux-x86_64.AppImage

Soar decides what to update to in two steps. If the artifact carries a feed, an AppImage recording one in its .upd_info section, that is the publisher's own statement of how the package updates and it is followed first. Otherwise, where the URL points at a GitHub or GitLab release, the newest release of that project decides, which is what covers archives and plain binaries.

Delta Updates Over zsync

A publisher offering a zsync feed publishes a control file describing the artifact block by block. Soar uses it to decide whether the artifact differs from the installed copy without downloading it, and then to fetch only the blocks that changed, reusing the rest from the copy on disk. The result is verified against the control file's checksums before it replaces the package.

Manual Pages and Completions

An install now links manual pages beside the bin directory, where man finds them through PATH with no MANPATH set, and shell completions into the directory each shell reads. The completions setting chooses which shells to link for, defaulting to those whose completion directory already exists. Removing a package unlinks only what points back into it, so anything your distribution installed is left alone.

Bug Fixes

• The version of a package installed from a release URL is taken from the release tag rather than guessed from the filename, so an asset named tool_x86_64-unknown-linux-musl.tar.gz no longer installs as tool_x86 at version 64
• A rolling build that keeps one version across every build is updated when its contents change, rather than being treated as already current
• An update check that cannot reach a release now says why, rather than reporting that nothing needs updating
• An empty GITHUB_TOKEN or GITLAB_TOKEN is ignored rather than sent, which previously earned an authentication failure on every request

TIP

GitHub allows 60 API requests an hour unauthenticated, which a handful of packages checked repeatedly will reach. Set GITHUB_TOKEN or GH_TOKEN to raise it. See Forge Rate Limits.