lip.toml
本頁說明 lip.toml 的每一個欄位,讀完後你能看懂任何套件的套件檔,也能寫出自己的。分步講解參見用 lip 發佈你的模組。
lip 套件是根部帶有套件檔 lip.toml 的歸檔。lip.toml 給出套件的名稱和版本,並針對每個變體、執行端和平臺
描述 lip 要安裝的內容:相依、要放置的檔案、要安裝的模組以及要執行的命令。
規範性定義見協議的 lip.toml(5) 頁。
lip.toml 是格式 4 的 TOML 1.0 檔案,由以 TOML 編寫的 JSON Schema
lip.schema.toml
描述。lip 也可讀取 lip v0.x 套件的 tooth.json(格式 1 到 3),參見早期格式。
歸檔
套件位於一個歸檔中,歸檔是一棵根部帶有 lip.toml 的檔案和目錄樹:
- git 歸檔:git 儲存庫的一個提交,通常是某個版本標籤所指的提交。只有其中的普通檔案和目錄屬於 該歸檔(不含符號連結和子模塊);
- ZIP 歸檔:一個 ZIP 檔案,可通過 HTTPS 下載,也可位於你的磁碟上。一個檔案是否為 ZIP 歸檔只看
內容,與檔案名稱無關。其條目必須是普通檔案或目錄,路徑以
/分隔,不得以/開頭,也不得包含..段或\; - 目錄歸檔:你磁碟上的一個目錄,以其內容作為歸檔。其中檔案和目錄的名字不得包含
\。
有一個套件既沒有歸檔也沒有 lip.toml:遊戲 github.com/LiteLDev/bds。lip 根據伺服器組建的清單自己定義
它的套件檔;參見 lip setup和
伺服器檔案。
示例
一個模組,以附加到每個 GitHub Release 的 ZIP 檔案發佈,支援 Windows x64 上的服務端和客戶端:
format = 4
id = "github.com/example/MyMod"
version = "1.0.0"
[info]
name = "My Mod"
description = "A short description"
tags = ["utility"]
[[variants.""]]
side = "server"
platform = "win-x64"
preserve = ["mods/MyMod/config/"]
[variants."".deps]
"github.com/LiteLDev/LeviLamina" = ">=1.0.0 <2.0.0"
"github.com/example/MyLib" = "^0.3.0"
[[variants."".assets]]
type = "mcmod"
urls = ["https://github.com/example/MyMod/releases/download/v{{version}}/MyMod-server-win-x64.zip"]
[[variants.""]]
side = "client"
platform = "win-x64"
preserve = ["mods/MyMod/config/"]
[variants."".deps]
"github.com/LiteLDev/LeviLamina" = ">=1.0.0 <2.0.0"
"github.com/example/MyLib" = "^0.3.0"
[[variants."".assets]]
type = "mcmod"
urls = ["https://github.com/example/MyMod/releases/download/v{{version}}/MyMod-client-win-x64.zip"]版本和版本範圍都是字串,因此總要加引號。含有 ASCII 字母、數字、_ 和 - 以外字元的鍵也要加引號,例如 deps 中的套件 id 或預設變體 "":[[variants.""]] 為預設變體新增一個條目。
欄位
lip.toml 不得包含日期時間、日期、時間,或浮點數 inf、nan。此處未描述的鍵會被忽略。
頂層
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
format |
int |
是 | 必須為 4。 |
id |
string |
是 | 套件 ID,必須是合法的 Go 模塊路徑,例如 github.com/user/repo。比較時不區分 ASCII 大小寫。 |
version |
string |
是 | 套件的版本,不帶前導 v 的 SemVer 2.0.0 版本。 |
info |
object |
否 | 供人閱讀的資訊。參見 Info。 |
variants |
object |
是 | 把每個變體名映射到其條目。參見變體。 |
對於 git 儲存庫中的套件,id 必須是該儲存庫的路徑:https://github.com/user/repo.git 中的
lip.toml 必須寫 id = "github.com/user/repo"。在版本標籤 v<version> 處,version 必須
等於標籤版本。否則該提交不是套件,lip 不會安裝它。
Info
| 欄位 | 類型 | 說明 |
|---|---|---|
name |
string |
顯示名稱。 |
description |
string |
簡短描述。 |
tags |
string[] |
標籤。參見推薦標籤。 |
logo |
string |
徽標圖片的 URL,必須以 https:// 開頭;其響應(直接或經重定向後)即為該圖片。 |
lip 不使用 info。
推薦標籤
info.tags 幫助人們在模組清單(例如介面的「取得模組」頁面和 LeviMC 模組)中找到你的套件;lip 自己忽略標籤。清單會優先顯示下面這些標籤,配上翻譯後的名稱,並允許使用者按它們篩選。請按這裡的寫法填寫 ID,使用小寫;還可以再加上你喜歡的其他標籤:
[info]
tags = ["management", "economy"]| 標籤 | 名稱 | 適用於 |
|---|---|---|
library |
前置庫 / API | 其他模組相依的庫或 API,例如事件、表單或導出函數。 |
utility |
實用工具 | 玩家日常使用的工具,例如背套件輔助、資訊顯示、物品提示和配方檢視。 |
management |
伺服器管理 | 運營伺服器,例如備份、封禁、白名單、登入、命令和領地。 |
game-mechanics |
遊戲機制 | 改變遊戲玩法,例如原版增強功能和成就。 |
adventure |
內容與冒險 | 可供探索的新內容,例如世界生成、地形和生物群系。 |
visual |
視覺與介面 | 玩家看到的內容,例如 HUD、側邊欄、光影、回放和錄製。 |
economy |
經濟 | 貨幣、商店和交易。 |
teleport |
傳送 | 傳送命令、家園、傳送點和傳送石碑。 |
anticheat |
反作弊 | 檢測和阻止作弊,例如反礦透。 |
optimization |
性能優化 | 提升性能,例如實體和掉落物清除。 |
bugfix |
錯誤修復 | 修復遊戲的錯誤。 |
technology |
技術與紅石 | 紅石、活塞和自動化。 |
protocol |
協議與多版本 | 網路協議,例如讓多個遊戲版本的客戶端加入。 |
不需要用標籤標明執行端或平臺,也不需要標明這個套件是 LeviLamina 模組:條目和 deps 已經說明了這些。
變體
variants 把每個變體名映射到一個非空的條目陣列。變體 "" 是預設變體;其他名稱須符合
^[a-z0-9_]+(/[a-z0-9_]+)?$,例如 lua 或 quickjs。使用者在來源後加上 #<variant> 來選擇變體,例如
lip install github.com/LiteLDev/LegacyScriptEngine#lua;不帶 # 的來源選擇 ""。
每個條目恰好適用於一個執行端和一個平臺。lip 解析套件時,取所選變體中 side 和 platform
與工作區環境完全相同的那個條目。沒有通配符:支援多個平臺的套件要為每個平臺各寫一個條目。
若該變體沒有這樣的條目,則該套件不是該環境下的候選。同一變體中的任意兩個條目不得具有相同的
side 和 platform。
條目
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
side |
string |
是 | "server" 或 "client"。 |
platform |
string |
是 | .NET RID,例如 win-x64。 |
deps |
object |
否 | 參見相依。 |
assets |
array |
否 | 參見資源。 |
preserve |
string[] |
否 | 需保留檔案的 glob:安裝時不覆寫已存在的檔案,解除安裝時也不刪除它。 |
purge |
string[] |
否 | 解除安裝時額外刪除的路徑的 glob。符合到的目錄會連同其下所有內容一起刪除。 |
hooks |
object |
否 | 參見鉤子。 |
相依
deps 把 <包 ID> 或 <包 ID>#<variant> 映射到版本範圍:
[variants."".deps]
"github.com/LiteLDev/LeviLamina" = ">=1.0.0 <2.0.0"
"github.com/LiteLDev/LegacyScriptEngine#lua" = "^0.9.0"對每個相依,lip 從該儲存庫的版本標籤中安裝一個版本在範圍內、且有同一環境條目的版本(及變體)。從 git
引用(例如 @branch:main)安裝的套件,只要版本在範圍內,且該儲存庫有 lip 可為該相依安裝的版本,也能滿足對同一套件
ID 和變體的相依。
版本範圍採用 Semver for .NET 3.0.0 中
SemVersionRange.Parse 在預設選項下的語法和語義,例如 ^1.2.0、~1.2.0、>=1.0.0 <2.0.0、
1.2.* 或 >=1.0.0 || 0.9.0。不帶運算符的完整版本(如 1.2.3)只符合該版本。
資源
assets 列出套件的檔案從哪裡來。每個資源都有一個 type:
| 類型 | 欄位 | 說明 |
|---|---|---|
self |
place(可選) |
lip.toml 自身所在的歸檔,例如標籤處的儲存庫。寫了 urls 也會被忽略。 |
zip |
urls、place(可選) |
通過 HTTPS 下載的 ZIP 歸檔。 |
mcmod |
urls |
通過 HTTPS 下載、包含一個 LeviLamina 模組的 ZIP 歸檔;它沒有 place。參見 模組。 |
urls 是同一檔案的 HTTPS URL 組成的非空陣列,按順序嘗試。一個條目最多有一個 mcmod 資源。資源按
順序寫入;兩個資源或放置規則寫入同一路徑時,以後者為準。
放置規則
place 的每個成員都是一條帶有 src 和 dest 的放置規則,把資源歸檔中的檔案寫入工作區。src 是歸檔中的路徑,dest 是
相對於工作區的路徑。兩者都以 / 分隔,不得以 / 或盤符開頭,也不得包含 //、.. 段或 \。
放置規則的形式由 src 決定:
- glob 形式:
src含有*、?或[。所有與 glob 符合的檔案都寫到dest(""或以/結尾)之下,並保留其相對於src中開頭那些不含通配符的段的路徑。不符合任何檔案的 glob 不寫入任何 內容。 - 目錄形式:
src為""或以/結尾。src之下的所有檔案都寫到dest(""或以/結尾) 之下,保留其相對於src的路徑。src之下必須至少有一個檔案。 - 檔案形式:其他情況。檔案
src寫入dest,dest不得以/結尾。該檔案必須存在。
[[variants."".assets]]
type = "zip"
urls = ["https://example.com/tool-1.0.0-win-x64.zip"]
place = [
{ src = "bin/", dest = "tools/" },
{ src = "README.md", dest = "tools/README.md" },
{ src = "plugins/*.dll", dest = "tools/plugins/" },
]套件根部的 lip.toml 永遠不會被寫入。
有些路徑 lip 拒絕寫入:.lip 及其下的一切、其他已安裝的套件擁有的檔案,以及某一段含有 : 或以 . 或
空格結尾的路徑(參見檔案名稱)。此時安裝失敗。
glob
preserve、purge 以及 glob 形式的放置規則使用 POSIX fnmatch 模式,按段逐一符合:
* 符合除 / 以外的任意字元(包括開頭的 .),? 符合除 / 以外的單個字元,[...] 符合集合中的
單個字元。** 段符合零個或多個段;以 / 結尾的模式符合一個目錄及其下的所有內容。沒有轉義字元。
glob 不得為空、不得以 / 開頭,也不得包含 // 或 \。
preserve 和 purge 符合的是相對於工作區的路徑,對模組也是如此:應寫
mods/MyMod/config/,而不是 config/。purge 永遠不會符合工作區根目錄下的 mods
或 .lip,也不會符合 .lip 之下的任何內容;mods 之下的路徑不會僅因 mods 符合而符合:
mods/ 和 */ 不會刪除 mods 之下的任何內容。
鉤子
| 欄位 | 類型 | 說明 |
|---|---|---|
pre_install |
string[] |
寫入檔案之前執行的命令。 |
post_install |
string[] |
寫入檔案之後執行的命令。 |
pre_uninstall |
string[] |
刪除檔案之前執行的命令。 |
post_uninstall |
string[] |
刪除檔案之後執行的命令。 |
命令在工作區根目錄中以 lip 的環境變數執行:工作區環境的平臺為 Windows 平臺時以
cmd /s /c "<命令>" 執行,使 cmd 按原樣執行該命令,否則以 sh -c <命令> 執行,sh 通過 PATH 查找;
在 Windows 以外的系統上,Windows 平臺的命令通過 Wine 執行(參見
Linux 和 macOS),此時含有 " 的命令無法按原樣到達 cmd。以非零結束代碼結束的命令會使操作失敗。操作失敗時,lip 會復原其檔案改動,但不會復原鉤子命令已經做過的事,因此鉤子命令應當可以
安全地再次執行。
模板
與 lip v0.37.0 的 tooth.json 一樣,lip.toml 中除鍵以外的每個字串都是
Scriban 語言的模板。lip 在讀取檔案之前
先渲染每個模板,因此上文所述的一切,例如版本檢查以及 URL 和 glob 的校驗,都作用於渲染後的值。變數是按原樣書寫的
頂層欄位:{{version}}、{{id}}、{{format}}、{{info.name}}、{{variants}},以及你新增的任何其他頂層鍵。
變數儲存的是欄位的原樣內容,其中的模板不會先被渲染。
version = "1.2.3"
[[variants."".assets]]
type = "mcmod"
urls = ["https://github.com/example/MyMod/releases/download/v{{version}}/MyMod-{{version}}.zip"]模板中可以使用任何 Scriban 表達式,例如 {{version | string.replace "." "_"}}。未定義的變數渲染為空。
無法解析或渲染失敗的模板(例如 {{ if }})會使該歸檔不是套件。要原樣寫出 {{,請寫成 {{ "{{" }}。
lip pkg view 顯示渲染後的套件檔,狀態檔中記錄的也是渲染後的套件檔。
模組
帶有 mcmod 資源的條目是 模組;否則該套件是檔案套件,只放置檔案。
mcmod 資源的歸檔根部必須有該模組的 LeviLamina manifest.json,它是一個 JSON 物件,其 name 須符合
^[A-Za-z0-9][A-Za-z0-9._-]*$。這個 name 就是 模組名稱。lip 把整個歸檔按原路徑寫入
mods/<模组名称>/。
lip 唯讀取 manifest.json 的 name,用來命名模組目錄。它不檢查也不修改其中的任何其他內容:
manifest.json 與其他檔案一樣,按歸檔中的原樣寫入模組目錄。讓其 dependencies 與條目的
deps 保持一致由你自己負責。缺少 manifest.json,或其中沒有有效的 name,會在任何修改之前
使安裝失敗。
兩個模組名稱相同(不區分 ASCII 大小寫)的模組不能安裝在同一個工作區中。
條目在 mcmod 資源之外還可以有其他資源,例如一個把檔案放到 mods/ 之外的 zip 資源。
身份
已安裝套件的身份是其套件 ID,當變體不為 "" 時再加上 #<variant>,例如
github.com/LiteLDev/LegacyScriptEngine#lua。一個工作區中每個身份至多有一個套件;
lip list 顯示身份,lip uninstall 也接受
身份。
身份來自套件的 id,而不是安裝來源:lip.toml 寫有 id = "github.com/user/repo" 的 ZIP 檔案,
與來自該儲存庫的套件身份相同,因此兩者不能同時安裝。
環境
工作區的環境是一個二元組 (side, platform):
- 執行端(side):
server或client,即工作區是遊戲的哪一端。lip 只管理服務端工作區,因此始終使用server。客戶端工作區由 LeviLauncher 等啟動器管理;若工作區的狀態檔記錄的是client,lip 會拒絕處理。 - 平臺(platform):一個 .NET RID,始終為
win-x64, 無論 lip 執行在什麼系統上。在 Windows 以外的系統上,lip 通過 Wine 執行工作區的程式(參見 Linux 和 macOS)。Linux 版伺服器不是另一個平臺,而是github.com/LiteLDev/bds的變體linux,其條目的平臺是win-x64。早期 lip 寫下的、記錄linux-x64的狀態檔會被當作win-x64的狀態檔讀取 (參見狀態檔)。以win開頭的平臺是 Windows 平臺。
早期格式
lip v0.39 的 lip.toml 同樣是格式 4,但把執行端寫作 platform、把平臺寫作 runtime,例如
platform = "server" 和 runtime = "win-x64"。lip 不讀取這樣的條目:含有 runtime、或 platform 為
"server" 或 "client" 的條目會使該歸檔不是套件,並給出消息,提示把 platform 改名為 side、把
runtime 改名為 platform。把每個條目的這兩個鍵改名即可,其餘內容保持不變。
lip v0.37.0 及更早版本的套件沒有 lip.toml,而是有格式版本 1、2 或 3 的 tooth.json。lip 仍會安裝它們,
但從不寫入它們;請使用 lip pkg migrate 把你的套件轉換為 lip.toml。帶有
lip.toml 的歸檔從 lip.toml 讀取,不論它是否還有 tooth.json;其他格式的 tooth.json 不會被讀取。
格式 1 和 2 先像 lip v0.37.0 那樣讀取為格式 3。格式 3 的 tooth.json 隨後針對工作區的環境被完整地
轉換為一個套件檔,lip 只使用轉換結果:
lip 解析、安裝並記錄到狀態檔中的都是它。安裝時不再保留任何格式 3 的語義。
tooth變為id。version為套件的版本:在版本標籤處為標籤版本,而不論tooth.json的version寫的是 什麼;否則為該version。- 保留
info,但其avatar_url以https://開頭時變為logo,否則被丟棄。 - 對每個標籤,將該標籤下
platform為空或與環境的平臺符合(tooth.json的platform是 RID 模式, 例如win-*)的變體,按 lip v0.37.0 的方式合併為一個對應該環境執行端和平臺的條目。 沒有這類變體的標籤不構成變體。 dependencies原樣變為deps。- 每個資源保留其
type和urls,其placements變為place(見下文)。類型為tar、tgz或uncompressed的資源在lip.toml中不存在,會使該標籤在該環境下沒有變體。 preserve_files變為preserve:\取代為/,不含/的模式加上前綴**/,因此config.json變為**/config.json。remove_files變為purge:\取代為/,不以/結尾的模式還會再加上一個以/結尾的形式,因此logs變為logs和logs/。- scripts 變為
hooks:pre_install仍為pre_install;install和隨後的post_install變為post_install;pre_uninstall和隨後的uninstall變為pre_uninstall;post_uninstall仍為post_uninstall。
放置規則 { "type": ..., "src": ..., "dest": ... } 在 src 和 dest 中的 \ 取代為 /、空段和 . 段被移除
後,變為 place 的一個成員:
| 放置規則 | place 成員 |
|---|---|
type 為 dir |
src 和 dest 各自加上 /(為空時除外):目錄形式。 |
type 為 file,src 含 *、? 或 [ |
src,以及加上 / 的 dest(為空時除外):glob 形式。 |
type 為 file,其他 src |
src 和 dest:檔案形式。 |
轉換後在套件檔中無效的 glob 或放置規則會被略去。隨後放置規則按 lip.toml 的方式執行:例如,缺失的檔案現在會使安裝
失敗,套件的 tooth.json 也永遠不會被寫入。
早期格式的套件始終是檔案套件。其身份遵循同樣的規則,例如 github.com/LiteLDev/LegacyScriptEngine#lua。
格式 3 的 schema 是 lip v0.37.0 的
manifest.schema.json,
lip v0.37.0 在其套件清單頁面
中記錄了這一格式:
{
"format_version": 3,
"format_uuid": "289f771f-2c9a-4d73-9f3f-8492495a924d",
"tooth": "github.com/user/repo",
"version": "1.0.0",
"info": { "name": "My Package", "description": "A short description" },
"variants": [
{
"label": "",
"platform": "win-x64",
"dependencies": { "github.com/other/package": ">=1.0.0" },
"assets": [
{
"type": "self",
"placements": [{ "type": "dir", "src": "bin/", "dest": "bin/" }]
}
],
"preserve_files": ["config/*.json"],
"remove_files": ["temp/"],
"scripts": { "post_install": ["echo installed"] }
}
]
}另請參閱
- 用 lip 發佈你的模組和移轉套件
lip pkg init、lip pkg view- 狀態檔:每個已安裝套件的套件檔記錄在哪裡。
- 內部機制:lip 怎樣解析來源和版本。