README.md

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