README.md

   1 # webinstall/packages
   2
   3 > WebInstall is how developers install their tools
   4
   5 This repository contains the primary and community-submitted packages for
   6 [webinstall.dev](https://webinstall.dev).
   7
   8 # Installer Guidelines
   9
  10 - Should install to `$HOME/.local/opt/<package>-<version>` or `$HOME/.local/bin`
  11 - Should not need `sudo` (except perhaps for a one-time `setcap`, etc)
  12 - Examples:
  13     - Full Packages:
  14         - Node.js: <https://github.com/webinstall/packages/tree/master/node>
  15         - Golang: <https://github.com/webinstall/packages/tree/master/golang>
  16         - PostgreSQL: <https://github.com/webinstall/packages/tree/master/postgres>
  17     - Single-Binary Installers:
  18         - Caddy: <https://github.com/webinstall/packages/tree/master/caddy>
  19         - Ripgrep: <https://github.com/webinstall/packages/tree/master/ripgrep>
  20         - Gitea: <https://github.com/webinstall/packages/tree/master/gitea>
  21     - Convenience Scripts:
  22         - Prettier: <https://github.com/webinstall/packages/tree/master/prettier>
  23         - Rust-lang: <https://github.com/webinstall/packages/tree/master/rustlang>
  24         - Rust-lang: <https://github.com/webinstall/packages/tree/master/vim-sensible>
  25
  26 # How it works
  27
  28 - Contacts official release APIs for download URLs
  29 - Selects the appropriate package version and archive format
  30 - Installs to `$HOME/.local/`
  31 - Updates `PATH` via `$HOME/.config/envman/PATH.env`
  32 - Symlinks or copies current selected version
  33
  34 More technically:
  35
  36 1. `<package>/releases.js` transforms the package's release API into a common formatt
  37     - (i.e. HTML, CSV, TAB, or JSON into a specific JSON format)
  38     - common release APIs are in `_common/` (i.e. `_common/github.js`)
  39 2. `_webi/bootstrap.sh` is a template that exchanges system information for a correct installer
  40     - contructs a user agent with os, cpu, and utility info (i.e. `macos`, `amd64`, can unpack `tar,zip,xz`)
  41 3. `_webi/template.sh` is the base installer template with common functions for
  42     - checking versions
  43     - downloading & unpacking
  44     - updating PATH
  45     - (re-)linking directories
  46 4. `<package>/install.sh` may provide functions to override `_webi/template.sh`
  47 5. Recap:
  48     - `curl https://webinstall.dev/<pkg>` => `bootstrap-<pkg>.sh`
  49     - `bash bootstrap-<pkg>.sh` => `https://webinstall.dev/api/installers/<pkg>@<ver>.sh?formats=zip,tar`
  50     - `bash install-<pkg>.sh` => download, unpack, move, link, update PATH
  51
  52 ## Creating an Installer
  53
  54 An install consists of 5 parts in 4 files:
  55
  56 ```
  57 my-new-package/
  58   - package.yash
  59   - releases.js
  60   - install.sh
  61   - install.bat
  62 ```
  63
  64 1. Create Description
  65 2. Fetch Releases
  66 3. Version Check (semi-optional)
  67 4. Update PATH
  68
  69 See these **examples**:
  70
  71 - https://github.com/webinstall/packages/blob/master/rg/
  72 - https://github.com/webinstall/packages/blob/master/golang/
  73
  74 The `webinstall.dev` server uses the list of releases returned by
  75 `<your-package>/releases.js` to generate a bash script with most necessary
  76 variables and functions pre-defined.
  77
  78 You just fill in the blanks.
  79
  80 ### TL;DR
  81
  82 Just create an empty directory and run the tests until you get a good result.
  83
  84 ```bash
  85 git clone git@github.com:webinstall/packages.git
  86 pushd packages
  87 ```
  88
  89 ```bash
  90 mkdir -p new-package
  91 npm install
  92 node _webi/test.js ./new-package/
  93 ```
  94
  95 ### 1. Create Description
  96
  97 Just copy the format from any of the existing packages. It's like this:
  98
  99 `package.yash`:
 100
 101 ````
 102 # title: Node.js
 103 # homepage: https://nodejs.org
 104 # tagline: JavaScript V8 runtime
 105 # description: |
 106 #   Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine
 107 # examples: |
 108 #   ```bash
 109 #   node -e 'console.log("Hello, World!")'
 110 #   > Hello, World!
 111 #   ```
 112
 113 END
 114 ````
 115
 116 This is a dumb format. We know. Historical accident (originally these were in
 117 bash comments).
 118
 119 It's in the TODOs to replace this with either YAML or Markdown.
 120
 121 ### 1. Fetch Releases
 122
 123 All you're doing in this step is just translating from one form of JSON or CSV
 124 or TAB or whatever, to a format understood by `webi`.
 125
 126 - Using Github releases? See `ripgrep/releases.js` (which uses
 127   `_common/github.js`)
 128 - Have a special format? See `golang/releases.js` or `node/releases.js`.
 129
 130 It looks like this:
 131
 132 `releases.js`:
 133
 134 ```js
 135 module.exports = function (request) {
 136   return github(request, owner, repo).then(function (all) {
 137     // if you need to do something special, you can do it here
 138     // ...
 139     return all;
 140   });
 141 };
 142 ```
 143
 144 ### 2. Bash Installer
 145
 146 1. Variables _you_ can set
 147 2. Functions _you_ must define
 148 3. Convenience / Helper Functions
 149
 150 (optional, if needed) Bash variables that you _may_ define:
 151
 152 ```bash
 153 # Define this if the package name is different from the command name (i.e. golang => go)
 154 pkg_cmd_name="foobar"
 155
 156 # These are used for symlinks, PATH, and test commands
 157 pkg_dst="$HOME/.local/opt/foobar"
 158 pkg_dst_bin="$HOME/.local/opt/foobar/bin"
 159 pkg_dst_cmd="$HOME/.local/opt/foobar/bin/foobar"
 160
 161 # These are the _real_ locations for the above
 162 pkg_src="$HOME/.local/opt/foobar-v$WEBI_VERSION"
 163 pkg_src_bin="$HOME/.local/opt/foobar-v$WEBI_VERSION/bin"
 164 pkg_src_cmd="$HOME/.local/opt/foobar-v$WEBI_VERSION/bin/foobar"
 165 ```
 166
 167 (required) A version check function that strips all non-version junk
 168
 169 ```bash
 170 pkg_get_current_version() {
 171     # foobar-v1.1.7 => 1.1.7
 172     echo "$(foobar --version | head -n 1 | sed 's:foobar-v::')"
 173 }
 174 ```
 175
 176 For the rest of the functions you can like copy/paste from the examples:
 177
 178 ```bash
 179 pkg_format_cmd_version() {}         # Override, pretty prints version
 180
 181 pkg_link                            # Override, replaces webi_link()
 182
 183 pkg_pre_install() {                 # Override, runs any webi_* commands
 184     webi_check                          # for $HOME/.local/opt tools
 185     webi_download                       # for things that have a releases.js
 186     webi_extract                        # for .xz, .tar.*, and .zip files
 187 }
 188
 189 pkg_install() {}                    # Override, usually just needs to rename extracted folder to
 190                                     # "$HOME/.local/opt/$pkg_cmd_name-v$WEBI_VERSION"
 191
 192 pkg_post_install() {                # Override
 193     webi_path_add "$pkg_dst_bin"        # should probably update PATH
 194 }
 195
 196 pkg_done_message() {}               # Override, pretty print a success message
 197 ```
 198
 199 ## Script API
 200
 201 See `webi/template.sh`
 202
 203 These variables will be set by the server:
 204
 205 ```
 206 WEBI_PKG=example@v1
 207 WEBI_NAME=example
 208 WEBI_TAG=v1
 209 WEBI_HOST=https://webinstall.dev
 210 WEBI_RELEASES=https://webinstall.dev/api/releases/example@v1?os=macos&arch=amd64&pretty=true
 211 WEBI_CSV=v1.0.2,
 212 WEBI_VERSION=1.0.2
 213 WEBI_MAJOR=1
 214 WEBI_MINOR=0
 215 WEBI_PATCH=2
 216 WEBI_LTS=
 217 WEBI_CHANNEL=stable
 218 WEBI_EXT=tar
 219 WEBI_PKG_URL=https://cdn.example.com/example-macos-amd64.tar.gz
 220 WEBI_PKG_FILE=example-macos-amd64.tar.gz
 221 ```
 222
 223 ```bash
 224 WEBI_TMP=${WEBI_TMP:-"$(mktemp -d -t webinstall-foobar.XXXXXXXX)"}
 225 WEBI_SINGLE=""
 226 ```
 227
 228 ```bash
 229 webi_check              # Checks to see if the selected version is already installed (and re-links if so)
 230 webi_download           # Downloads the selected release to $HOME/Downloads/<package-name>.tar.gz
 231 webi_extract            # Extracts the download to /tmp/<package-name>-<random>/
 232 webi_path_add /new/path # Adds /new/path to PATH for bash, zsh, and fish
 233 webi_pre_install        # Runs webi_check, webi_download, and webi_extract
 234 webi_install            # Moves extracted files from $WEBI_TMP to $pkg_src
 235 webi_link               # replaces any existing symlink with the currently selected version
 236 webi_post_install       # Runs `webi_add_path $pkg_dst_bin`
 237 ```
 238
 239 # Roadmap
 240
 241 - Wrap release APIs to unify and expose
 242 - [ ] Support arbitrary git urls (i.e. `@github.com/node/node`)
 243   - (maybe `ghi node/node` for github specifically)
 244 - [ ] Support git as an archive format