README.md

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