webi-installers

webi 是开发者安装工具的方式

• 无需 sudo
• 无需包管理器
• 无需修改系统权限
• 简而言之：没有麻烦

curl https://webi.sh/webi | sh

这个仓库包含 webinstall.dev 的主要和社区提交的软件包。

webi 的工作原理

• 联系官方发布 API 获取下载 URL
• 选择适当的软件包版本和归档格式
• 安装到 $HOME/.local/opt 或 $HOME/.local/bin（视情况而定）
• 通过 $HOME/.config/envman/PATH.env 更新 PATH
• 符号链接或复制当前选定的版本

更技术性的说明：

1. <package>/releases.js 将软件包的发布 API 转换为通用格式
   • （即将 HTML、CSV、TAB 或 JSON 转换为特定的 JSON 格式）
   • 常见的发布 API 在 _common/ 中（如 _common/github.js）
2. _webi/bootstrap.sh 是一个模板，用于交换系统信息以获取正确的安装程序
   • 构建包含操作系统、CPU 和实用工具信息的用户代理（如 macos、amd64、可解压 tar,zip,xz）
3. _webi/template.sh 是基础安装程序模板，具有常见函数用于
   • 检查版本
   • 下载和解压
   • 更新 PATH
   • （重新）链接目录
4. <package>/install.sh 可能提供函数来覆盖 _webi/template.sh
5. 总结：
   • curl https://webi.sh/<pkg> => bootstrap-<pkg>.sh
   • sh bootstrap-<pkg>.sh => https://webinstall.dev/api/installers/<pkg>@<ver>.sh?formats=zip,tar
   • sh install-<pkg>.sh => 下载、解压、移动、链接、更新 PATH

理念（针对使用 webi 发布的软件包作者/维护者）

• 应安装到 $HOME/.local/opt/<package>-<version> 或 $HOME/.local/bin
• 不应需要 sudo（除非可能是一次性的 setcap 等）
• 示例：
  • 完整软件包：
    • Node.js: https://github.com/webinstall/packages/tree/master/node
    • Golang: https://github.com/webinstall/packages/tree/master/golang
    • PostgreSQL: https://github.com/webinstall/packages/tree/master/postgres
  • 单二进制安装程序：
    • Caddy: https://github.com/webinstall/packages/tree/master/caddy
    • Ripgrep: https://github.com/webinstall/packages/tree/master/ripgrep
    • Gitea: https://github.com/webinstall/packages/tree/master/gitea
  • 便捷脚本：
    • Prettier: https://github.com/webinstall/packages/tree/master/prettier
    • Rust-lang: https://github.com/webinstall/packages/tree/master/rustlang
    • vim-sensible: https://github.com/webinstall/packages/tree/master/vim-sensible

创建安装程序

安装程序由 4 个文件中的 5 个部分组成：

my-new-package/
  - README.md （软件包信息在前置元数据中）
  - releases.js
  - install.sh （POSIX Shell）
  - install.ps1 （PowerShell）

1. 创建描述
2. 获取发布版本
3. 版本检查（半可选）
4. 更新 PATH

请参考这些示例：

• https://github.com/webinstall/packages/blob/master/rg/
• https://github.com/webinstall/packages/blob/master/golang/

webinstall.dev 服务器使用 <your-package>/releases.js 返回的发布列表生成一个 shell 脚本，其中预定义了大多数必要的变量和函数。

你只需填写空白处即可。

简要说明

只需创建一个空目录并运行测试，直到获得满意的结果。

git clone git@github.com:webinstall/webi-installers.git
pushd ./webi-installers/
git submodule update --init
npm clean-install

mkdir -p ./new-package/
node _webi/test.js ./new-package/

1. 创建描述

只需从任何现有软件包复制格式。格式如下：

README.md:

---
title: Node.js
homepage: https://nodejs.org
tagline: |
  JavaScript V8 运行时
description: |
  Node.js® 是基于 Chrome V8 JavaScript 引擎构建的 JavaScript 运行时
---

```sh
node -e 'console.log("Hello, World!")'
> Hello, World!
```

1. 获取发布版本

在这一步中，你只需将一种形式的 JSON、CSV、TAB 或其他格式转换为 webi 能理解的格式。

