Installing applications

gritpack install, app list, app upgrade, app which, uninstall

Chapter 14 of 34Current for Gritpack 1.2.63Source: docs/guide/14-installing-applications.md

Some packages are not libraries you build against but programs you run: a code generator, a formatter, a deployment tool, Gritpack itself. You want to type one command, get the program on your PATH, and later move it to a new version without thinking about where its files live. That is what gritpack install and the gritpack app commands are for. They install for your user only, never ask for an administrator password, and never touch /usr, Homebrew or the system package manager.

What you will be able to do

  • install a command-line application from the public hub or your private hub;
  • see what you have installed, and which application owns a command;
  • check for newer versions and upgrade, one application or all of them;
  • remove an application cleanly;
  • understand which hub an application comes from, and why that choice is safe.

Install one application

The public hub, get.gritpack.org, serves applications to anyone, without an account. Installing one is a single command:

$ gritpack install @frogfish/scroll-throttle
resolving @frogfish/scroll-throttle latest for x86_64-unknown-linux-gnu from the configured registry chain…
downloading and verifying 1 package…
installing and activating commands…
installed @frogfish/scroll-throttle 1.0.0 from https://get.gritpack.org:443 into ~/.frogfish/gritpack commands=scroll-throttle integrity=verified provenance=registry-recorded

Read the last line from left to right. Gritpack installed version 1.0.0, it says which hub the package came from, the files went into your Gritpack home, and the package provides one command, scroll-throttle. integrity=verified means every byte matched the digest the hub recorded when the version was published. provenance=registry-recorded means the hub vouched for who published it and under which name. Neither is a claim that the program is safe to run: Gritpack checks that you got exactly what the publisher published, not what the program does.

The first line names the platform Gritpack looked for, x86_64-unknown-linux-gnu here. An application is published once per platform, and Gritpack picks the one for your machine. If there is none, it says it cannot resolve the package rather than install something that will not run.

To ask for a particular version, add it after the name. A plain version is taken as a requirement, as everywhere in Gritpack:

gritpack install @ada/hello-tool 1.0.0
gritpack install @ada/hello-tool '^1'

Careful. In zsh, a word that starts with = is expanded by the shell. Quote an exact pin: gritpack install @ada/hello-tool '=1.0.0'.

gritpack app install is the same command under the app group. Use whichever you like; this guide uses the shorter gritpack install.

Where the files go, and PATH

Everything lives in your Gritpack home, ~/.frogfish/gritpack unless you moved it with GRITPACK_HOME:

~/.frogfish/gritpack/
  bin/            one entry per command, the only directory you put on PATH
  store/sha256/   each installed version, unpacked into a folder named by its digest
  receipts/       one record per installation: what, which version, from where
  cache/          downloaded package files, shared with projects

On Linux and macOS each command in bin/ is a symbolic link into the store. On Windows it is a small launcher, bin\<command>.exe, beside a one-line bin\<command>.target file naming the program it runs.

The installer described in Installers and download links offers to add ~/.frogfish/gritpack/bin to your PATH. If you installed Gritpack another way, add it yourself once, for example in ~/.zprofile or ~/.bashrc:

export PATH="$HOME/.frogfish/gritpack/bin:$PATH"

Open a new terminal and the commands work by name:

$ hello
hello from hello-tool 1.0.0

Under the hood. A version's folder in store/ is written once and never changed. An upgrade unpacks the new version into a new folder and then switches the commands to it, so a program that is already running keeps its files. Gritpack never runs code from a package while installing it: there are no install scripts.

See what you have

gritpack app list shows every application installed for your user:

$ gritpack app list
@ada/hello-tool 1.0.0 provenance=registry-recorded origin=https://packages.example.com:443 commands=hello
@frogfish/scroll-throttle 1.0.0 provenance=registry-recorded origin=https://get.gritpack.org:443 commands=scroll-throttle

When a command on your PATH surprises you, ask which application owns it:

$ gritpack app which hello
hello -> @ada/hello-tool 1.0.0 (https://packages.example.com:443)

Both commands take --json. app list --json adds the exact digest, the platform, the installation's ID, when it was installed, and store_path, the folder holding that version's files:

$ gritpack app list --json
[
  {
    ...
    "dialect": "application/cli",
    "entrypoints": {
      "hello": "bin/hello"
    },
    "origin": "https://packages.example.com:443",
    "package": "@ada/hello-tool",
    "provenance": "registry_recorded",
    "store_path": "~/.frogfish/gritpack/store/sha256/046afd42631eca55899b9e88d2205d520bb2135c13b5fcb1132f8b8f69d65df7",
    "target": "x86_64-unknown-linux-gnu",
    "version": "1.0.0"
  }
]

A program that wants to find the files of another installed application, such as a launcher looking for a bundle of resources, should read this list instead of searching folders on disk.

Upgrade

When a publisher releases a new version, check first, then upgrade:

$ gritpack app upgrade --check
@ada/hello-tool 1.0.0 -> 1.1.0 available
$ gritpack app upgrade
downloading and verifying 1 package…
installing and activating commands…
@ada/hello-tool 1.0.0 -> 1.1.0 upgraded
$ hello
hello from hello-tool 1.1.0

With no names, app upgrade looks at every installed application. Name one or more to upgrade only those:

gritpack app upgrade @ada/hello-tool

Each application is upgraded on its own. If one fails, the others still upgrade, the report says failed for the one that did not, and the command exits with an error so a script notices. An application that is already at its newest version reports current:

$ gritpack app upgrade
@ada/hello-tool 1.1.0 current
@frogfish/scroll-throttle 1.0.0 current

Gritpack is an application too. If you installed it with the installer, it upgrades itself the same way:

gritpack app upgrade gritpack

gritpack version prints this line under upgrade: as a reminder.

From npm. gritpack app upgrade is the counterpart of npm update -g, and gritpack install of npm install -g. Project dependencies are a different thing in Gritpack: gritpack update and gritpack upgrade act on a project's gritpack.toml, never on installed applications. See Keeping up to date.

Running gritpack install again for an installed application also moves it to the newest version, or to the version you name. That is how you go back to an older version:

$ gritpack install @ada/hello-tool 1.0.0
resolving @ada/hello-tool 1.0.0 for x86_64-unknown-linux-gnu from https://packages.example.com:443 (recorded by the existing installation)…
downloading and verifying 1 package…
installing and activating commands…
installed @ada/hello-tool 1.0.0 from https://packages.example.com:443 into ~/.frogfish/gritpack commands=hello integrity=verified provenance=registry-recorded

Note the words "recorded by the existing installation". The next section is about why that matters.

Which hub an application comes from

With no login, Gritpack knows only the public hub, and every install comes from get.gritpack.org.

Once you log in to a private hub (Logging in), Gritpack asks your hub first and the public hub second. It moves on to the public hub only when your hub answers, with your login, that it has no package of that name at all. So with a private login active, this still installs from the public hub:

$ gritpack install @frogfish/scroll-throttle
resolving @frogfish/scroll-throttle latest for x86_64-unknown-linux-gnu from the configured registry chain…
...
installed @frogfish/scroll-throttle 1.0.0 from https://get.gritpack.org:443 into ~/.frogfish/gritpack commands=scroll-throttle integrity=verified provenance=registry-recorded

and this installs from your hub:

$ gritpack install @ada/hello-tool
resolving @ada/hello-tool latest for x86_64-unknown-linux-gnu from the configured registry chain…
...
installed @ada/hello-tool 1.0.0 from https://packages.example.com:443 into ~/.frogfish/gritpack commands=hello integrity=verified provenance=registry-recorded

Three rules keep this safe:

  1. Only a clear "no such name" falls through. If your hub cannot be reached, rejects your login, or has the name but cannot offer it right now (for example because an administrator quarantined it), the install stops with an error. It never quietly fetches a public package of the same name instead. That is what protects you from someone publishing a look-alike name on the public hub.

  2. Once installed, an application stays with its hub. The receipt records where it came from, and every later install, reinstall and upgrade of it asks only that hub.

  3. --from means exactly one hub. To use one hub and no other for this command, name it:

    gritpack install @frogfish/scroll-throttle --from get.gritpack.org

    --from never falls back. If the package is not on that hub, the command fails:

    $ gritpack install @ada/hello-tool --from get.gritpack.org
    

resolving @ada/hello-tool latest for x86_64-unknown-linux-gnu from get.gritpack.org… cannot resolve @ada/hello-tool: root requires @ada/hello-tool *

For a private hub, --from takes the hub's address, and --from-cert, --from-key and --from-ca take a certificate if no login profile covers it.

If you have logins to several private hubs, app upgrade uses, for each application, the login that serves the hub it came from, so applications from different hubs upgrade in one run. Hubs and sources explains the same rules for project dependencies.

Two applications, one command name

Two applications may not both own the same command. Gritpack refuses before it changes anything:

$ gritpack install @ada/hello-two
resolving @ada/hello-two latest for x86_64-unknown-linux-gnu from the configured registry chain…
downloading and verifying 1 package…
installing and activating commands…
global command "hello" is already owned by @ada/hello-tool

The command exits with code 6, a conflict. Uninstall the other application first if you want to switch. Gritpack also refuses to replace a file in bin/ that it did not put there, so a program you copied in by hand is never overwritten.

Remove an application

$ gritpack uninstall @ada/hello-tool
uninstalled @ada/hello-tool 1.1.0 commands=hello

gritpack app uninstall is the same command. It removes the application's commands from bin/ and its receipt. The version's folder in store/ is left in place, so a copy of the program that is still running keeps working. In 1.2.63 Gritpack does not yet remove unused store folders by itself; they are safe to leave.

For automation

For automation. install, uninstall, app list, app which and app upgrade take --json and --error-format json. Every one of them takes --home <dir> to work on a Gritpack home other than yours, which is handy in tests. app upgrade --check --json tells a script what is out of date without changing anything. See Scripting with JSON.

Making your own application installable

Any package becomes an installable application when its gritpack.toml maps command names to executable files with an [entrypoints] table:

[package]
name = "@ada/hello-tool"
version = "1.0.0"
dialect = "application/cli"
encoding = "executable/native"
target = "x86_64-unknown-linux-gnu"
description = "Prints a friendly greeting"
readme = "README.md"
license = "MIT"
license-files = ["LICENSE"]
files = ["bin/hello", "README.md", "LICENSE"]

[entrypoints]
hello = "bin/hello"

The rules:

  • Each key is a command name: letters, digits, ., _ and -, starting with a letter or digit, at most 64 characters. Names are compared without regard to case.

  • Each value is a path inside the package to a regular file that is marked executable. Gritpack checks this when you pack:

    $ gritpack pack --output ../hello-tool-1.0.0.gpk
    

invalid manifest: entrypoint "hello" target "bin/hello" must be a regular executable package file $ chmod +x bin/hello $ gritpack pack --output ../hello-tool-1.0.0.gpk packed @ada/hello-tool 1.0.0 dialect=application/cli encoding=executable/native target=x86_64-unknown-linux-gnu files=4 entrypoints=hello payload_sha256=9b63f1b1... -> ../hello-tool-1.0.0.gpk

  • Set target to the platform the program runs on, using the names Gritpack reports, such as x86_64-unknown-linux-gnu, aarch64-apple-darwin or x86_64-pc-windows-msvc. Publish one package per platform, all with the same name and version; gritpack install picks the one that matches the machine. A package with no target is not offered by gritpack install.
  • dialect = "application/cli" is a label for people and tools that filter search results. Gritpack attaches no rules to it, and you may use another label that suits your application.
  • Gritpack carries regular files, with or without the executable bit, and symbolic links that stay inside the package. It does not carry file owners, other permission bits, or empty directories.
  • An application may be laid out however it likes, for example a folder with a binary, icons and data files. Gritpack does not look inside; it only activates the commands you list.

Publishing it is the same as publishing any package, and is the subject of Publish your first package.

What just happened

  • gritpack install resolved an application for your platform, checked every byte against the hub's record, unpacked it into a folder that never changes, and linked its commands into ~/.frogfish/gritpack/bin.
  • app list and app which show what is installed and where it came from.
  • app upgrade moves applications forward, each from the hub it came from; install with a version moves one to exactly that version.
  • With a private login, your hub is asked first, and the public hub only when your hub has no such name. --from picks exactly one hub.
  • uninstall removes the commands and the record.

You can stop here

If you only want to install and update command-line tools, you are done.

Next