跳轉到

Veryl.toml 專案設定#

Cargo 之所以成功，一半功勞在 Cargo.toml：一個檔案就說明專案是什麼、怎麼建、怎麼測。Veryl 對應的檔案是 Veryl.toml，放在專案根目錄，是整個工具鏈行為的單一設定來源。

一個典型的 Veryl.toml#

[project]
name    = "my_proj"
version = "0.1.0"

[build]
clock_type     = "posedge"
reset_type     = "async_low"
filelist_type  = "flist"

[format]
indent_width = 4

[test]
waveform_target = "directory"

[doc]
path = "doc"

這份檔案的結構對 Cargo 使用者完全熟悉：頂層以區段（section）劃分關注點，每個區段管一件事。

[project] 區段#

name 定義專案的唯一名稱，會出現在 filelist、發布與依賴解析中，就像 crate 的名字；version 使用語意化版本（semver）。當專案之間有相依關係時，靠 name 與 version 定位彼此。

[build] 區段：全域的硬體慣例#

這是 Veryl.toml 最有深意的部分。clock_type 與 reset_type 指定整個專案的時脈與重置慣例：時脈是正緣（posedge）還是負緣，重置是非同步還是同步、active high 還是 active low。為什麼要全域設定而不是每個 module 自己寫？回頭看 SystemVerilog 的歷史：每家公司的 RTL 對 reset 寫法各自不同，always @(posedge clk or negedge rst_n) 與 always @(posedge clk) if (!rst_n) 混雜在一個 codebase 是家常便飯，review 與 lint 都要逐一檢查。Veryl 把這個慣例上收為專案層級設定：原始碼裡你一律寫 clock、reset 型別與 if_reset，具體展開成正緣或負緣、同步或非同步，由 Veryl.toml 統一決定。換一家公司、換一個 reset 慣例，只改設定不改程式碼。這是「慣例即設定」思想在 HDL 中的落地，也是 Veryl 的 reset_async_high、clock_posedge 這類型別變體存在的背景。

filelist_type 則決定 veryl build 產出的 filelist 格式——把編譯順序與來源清單寫成下游工具（模擬器、綜合器）能吃的格式。filelist 是 EDA 工具鏈的「膠水」，各工具各有格式偏好，Veryl 支援多種常見格式，讓轉譯輸出可以直接接上你既有的腳本。具體支援的格式名稱隨版本擴充，使用時以官方文件為準。

[format] 區段#

控制 veryl fmt 的行為，例如縮排寬度。如同 rustfmt，Veryl 的態度是「格式不該被討論」：專案裡設定一次，所有人的輸出一致，code review 只看邏輯不看縮排。

[test] 區段#

控制 veryl test 內建模擬測試的行為，例如波形傾印的位置與方式（waveform_target 指定波形檔要集中放到目錄還是其他模式）。Veryl 的測試體系會在後面的章節詳細展開，這裡只需要知道：測試的組態也集中在 Veryl.toml，不必另寫 script。

[doc] 區段#

控制 veryl doc 產生文件的行為，例如輸出路徑。Veryl 從原始碼中的 /// 文件註解產生 HTML 文件，機制完全對應 rustdoc——文件與程式碼放在一起、由同一個工具鏈維護，而不是活在另一份會過期的 spec 裡。

依賴與發布#

Veryl.toml 還可以宣告對其他 Veryl 專案的依賴（如 [dependencies]），由工具鏈解析抓取，如同 Cargo 的依賴管理；veryl publish 則配合發布流程使用。這些進階用法在後續章節再談。

設定即文件#

最後提醒一個閱讀視角：Veryl.toml 不只是給工具看的設定，它同時是給人看的專案說明書。拿到一個陌生的 Veryl 專案，第一件事讀 Veryl.toml，十秒內你就知道專案叫什麼、reset 慣例是什麼、測試與文件怎麼跑。在 SystemVerilog 的世界，這些資訊散落在 wiki、口耳相傳與無數 script 裡；Veryl 把它們收進一個檔案。這就是「設定即文件」的價值。

本章小結#

  • Veryl.toml 是專案單一設定來源，結構與 Cargo.toml 同型：[project]、[build]、[format]、[test]、[doc] 區段。
  • [build] 的 clock_type、reset_type 把時脈/重置慣例上收為專案級全域設定，程式碼寫抽象型別、設定決定展開。
  • filelist_type 決定輸出 filelist 的格式，銜接既有 EDA 腳本。
  • [format]、[test]、[doc] 分別組態 fmt、test、doc 的行為。
  • 慣例即設定、設定即文件，是 Veryl 專案管理的核心思想。