Installers and download links
How the installer works, download links, and building a download for your application
The people who use your application should not have to learn Gritpack first.
They should click a download, confirm once, and find the program ready, and
afterwards it should stay up to date. Gritpack's installer does exactly that:
it installs one application, and installs Gritpack too when it is missing, so
that gritpack app upgrade keeps both current. This chapter explains what the
installer does, the links the public hub serves for it, and how you build a
download for your own application.
What you will be able to do
- explain to a user what happens when they run an installer;
- give people a one-line install or a download link for an application on the public hub;
- run the installer unattended, without touching
PATH; - build an install script or a Mac download for your application with
gritpack installer build; - understand invitation links that join someone to a private hub.
What the installer does
The installer is one small program per platform, released with every Gritpack version. You never need to build it. Whichever way it reaches the person (a download, a one-line command), it does the same things in the same order:
- Works out which application. From its command line, or from its own file name, or from a small label file beside it.
- Asks once, showing the application's name, version, description and
the hub it comes from.
--yesanswers for unattended use. With no terminal to ask in and no--yes, it stops rather than guess. - Installs Gritpack from
get.gritpack.orgif nogritpackcommand is installed yet, so the application can be kept up to date. - Installs the application, exactly as
gritpack installwould, into the person's Gritpack home, with the same checks and the same receipt. - Offers to put
~/.frogfish/gritpack/binonPATH, once, by adding a line to the login profile of the person's shell (~/.zprofile,~/.bash_profileor~/.profile), or to the user'sPathon Windows.--no-modify-pathdeclines. - Says how to run it.
Here is a real run in a terminal, installing a small public application on a machine with no Gritpack:
$ installer @frogfish/scroll-throttle --yes --no-modify-path
Install scroll-throttle 1.0.0 from get.gritpack.org?
Rate-limits X11 scroll-wheel events; fixes unusably fast scrolling caused by a high-resolution trackpad relayed through RDP to a Linux X11 session
Installing Gritpack 1.2.63, which keeps scroll-throttle up to date … ok
Downloading @frogfish/scroll-throttle 1.0.0 … verified
Installing scroll-throttle … ok
Add ~/.frogfish/gritpack/bin to PATH to run the commands by name
scroll-throttle is ready: run `scroll-throttle`
Without --no-modify-path it would have offered to add that directory to
PATH instead of printing the reminder. Running the installer again later
upgrades the application to its newest version.
The installer's options, from installer --help:
| Option | What it does |
|---|---|
[PACKAGE] | The application to install; read from the label or the installer's own file name when omitted |
--hub <HUB> | The hub to install from; default the label's, else get.gritpack.org |
-y, --yes | Answer yes to every question, for unattended installation |
--home <HOME> | The Gritpack home to install into; default ~/.frogfish/gritpack |
--no-modify-path | Do not add the command directory to PATH |
--ca <CA> | A certificate authority for a hub whose certificate the system does not trust |
--gui | Open the window even from a terminal (builds with the window only) |
--code <CODE> | A download code from an invitation page |
The installer never runs code from the package while installing, and it writes nothing outside the person's Gritpack home and, if they agree, one line in their shell profile.
Careful. The installer installs public applications. It does not log in, so it cannot install from a private hub that needs a login: the person runs
gritpack loginfirst, thengritpack install. Invitation links, at the end of this chapter, are the way to bring someone onto a private hub.
Installing Gritpack itself
Install Gritpack covers this from the user's side. The pieces, for reference:
| Platform | How |
|---|---|
| Mac, Windows, Linux | Download from https://gritpack.org/install/, or directly from https://gritpack.org/download/mac, /download/windows or /download/linux |
| Linux or a Mac terminal | curl -fsSL https://get.gritpack.org/install/gritpack \| sh |
| Windows PowerShell | irm https://get.gritpack.org/install.ps1/gritpack \| iex |
The Mac and Windows downloads are not yet signed with a Developer ID or a Windows code-signing certificate, so the operating system warns the first time; the install page says how to proceed.
One-line installs for any public application
The public hub serves an install script for every application it holds. Put the package name at the end of the address:
curl -fsSL https://get.gritpack.org/install/@frogfish/scroll-throttle | sh
The script is short and worth reading before you pipe it into a shell:
curl -fsSL https://get.gritpack.org/install/gritpack | less
It works out the platform, downloads the installer for that platform from the
hub, checks it against a SHA-256 checksum written into the script itself, and
runs it, naming the package and the hub. If the checksum does not match,
nothing is installed. Arguments after sh -s -- reach the installer:
curl -fsSL https://get.gritpack.org/install/@frogfish/scroll-throttle | sh -s -- --yes
On Windows, the PowerShell form is the same idea:
irm https://get.gritpack.org/install.ps1/@frogfish/scroll-throttle | iex
irm and iex cannot pass arguments, so for --yes use the longer form the
script's own first lines suggest:
& ([scriptblock]::Create((irm https://get.gritpack.org/install.ps1/@frogfish/scroll-throttle))) --yes
The install scripts cover Linux on x86-64, Macs with Apple silicon, and Windows on x86-64. On other platforms the script says there is no installer for that platform yet.
Downloads named for their package
People who do not use a terminal want a file to double-click. The public hub serves the same installer under a name that says what it installs:
https://get.gritpack.org/installer/<platform>/<package>
<platform> is x86_64-unknown-linux-gnu, aarch64-apple-darwin or
x86_64-pc-windows-msvc. The file arrives with a name built from the package,
with _ standing for the / of a scope:
| Package | Linux | Windows | Mac |
|---|---|---|---|
gritpack | gritpack.installer | gritpack.installer.exe | gritpack.installer.app, in a zip |
@frogfish/scroll-throttle | frogfish_scroll-throttle.installer | frogfish_scroll-throttle.installer.exe | frogfish_scroll-throttle.installer.app, in a zip |
The installer reads its own file name to know what to install. Copy marks that
browsers add, such as (1), are ignored. A renamed file installs whatever its
new name says, after showing the package and asking. Because the name carries
no hub, these downloads always install from get.gritpack.org.
That is why the name of an application package cannot contain _: it would be
ambiguous in a download name, so the hub refuses it.
On Windows, a double-clicked installer opens a small window and asks there. A console window shows for a moment first, because the same program also works in a terminal.
Build a download for your application
gritpack installer build turns a published application into a download you
can host yourself. It needs the application to be on a hub that also serves
the installer, which today means the public hub.
For Linux and Mac terminals, it saves the install script:
$ gritpack installer build @frogfish/scroll-throttle --platform linux --from get.gritpack.org
wrote install-scroll-throttle.sh for @frogfish/scroll-throttle
the hub serves the same script: curl -fsSL https://get.gritpack.org/install/@frogfish/scroll-throttle | sh
The script is the one the hub serves, pinned to the newest installer and its checksum, so you can put it on your own website. It does not need rebuilding when you release a new version of your application, because the installer always installs the newest version for the platform. Rebuild it when you want it to use a newer installer.
For Macs, --platform macos builds an application bundle called
Install <Title> that carries the installer and a label naming your package.
On a Mac it is a .dmg; on other systems a .zip:
$ gritpack installer build @frogfish/scroll-throttle --platform macos --title "Scroll Throttle" --from get.gritpack.org
wrote Install Scroll Throttle.zip for @frogfish/scroll-throttle (installer 1.2.63, aarch64-apple-darwin; not notarized)
"Not notarized" is honest: the bundle is not signed with an Apple Developer ID, so macOS warns the first time it is opened.
--title sets the name people see (default: the package's own name), and
--output sets where the file goes (default: install-<name>.sh, or
Install <Title>.dmg or .zip).
For automation.
installer buildtakes the usual hub options, so a release job can build downloads right aftergritpack publish. Use--fromto name the hub explicitly in CI.
If the hub you name does not serve installers, the command fails with a "not found" error (exit code 5) rather than writing an incomplete download.
Invitation links
To bring someone onto a private hub, its administrator sends an invitation
(Administering a hub). Usually that is an email
address and a one-time code that the person passes to gritpack login. An
administrator can instead make the invitation a link:
$ gritpack admin user invite bea@example.com --download --enrollment-hub packages.example.com:7445 --package-hub packages.example.com:443
invitation=01a1e868-b459-7c22-b169-9bf9487961f5 account=01a1e868-b3e8-7870-82c6-fc0f4e3af433 expires_at=1794986938 link=https://get.gritpack.org/i/J11F3QAC2N
What the invited person sees:
- They open the link. The page offers a Mac download, and for Linux and Mac
terminals a one-line command of the form
curl -fsSL https://get.gritpack.org/install/gritpack | sh -s -- --code <code>. - The Mac download is called
Join <Profile> - <code>.app, in a zip. The ten characters at the end of its name are the code; the program reads its own name, as the named installers do. - Opening it asks "Join
<hub>as<email>?". On confirmation it installs Gritpack if needed and logs in to the private hub, saving a login profile. If Gritpack is already installed, it downloads nothing and only logs in.
The code works once, only together with the invited email address, and stops working when the invitation expires or is revoked. An unknown, used, revoked or expired code all look the same from outside: "not found".
Today an invitation logs the person in; installing a private application in
the same step is Planned. After joining, they run
gritpack install <application> themselves, or use gritpack app upgrade to
keep it current.
What just happened
- The installer installs one application, and Gritpack if it is missing, after
one confirmation, with the same checks as
gritpack install. get.gritpack.org/install/<package>andinstall.ps1/<package>serve checksummed one-line installs for any public application.get.gritpack.org/installer/<platform>/<package>serves a double-clickable installer named for its package.gritpack installer buildsaves the install script or builds a Mac bundle you can host yourself.- Invitation links bring a person onto a private hub with one download.
You can stop here
If you ship a public application and want people to get it in one step, you have what you need.
Next
- Publish your first package shows how the application gets onto a hub in the first place.
- Optional: Logging in for what happens when someone joins a private hub.