packages

Primary and community-submitted packages for webinstall.dev

Guidelines

• Should install to ./local/opt/<package>-<version>
• Should not need sudo (except perhaps for a one-time setcap, etc)
• Follow the example of https://github.com/webinstall/packages/tree/master/ripgrep, https://github.com/webinstall/packages/tree/master/node, or https://github.com/webinstall/packages/tree/master/golang

Creating an Installer

An install consists of 5 parts in 4 files:

my-new-package/
  - package.yash
  - releases.js
  - install.sh
  - install.bat

1. Create Description
2. Fetch Releases
3. Version Check (semi-optional)
4. Update PATH

See these examples:

• https://github.com/webinstall/packages/blob/master/rg/
• https://github.com/webinstall/packages/blob/master/golang/

The webinstall.dev server uses the list of releases returned by <your-package>/releases.js to generate a bash script with most necessary variables and functions pre-defined.

You just fill in the blanks.

TL;DR

Just create an empty directory and run the tests until you get a good result.

mkdir -p new-package
node _webi/test.js ./new-package/

1. Create Description

Just copy the format from any of the existing packages. It's like this:

package.yash:

# title: Node.js
# homepage: https://nodejs.org
# tagline: JavaScript V8 runtime
# description: |
#   Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine
# examples: |
#   ```bash
#   node -e 'console.log("Hello, World!")'
#   > Hello, World!
#   ```

END

This is a dumb format. We know. Historical accident (originally these were in bash comments).

It's in the TODOs to replace this with either YAML or Markdown.

1. Fetch Releases

All you're doing in this step is just translating from one form of JSON or CSV or TAB or whatever, to a format understood by webi.

• Using Github releases? See ripgrep/releases.js (which uses _common/github.js)
• Have a special format? See golang/releases.js or node/releases.js.

It looks like this:

releases.js:

module.exports = function (request) {
  return github(request, owner, repo).then(function (all) {
    // if you need to do something special, you can do it here
    // ...
    return all;
  });
};

2. Bash Installer

1. Variables you can set
2. Functions you must define
3. Convenience / Helper Functions

(optional, if needed) Bash variables that you may define:

# Define this if the package name is different from the command name (i.e. golang => go)
pkg_cmd_name="foobar"

# These are used for symlinks, PATH, and test commands
pkg_dst="$HOME/.local/opt/foobar"
pkg_dst_bin="$HOME/.local/opt/foobar/bin"
pkg_dst_cmd="$HOME/.local/opt/foobar/bin/foobar"

# These are the _real_ locations for the above
pkg_src="$HOME/.local/opt/foobar-v$WEBI_VERSION"
pkg_src_bin="$HOME/.local/opt/foobar-v$WEBI_VERSION/bin"
pkg_src_cmd="$HOME/.local/opt/foobar-v$WEBI_VERSION/bin/foobar"

(required) A version check function that strips all non-version junk

pkg_get_current_version() {
    # foobar-v1.1.7 => 1.1.7
    echo "$(foobar --version | head -n 1 | sed 's:foobar-v::')"
}

For the rest of the functions you can like copy/paste from the examples:

pkg_format_cmd_version() {}         # Override, pretty prints version

pkg_link                            # Override, replaces webi_link()

pkg_pre_install() {                 # Override, runs any webi_* commands
    webi_check                          # for $HOME/.local/opt tools
    webi_download                       # for things that have a releases.js
    webi_extract                        # for .xz, .tar.*, and .zip files
}

pkg_install() {}                    # Override, usually just needs to rename extracted folder to
                                    # "$HOME/.local/opt/$pkg_cmd_name-v$WEBI_VERSION"

pkg_post_install() {                # Override
    webi_path_add "$pkg_dst_bin"        # should probably update PATH
}

pkg_done_message() {}               # Override, pretty print a success message

Script API

See webi/template.bash

These variables will be set by the server:

WEBI_PKG=example@v1
WEBI_NAME=example
WEBI_TAG=v1
WEBI_HOST=https://webinstall.dev
WEBI_RELEASES=https://webinstall.dev/api/releases/example@v1?os=macos&arch=amd64&pretty=true
WEBI_CSV=v1.0.2,
WEBI_VERSION=1.0.2
WEBI_MAJOR=1
WEBI_MINOR=0
WEBI_PATCH=2
WEBI_LTS=
WEBI_CHANNEL=stable
WEBI_EXT=tar
WEBI_PKG_URL=https://cdn.example.com/example-macos-amd64.tar.gz
WEBI_PKG_FILE=example-macos-amd64.tar.gz

WEBI_TMP=${WEBI_TMP:-"$(mktemp -d -t webinstall-foobar.XXXXXXXX)"}
WEBI_SINGLE=""

webi_check              # Checks to see if the selected version is already installed (and re-links if so)
webi_download           # Downloads the selected release to $HOME/Downloads/<package-name>.tar.gz
webi_extract            # Extracts the download to /tmp/<package-name>-<random>/
webi_path_add /new/path # Adds /new/path to PATH for bash, zsh, and fish
webi_pre_install        # Runs webi_check, webi_download, and webi_extract
webi_install            # Moves extracted files from $WEBI_TMP to $pkg_src
webi_link               # replaces any existing symlink with the currently selected version
webi_post_install       # Runs `webi_add_path $pkg_dst_bin`

Roadmap

• Wrap release APIs to unify and expose
  • Golang https://golang.org/dl/?mode=json
  • Node https://nodejs.org/dist/index.tab
  • Flutter https://storage.googleapis.com/flutter_infra/releases/releases_linux.json - Started at https://github.com/webinstall/packages/blob/master/flutter/versions.js
  • git
    • Note: do all platforms expose tar/zip releases with the same URLs?
  • npm
  • github (see ripgrep)
  • gitea (see serviceman)
• Support git urls (i.e. @github.com/node/node)
  • (maybe ghi node/node for github specifically)