1 # [webi-installers](https://github.com/webinstall/webi-installers)
3 > [webi](https://webinstall.dev) is how developers install their tools
5 [![webinstall-dev-ogimage-github](https://user-images.githubusercontent.com/122831/129465590-136b5a8a-f8f5-4e8d-a010-784eaa9f21bb.png)](https://webinstall.dev)
9 - no messing with system permissions
10 - in short: no nonsense
13 curl https://webinstall.dev/webi | bash
16 This repository contains the primary and community-submitted packages for
17 [webinstall.dev](https://webinstall.dev).
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
29 1. `<package>/releases.js` transforms the package's release API into a common
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
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
39 - downloading & unpacking
41 - (re-)linking directories
42 4. `<package>/install.sh` may provide functions to override `_webi/template.sh`
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
49 # Philosophy (for package authors / maintainers publishing with webi)
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)
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>
66 <https://github.com/webinstall/packages/tree/master/vim-sensible>
68 ## Creating an Installer
70 An install consists of 5 parts in 4 files:
74 - README.md (package info in frontmatter)
77 - install.ps1 (PowerShell)
82 3. Version Check (semi-optional)
85 See these **examples**:
87 - https://github.com/webinstall/packages/blob/master/rg/
88 - https://github.com/webinstall/packages/blob/master/golang/
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.
94 You just fill in the blanks.
98 Just create an empty directory and run the tests until you get a good result.
101 git clone git@github.com:webinstall/packages.git
107 mkdir -p ./new-package/
108 node _webi/test.js ./new-package/
111 ### 1. Create Description
113 Just copy the format from any of the existing packages. It's like this:
120 homepage: https://nodejs.org
121 tagline: JavaScript V8 runtime
123 Node.jsĀ® is a JavaScript runtime built on Chrome's V8 JavaScript engine
127 node -e 'console.log("Hello, World!")'
132 ### 1. Fetch Releases
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`.
137 - Using Github releases? See `ripgrep/releases.js` (which uses
139 - Have a special format? See `golang/releases.js` or `node/releases.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
155 ### 2. Bash Installer
157 1. Variables _you_ can set
158 2. Functions _you_ must define
159 3. Convenience / Helper Functions
161 (optional, if needed) Bash variables that you _may_ define:
164 # Define this if the package name is different from the command name (i.e. golang => go)
165 pkg_cmd_name="foobar"
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")"
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")"
178 (required) A version check function that strips all non-version junk
181 pkg_get_current_version() {
182 # foobar-v1.1.7 => 1.1.7
183 echo "$(foobar --version | head -n 1 | sed 's:foobar-v::')"
187 For the rest of the functions you can like copy/paste from the examples:
190 pkg_format_cmd_version() {} # Override, pretty prints version
192 pkg_link # Override, replaces webi_link()
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
200 pkg_install() {} # Override, usually just needs to rename extracted folder to
201 # "$HOME/.local/opt/$pkg_cmd_name-v$WEBI_VERSION"
203 pkg_post_install() { # Override
204 webi_path_add "$pkg_dst_bin" # should probably update PATH
207 pkg_done_message() {} # Override, pretty print a success message
212 See `webi/template.sh`
214 These variables will be set by the server:
219 WEBI_HOST=https://webinstall.dev
220 WEBI_RELEASES=https://webinstall.dev/api/releases/example@v1?os=macos&arch=amd64&pretty=true
229 WEBI_PKG_URL=https://cdn.example.com/example-macos-amd64.tar.gz
230 WEBI_PKG_FILE=example-macos-amd64.tar.gz
235 PKG_OSES=macos,linux,windows
236 PKG_ARCHES=amd64,arm64,x86
241 WEBI_TMP=${WEBI_TMP:-"$(mktemp -d -t webinstall-foobar.XXXXXXXX)"}
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`
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
269 set WEBI_HOST=https://webinstall.dev
272 Windows 10 has curl too!?
275 curl.exe -sL -A "MS" https://webinstall.dev/node | powershell
278 And it's easy enough to ignore the execution policy
281 powershell -ExecutionPolicy Bypass install.ps1
284 And if we want something that looks as complicated as we expect Windows to be,
285 historically, we have options:
288 powershell "Invoke-Expression ( Invoke-WebRequest -UseBasicParsing https://webinstall.dev/node ).Contents"
292 powershell ( Invoke-WebRequest -UseBasicParsing https://webinstall.dev/node ).Contents | powershell