with one click
xpkg-creater
// 在 xim-pkgindex 中创建/更新 xpkg 包(V1),遵守 xlings subos 隔离规范,补齐 tests,并在本地与测试集验证通过后再提交 PR。
// 在 xim-pkgindex 中创建/更新 xpkg 包(V1),遵守 xlings subos 隔离规范,补齐 tests,并在本地与测试集验证通过后再提交 PR。
| name | xpkg-creater |
| description | 在 xim-pkgindex 中创建/更新 xpkg 包(V1),遵守 xlings subos 隔离规范,补齐 tests,并在本地与测试集验证通过后再提交 PR。 |
用于在 xim-pkgindex 仓库中新增或维护 xpkg 包文件,确保满足:
spec = "1")install / config)详细安装命令、测试命令清单、相关链接见:
references/xlings-setup-and-links.mdreferences/testing-and-acceptance.md
开发/验证 xpkg 之前,先确保环境可用:
xlings(用于 xim/xlings/xvm 命令)xlings 命令在 shell 中可执行安装方式与快速命令见 references/xlings-setup-and-links.md。
一个 xpkg 文件由两部分组成:
package = { ... } 元数据域installed/build/install/config/uninstall,按需实现)至少保证:
spec = "1"namedescriptiontype(常见:package/script/config/template)xpm(平台、版本、资源映射)常见推荐字段:
archs, status, categories, keywordsauthors/maintainers/licenses/repo/docs/homepagexvm_enable = true(需要 xvm 管理时)windows/linux/macosx/ubuntu/debian/...{"latest" = { ref = "x.y.z" }}{"x.y.z" = { url = "...", sha256 = "..." }}"XLINGS_RES"ubuntu = { ref = "linux" }["0.0.1"] = {}优先使用官方下载 URL 作为默认资源,同时以注释形式保留 XLINGS_RES 备选。
这样保证首次安装直接从官方源下载,后续如需切换到 xlings 镜像只需取消注释即可。
xpm = {
linux = {
["latest"] = { ref = "1.0.0" },
-- 默认:使用官方 URL
["1.0.0"] = {
url = "https://github.com/org/repo/releases/download/v1.0.0/tool_1.0.0_linux_amd64.tar.gz",
sha256 = nil,
},
-- 备选:使用 xlings 镜像资源(取消注释并删除上面的 url 配置即可切换)
-- ["1.0.0"] = "XLINGS_RES",
},
},
参考实现:pkgs/g/github-gh.lua
当某个版本在包索引中写成 "XLINGS_RES" 时,该版本已经进入 xlings 多镜像资源服务链路。发布前必须同时满足:
https://github.com/xlings-res/<pkg> 与 https://gitcode.com/xlings-res/<pkg> 都存在同名 tag/release。latest 仍指向应当作为最新的版本,不要因为补旧版本导致 latest 倒退。如果 GitHub RES 和 GitCode RES 任一侧缺资源、版本不一致、资产不一致,不能把该版本切到 "XLINGS_RES";先补齐镜像资源,再改包索引。
优先使用新版 API:
import("xim.libxpkg.pkginfo")import("xim.libxpkg.xvm")import("xim.libxpkg.system")(可选)import("xim.libxpkg.log")(可选)避免旧 API:
import("xim.base.runtime")import("common")import("platform")一般情况下,新增或维护 xpkg 只能使用三类能力:
package 元数据、xpm 描述和 lifecycle hooks。string/table/io/os.getenv/pcall/error 等)。xim.libxpkg.* API(例如 pkginfo/xvm/system/log/json)。不要默认引入 xmake 私有 runtime/API。除非某个既有包的兼容性约束已经证明必须使用,否则避免:
core.*、detect.*、runtime.*、xim.base.runtimecommon、platformpath.*、os.host()、is_host()、try { ... }、raise(...)测试也应默认锁定这条边界:import 只能来自 xim.libxpkg.*,路径、错误处理、文件 IO 优先用标准 Lua 或 libxpkg 可移植封装。
对 type = "config" 且会写入用户工具配置的包(例如 Claude/LLM 配置):
package 元数据、hooks,以及必要的 xim.libxpkg.* import。core.*、detect.*、xim.base.runtime、runtime.*、is_host()、os.host()、path.*、try { ... }。error(...),不要使用 raise(...)。install() 保持轻量,默认 return true;实际配置写入放在 config()。log.info/log.warn/log.error 说明结果,敏感 token 不要明文打印。log.warn 提示继续复用旧 key 且不改 token;如果没有可复用 key,使用 log.error 后失败。install() 只负责安装动作本身:
pkginfo.install_file() 获取下载/解压后的输入路径pkginfo.install_dir() 作为目标安装目录os.tryrm(pkginfo.install_dir()) 再 os.mv(...)config() 负责将该版本注册到 xvm(subos 隔离路由):
xvm.add("tool")xvm.add("tool", { bindir = ..., alias = ... })bindiros.exec("xvm add ...") / os.exec("xvm remove ...").bashrc / shell profileos.addenv("PATH") 或 os.setenv("PATH")apt install / brew install / pacman -S依赖请通过 xpm.<platform>.deps 声明;命令路由请通过 xvm shim 完成。
pkgs/<首字母>/<name>.lua 新增或修改包。tests/<首字母>/test_<name_with_underscore>.pyxim.libxpkg.*,只使用标准 Lua + xpkg 规范,不使用 path.*/os.host()/try {}/raise() 等 xmake 私有 API。type = "config" 包,额外锁定:install() 轻量,实际写入在 config()。详细步骤与命令见 references/testing-and-acceptance.md。
tests/ 测试文件。package = {
spec = "1",
name = "demo",
description = "demo package",
type = "package",
archs = {"x86_64"},
status = "stable",
categories = {"tools"},
keywords = {"demo"},
xvm_enable = true,
xpm = {
linux = {
["latest"] = { ref = "1.0.0" },
["1.0.0"] = {
url = "https://github.com/org/repo/releases/download/v1.0.0/demo_1.0.0_linux_amd64.tar.gz",
sha256 = nil,
},
-- ["1.0.0"] = "XLINGS_RES",
},
},
}
import("xim.libxpkg.pkginfo")
import("xim.libxpkg.xvm")
function install()
os.tryrm(pkginfo.install_dir())
os.mv("demo", pkginfo.install_dir())
return true
end
function config()
xvm.add("demo")
return true
end
function uninstall()
xvm.remove("demo")
return true
end