• 使用 Github 发布？请参考 ripgrep/releases.js（使用 _common/github.js）
• 有特殊格式？请参考 golang/releases.js 或 node/releases.js。

它看起来像这样：

releases.js:

module.exports = function (request) {
  return github(request, owner, repo).then(function (all) {
    // 如果你需要做一些特殊处理，可以在这里进行
    // ...
    return all;
  });
};

2. Bash 安装程序

1. 你可以设置的变量
2. 你必须定义的函数
3. 便捷/辅助函数

（可选，如果需要）你可能定义的 Bash 变量：

# 如果软件包名称与命令名称不同，请定义此项（如 golang => go）
pkg_cmd_name="foobar"

# 这些用于符号链接、PATH 和测试命令
pkg_dst="$HOME/.local/opt/foobar"
pkg_dst_cmd="$HOME/.local/opt/foobar/bin/foobar"
#pkg_dst_bin="$(dirname "$pkg_dst_cmd")"

# 这些是上述位置的实际位置
pkg_src="$HOME/.local/opt/foobar-v$WEBI_VERSION"
pkg_src_cmd="$HOME/.local/opt/foobar-v$WEBI_VERSION/bin/foobar"
#pkg_src_bin="$(dirname "$pkg_src_cmd")"

（必需）一个去除所有非版本垃圾的版本检查函数

pkg_get_current_version() {
    # foobar-v1.1.7 => 1.1.7
    echo "$(foobar --version | head -n 1 | sed 's:foobar-v::')"
}

对于其余函数，你可以从示例中复制/粘贴：

pkg_format_cmd_version() {}         # 覆盖，美化打印版本
pkg_link                            # 覆盖，替换webi_link()函数

pkg_pre_install() {                 # 覆盖，运行任何webi_*命令
    webi_check                          # 用于$HOME/.local/opt工具
    webi_download                       # 用于有releases.js的项目
    webi_extract                        # 用于.xz、.tar.*和.zip文件
}

pkg_install() {}                    # 覆盖，通常只需将提取的文件夹重命名为
                                    # "$HOME/.local/opt/$pkg_cmd_name-v$WEBI_VERSION"

pkg_post_install() {                # 覆盖
    webi_path_add "$pkg_dst_bin"        # 应该更新PATH
}

pkg_done_message() {}               # 覆盖，美化打印成功消息

## 脚本API

参见`webi/template.sh`

以下变量将由服务器设置：

```sh
WEBI_PKG=example@v1
WEBI_TAG=v1
WEBI_HOST=https://webinstall.dev
WEBI_RELEASES=https://webinstall.dev/api/releases/example@v1?os=macos&arch=amd64&pretty=true
WEBI_CSV=v1.0.2,
WEBI_VERSION=1.0.2
WEBI_MAJOR=1
WEBI_MINOR=0
WEBI_PATCH=2
WEBI_LTS=
WEBI_CHANNEL=stable
WEBI_EXT=tar
WEBI_PKG_URL=https://cdn.example.com/example-macos-amd64.tar.gz
WEBI_PKG_FILE=example-macos-amd64.tar.gz

PKG_NAME=example
PKG_OSES=macos,linux,windows
PKG_ARCHES=amd64,arm64,x86
PKG_FORMATS=zip,xz

WEBI_TMP=${WEBI_TMP:-"$(mktemp -d -t webinstall-foobar.XXXXXXXX)"}
WEBI_SINGLE=""

webi_check              # 检查所选版本是否已安装（如果是，则重新链接）
webi_download           # 将所选版本下载到$HOME/Downloads/webi/<package-name>.tar.gz
webi_extract            # 将下载的文件解压到/tmp/<package-name>-<random>/
webi_path_add /new/path # 将/new/path添加到bash、zsh和fish的PATH中
webi_pre_install        # 运行webi_check、webi_download和webi_extract
webi_install            # 将解压的文件从$WEBI_TMP移动到$pkg_src
webi_link               # 用当前选择的版本替换任何现有的符号链接
webi_post_install       # 运行`webi_path_add $pkg_dst_bin`

路线图

• 封装发布API以统一和公开
• 支持更多Windows包
• 支持任意git URL（例如@github.com/node/node）
  • （可能对GitHub专门使用ghi node/node）
• 支持git作为归档格式