wares

wares is a declarative AppImage/binary package manager!

Installation

Downloading wares

To install, just grab the binary for your operating system from the Releases section on the right.

Or, compile wares from Source

Alternatively, you can build wares from *source*.

To do this, you'll need a copy of go installed on your system. I'd recommend using Nix to get a temporary shell with Go installed.

Then, simply clone this repo (https://github.com/indium114/wares), cd into it, and run go build

Setting up wares

Run the following to check that everything is in order:

/path/to/wares doctor

If it tells you that ~/Wares is not in your $PATH, please add it.

Letting wares manage itself

Then, create ~/.config/wares and paste the following into ~/.config/wares/config.yaml:

wares:
  wares:
    name: wares
    repo: indium114/wares
    asset: "wares_Linux_x86_64"

Replace Linux_x86_64 with Darwin_aarch64 if you're on a Mac with Apple Silicon, or Darwin_x86_64 if you're on an Intel Mac.

Then, run /path/to/wares sync to download Wares, and it will now manage itself.

Usage

Installing a package

To install a package, add it to the wares section of config.yaml.

Installing an AppImage or Binary

For example, here's me installing Helix using wares

wares:
  hx:
    name: hx                 # Name of the program
    repo: helix-editor/helix # GitHub repo (without github.com)
    asset: "*.AppImage"      # Pattern which will match the downloaded asset you would like
                               # For example, using "*Linux-x86_64*" will match with any file containing the substring `Linux-x86_64` in its name

Installing an Archive

Installing an Archive (.tar.gz) is the same as installing as installing an AppImage.

In this example, I'll be installing Lazygit, which is packaged in .tar.gz format

wares:
  lazygit:
    name: lazygit                          # Name of the executable file inside .tar.gz archive that you want to use
    repo: jesseduffield/lazygit            # GitHub repo (without github.com)
    asset: "lazygit_*_linux_x86_64.tar.gz" # Pattern which will match the downloaded asset you would like
                                             # For example, using "*Linux-x86_64*" will match with any file containing the substring `Linux-x86_64` in its name

Removing top-level directory

Some .tar.gz-archived packages may include a top-level directory, usually named the same things as the archive itself.

To remedy this, you can set removetoplevel: true under a ware.

In this example, I'll be installing the GitHub CLI, which is packaged like this.

wares:
  gh:
    name: bin/gh
    repo: cli/cli
    asset: "gh_*_linux_amd64.tar.gz"
    removetoplevel: true # This is the important part for this archive.

If you want to know if a particular package does this or not, download and extract the archive for yourself.

Installing a package with Multiple Artifacts

If your package has multiple files that all need to be symlinked, you can use the multiple attribute.

When using multiple, a new directory named after the package will be created, into which the contents of the archive will be symlinked.

Ensure that ~/Wares/<package name> is in your $PATH for this to work.

In this example, I'll be installing Cubyz, which is packaged in .tar.gz format and requires multiple artifacts.

wares:
  Cubyz:                         # Name of the directory that the artifacts will be symlinked into inside ~/Wares
    name: Cubyz                  # Not very useful for multi-artifact, but can't be empty
    repo: pixelguys/cubyz        # GitHub repo (without github.com)
    multiple: true               # Denotes that *all* files in the archive must be symlinked
    asset: "Linux-x86_64.tar.gz" # Pattern which will match the downloaded asset you would like
                                   # For example, using "*Linux-x86_64*" will match with any file containing the substring `Linux-x86_64` in its name

Installing packages from source

wares can build and install packages from source through the blueprint system.

In this example, I'll be installing dotkeeper from source.

blueprints:
  dotkeeper:
    repo: "https://github.com/indium114/dotkeeper" # Full URL to repo
    steps:                                         # Steps to build the project in bullet-point form
      - "go build"
    artifacts:                                     # Path of artifacts relative to the repo's root, in bullet-point form
      - "dotkeeper"

Managing distro packages

wares can manage your distro's package manager as well, allowing you to declaratively install packages from apt, pacman, flatpak, etc.

Configuring managers

To configure a manager, add it to the settings:managers section of config.yaml.

In this example, I'll configure flatpak.

settings:
  managers:
    flatpak:                         # Name of the package manager
      install: "flatpak install -y"  # Command to install a package
      remove: "flatpak uninstall -y" # Command to remove a package
      update: "flatpak update -y"    # Command to update all installed packages

Installing distro packages

Now that your manager is configured, let's install a package!

This is done in the managers:<manager_name> section of config.yaml.

In this example, I'll be installing Resources (net.nokyan.Resources) as a flatpak.

managers:
  flatpak:                   # Name of the package manager (set earlier in settings:managers)
    - "net.nokyan.Resources" # Package to install

Installing packages system-wide

To install a ware or blueprint system-wide, simply add system: true to its definition.

Ensure that wares doctor is run before installing a system-wide ware or blueprint for the first time.

In this example, I'll be installing Cubyz system-wide.

wares:
  Cubyz:
    name: Cubyz
    repo: pixelguys/cubyz
    multiple: true
    asset: "Linux-x86_64.tar.gz"
    system: true # set this to install system-wide

Installing packages from Codeberg or other Forgejo instances

You can install wares from Codeberg or other Forgejo instances that expose the Forgejo API.

You can do this be setting the host: value of the ware definition to the URL to the host, like https://codeberg.org.

In this example, I'll be installing the Forgejo CLI from Codeberg.

wares:
  fj:
    name: fj
    repo: forgejo-contrib/forgejo-cli
    asset: "*x86_64-linux.tar.gz"
    host: https://codeberg.org # this is the important part

Updating packages

To update packages, run the following command:

wares update

This will update the version in pallet.lock. Now just sync to install the new version:

wares sync

wares shells

wares shells allow you to create temporary environments with tools installed that you don't want on your global system, a la Nix Shells.

To start, create waresfile.yaml in the root of your project.

Fill it out as you would with wares' config.yaml file.

Note

managers are not and will not be supported inside wares shells.

In this example, I'll be installing Just in a wares shell.

wares:
  just:
    name: just
    repo: casey/just
    asset: just-*-x86_64-unknown-linux-musl.tar.gz

Run the following command to enter the wares shell:

wares shell

Note

The first time you enter the shell, you'll need to run wares shell --update instead.

Building your project with the _self blueprint

Inside the waresfile.yaml file at the root of your repo, you can specify a _self blueprint.

This blueprint defines how your project will be built, allowing you to build it with wares.

this is similar to the nix build command

For example, this is the _self blueprint for the wares Git repo.

blueprints:
  _self:
    repo: "https://github.com/indium114/wares"
    steps:
      - "nix develop --command go build"
    artifacts:
      - "wares"

Note

The repo: field is ignored, but can't be empty. You should still set it to the URL to your repo, as it may have a use in the future.

Once you have the blueprint written, you can build it with the following:

wares build

You can optionally specify a directory (e.g. wares build /path/to/project)

After buildijng, the artifacts will be symlinked into wares-result at the root of your project.

Remember to add wares-result to your .gitignore file.