README.md

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