指令

每個 Rebar3 指令的用法。

每個指令代表一個任務，它會執行一個或多個提供者來完成任務。

別名

列出別名的定義 (來自 rebar.config)。

範例輸出

test=eunit,ct --suite=rebar_alias_SUITE,cover
check=xref,dialyzer

as

高階任務，它接受一個設定檔名稱和要在該設定檔下執行的任務列表。

編譯

在確保所有相依性都可用，並在它們不可用時取得它們之後，編譯將編譯所需的相依性和專案應用程式的 .app.src 和 .erl 檔案。

選項 類型 說明
-d/--deps_only 無 僅編譯相依性，不建置專案應用程式

completion (自動完成)

📘

自 3.23.0 版本起

為其中一個支援的 shell 產生自動完成檔案：bash、zsh。

可以根據專案設定產生自動完成檔案，因此自動完成也適用於專案中使用的所有插件，而不僅僅是預設提供者。

要使用產生的自動完成檔案，請執行 source path/to/generated/file。

選項 類型 說明
-a/--aliases 以逗號分隔的字串列表 將觸發 rebar3 自動完成的作業系統層級別名（例如 "rebar, r3"）
-f/--file 字串 自動完成檔案名稱。 如果不是絕對路徑，則相對於 _build/<profile>/ 目錄
-s/--shell atom 指定自動完成檔案的類型。 預設情況下，使用 $SHELL 變數自動偵測。 有效值為 bash 和 zsh。

🚧

zsh 特定要求

請確保在 .zshrc 檔案中呼叫 autoload -Uz compinit; compinit。

為了獲得更好的使用者體驗，請設定預設自動完成並在需要時覆蓋它。 可以透過產生全域自動完成檔案並將其載入 .bashrc 或 .zshrc 中來設定預設自動完成。

要產生全域（與專案無關）自動完成檔案，請在 rebar3 專案之外執行 rebar3 completion --file path/to/global/completion/file。

清除

從應用程式中移除已編譯的 BEAM 檔案。

clean 指令預設會移除頂層應用程式的 BEAM 檔案。它在執行此操作時會遵守設定檔，這表示「rebar3 clean」只會清除預設設定檔，而「rebar3 as test clean」只會清除測試設定檔。

選項 類型 說明
--all/-a 無 清除所有應用程式，包括相依性
--apps 以逗號分隔的字串列表 清除特定應用程式或相依性列表
--profile/-p 字串 指定設定檔（rebar3 as clean 的替代方案）

ct (Common Test)

執行位於 test/ 目錄下專案的 Common Test。

大多數 Common Test 選項，如 Erlang 文件中針對 ct_run 所述，都可用。以下說明一些常見的選項

選項 類型 說明
--dir 以逗號分隔的字串列表 編譯並執行指定目錄中的所有測試套件。
--suite 以逗號分隔的字串列表 編譯並執行所有指定的測試套件。必須透過完整路徑指定，可以是絕對路徑或相對於目前目錄的路徑。
--group 以逗號分隔的字串列表 要執行的測試群組。請參閱 Common Test 文件。
--case 以逗號分隔的字串列表 要執行的測試案例列表。請參閱 Common Test 文件。
--spec 以逗號分隔的字串列表 測試規格 列表
--join_specs 以逗號分隔的字串列表 類似於 --spec，但會將所有規格合併成一個並執行一次。
--repeat 整數 重複測試的次數
--duration 字串（格式：HHMMSS） 測試執行的最長允許持續時間
--until 字串（格式：HHMMSS） 執行測試的截止時間
--force_stop true | false | skip_rest 測試逾時時強制終止
--multiply_timetraps 整數 將測試的逾時值乘以給定的乘數值來延長
--scale_timetraps 布林值 使用程式碼覆蓋率或追蹤時，啟用自動逾時值調整
--abort_if_missing_suites 布林值 如果缺少測試套件，則中止測試執行（預設值：true）
--sys_config 字串 Rebar3 在測試執行前應套用的 OTP 應用程式設定檔列表（例如 sys.config）。
--config 以逗號分隔的字串列表 執行測試時要使用的設定檔。請參閱 [Common Test 文件](https://erlang.dev.org.tw/doc/apps/common_test/index.html)
--allow_user_terms 布林值 允許在設定檔中使用使用者定義的設定值。請參閱 Common Test 文件。
--decrypt_key 字串 如果設定檔已加密，請設定用於解密的密鑰
--decrypt_file 字串 如果設定檔已加密，請指向包含用於解密密鑰的檔案
--logdir 字串 將寫入測試日誌的目錄。請參閱 Common Test 文件。
預設值：_build/test/logs
--logopts 以逗號分隔的字串列表 設定 Common Test 日誌選項。請參閱 Common Test 文件。
預設值：_build/test/logs
--readable 布林值 以每個測試為基礎添加帶有結果的測試名稱，並且僅在測試失敗時在終端機中顯示 Common Test 日誌。
預設值：true
--verbose, -v 布林值 啟用詳細輸出。 預設值：false
--verbosity 整數 設定 Common Test 詳細資訊的級別
--cover, -c 布林值 產生覆蓋率數據
--cover_export_name 字串 變更程式碼覆蓋率檔案的名稱
--label 字串 設定測試標籤
--basic_html 布林值 顯示基本的 HTML
--stylesheet 字串 套用於 HTML 輸出的 CSS 樣式表
--create_priv_dir auto_per_run | auto_per_tc | manual_per_tc 變更 Common Test 執行私人（暫存）目錄建立的行為
--include 字串 包含標頭檔的其他目錄。新增此選項是為了與 ct_run 保持一致，通常 rebar3 應該處理標頭檔路徑
--name, --sname 字串 使用給定名稱啟動分散式節點
--setcookie 字串 設定分散式 Cookie 的值
--compile_only 布林值 使用指定的測試設定編譯專案，但不執行測試

在 test 設定檔中執行。

cover (覆蓋率)

對 Common Test 或 Eunit 測試套件呼叫的模組執行覆蓋率分析。當您的 rebar 設定檔中有 {cover_enabled, true} 選項，或者如果單獨使用這些指令時使用了覆蓋率標誌，則以 rebar3 do ct, cover、rebar3 do eunit, cover 或兩者組合 rebar3 do eunit, ct, cover 的方式呼叫。

會產生 HTML 報告。

選項 類型 說明
-m, --min_coverage 整數 強制要求成功的覆蓋率百分比 (0..100)
--reset, -r 無 重設所有覆蓋率數據
--verbose, -v 無 在終端機中列印覆盖率分析。

可以透過在設定檔中新增 {cover_excl_mods, [Modules]} 將特定模組從程式碼覆蓋率中列入黑名單。可以透過在設定檔中新增 {cover_excl_apps, [AppNames]} 將特定應用程式列入黑名單。

deps (相依性)

列出相依性，無論是來源還是套件相依性，以及它們是否已鎖定。那些已鎖定但不符合鎖定檔案的相依性後面會加上星號 (*)。

do

用於依序執行多個任務的高階提供者，以逗號分隔。範例：rebar3 do a, b, c。

dialyzer (程式碼分析)

建置並保持合適的 PLT（持久查詢表）最新，並使用它對目前專案執行成功類型分析。

選項 類型 說明 預設值
--incremental, -i 布林值 啟用增量分析模式。 false
--update-plt, -u 布林值 啟用 PLT 更新。 true
--succ-typings, -s 布林值 啟用成功類型分析。 true

有關隱藏警告的說明，請閱讀 Dialyzer 文件的 在原始程式檔中請求或隱藏警告 一節。

PLT 檔案命名為 <prefix>_<otp_release>_plt；基本 PLT 是一個包含專案 PLT 通常所需的核心應用程式的 PLT。每個 OTP 版本會建立一個基本 PLT 並儲存在 base_plt_location 中。然後使用基本 PLT 來建置專案 PLT。

以下（可選）配置可以添加到 rebar.config 中的 options dialyzer 的 proplist 中。

選項 說明
warnings（警告） dialyzer 警告列表
get_warnings（取得警告） 在更改 PLT 檔案時顯示警告（布林值）
plt_apps（PLT 應用程式） 決定 PLT 檔案中包含哪些應用程式的策略，top_level_deps 只包含直接依賴項，或 all_deps 包含所有嵌套依賴項（直接依賴的應用程式列在它們的 .app 檔案的 applications 和 included_applications 中。）
plt_extra_apps（額外 PLT 應用程式） 要包含在 PLT 檔案中的應用程式列表（base_plt_apps 中的應用程式已在列表中）
plt_location（PLT 位置） PLT 檔案的位置，local 儲存在設定檔的基本目錄中（預設），或自訂目錄。
plt_prefix（PLT 前綴） PLT 檔案的前綴，預設為“rebar3”
base_plt_apps（基礎 PLT 應用程式） 要包含在基礎 PLT 檔案中的應用程式列表
base_plt_location（基礎 PLT 位置） 基礎 PLT 檔案的位置，global 儲存在 $HOME/.cache/rebar3 中（預設），或自訂目錄。
base_plt_prefix（基礎 PLT 前綴） 基礎 PLT 檔案的前綴，預設為“rebar3”
incremental（增量） 增量分析模式

edoc (文件產生)

使用 doc 產生文件。

在 docs 設定檔中執行。

escriptize (腳本化)

產生一個包含專案及其相依套件的 BEAM 檔案的 escript 可執行檔。

配置選項 類型 說明
escript_main_app（主要 Escript 應用程式） atom 要轉換為 escript 的應用程式名稱。如果只有一個應用程式，則預設為最上層的應用程式。當使用 umbrella 儲存庫（具有多個最上層應用程式）時，*必須*指定此值。
escript_name（Escript 名稱） 字串 產生的 escript 的名稱，以及要啟動的預設模組名稱 (Module:main(_))。預設為 escript_main_app 的值。
escript_incl_apps（包含的 Escript 應用程式） atom 列表 除了主要應用程式及其相依套件（來自 app 檔案）之外，要包含在 escript 封存中的應用程式列表。預設為 []。
escript_emu_args（Escript 模擬器參數） 字串 Escript 模擬器參數（在 escript 宣告中的 %%! 之後）。字串必須以 %%! 開頭，並以換行符號結尾。範例字串為 "%%! +sbtu +A0\n"。預設值為 "%%! -escript main MainApp\n"。
escript_shebang（Escript Shebang） 字串 要執行的 escript 檔案的位置。預設為 "#!/usr/bin/env escript\n"。字串中必須包含換行標記。
escript_comment（Escript 註解） 字串 要放入產生的 escript 中的任意註解。結尾必須包含換行標記。預設為 %%\n。

要覆寫 escript 的預設模組名稱（預期與 escript_name 相同），請將 -escript main Module 添加到 escript_emu_args 中。

來自 relx 的 Escript 配置範例

{escript_emu_args, "%%! +sbtu +A0 -noinput\n"}.
{escript_incl_apps, [getopt, erlware_commons, bbmustache, providers, relx]}.

eunit (單元測試)

對專案應用程式執行 EUnit 測試。

配置選項 類型 說明
--application（應用程式） 以逗號分隔的字串列表 要執行的應用程式測試套件。相當於 [{application, App}]。
-c, --cover（覆蓋率） 布林值 產生覆蓋率資料。預設為 false。
--cover_export_name 字串 要寫入的覆蓋率資料檔案的基本名稱。
-p, --profile（效能分析） 布林值 顯示最慢的測試。預設為 false。
-d, --dir（目錄） 以逗號分隔的字串列表 要載入測試的目錄。相當於 [{dir, Dir}]。
-f, --file（檔案） 以逗號分隔的字串列表 要載入測試的檔案。相當於 [{file, File}]。
-m, --module（模組） 以逗號分隔的字串列表 要載入測試的模組。相當於 [{module, Module}]。
-t, --test（測試） 以逗號分隔的字串列表 要執行的測試。格式為 Module:Func1+Func2。相當於 [{test, Module, Function}]。
-g, --generator（產生器） 以逗號分隔的字串列表 要載入測試的產生器。格式為 Module:Func1+Func2。相當於 [{generator, Module, Function}]。
-v, --verbose（詳細） 布林值 詳細輸出。預設為 false。
--name（名稱） 字串 賦予節點一個長名稱。
--sname（簡稱） 字串 賦予節點一個簡稱。
--sys_config 以逗號分隔的字串列表 應用程式設定檔列表。
--setcookie 字串 如果節點是分散式的，則設定 cookie。

更多詳細資訊，請參閱 EUnit。

在 test 設定檔中執行。

get-deps (取得相依性)

🚧

非必要

與 Rebar 2 不同，此命令不需要用於擷取相依套件。compile 命令將會擷取相依套件，如果它們尚未建置，則會建置它們。如果您有需要將擷取相依套件與編譯分開的特定用例，則此命令很有用。

擷取專案相依套件。

help (說明)

顯示任務列表或給定任務或子任務的說明。

選項 說明
<task>（任務） 要顯示說明的任務。
<namespace> <task>（命名空間、任務） 要顯示說明的 <namespace> 中的任務。

new (新增)

從範本建立新專案。不提供任何參數即可查看可用範本列表。

選項 說明
--force, -f（強制） 覆寫現有檔案。
help <template>（說明、範本） 顯示每個範本的所有變數和參數。

path (路徑)

列印目前設定檔中建置目錄的路徑。

選項 類型 說明
--app（應用程式） 以逗號分隔的字串列表 以逗號分隔的應用程式列表，用於傳回路徑。
--base（基礎） 無 傳回目前設定檔的基底路徑。
--bin（執行檔） 無 傳回目前設定檔的執行檔路徑。
--ebin（ebin） 無 傳回目前設定檔的應用程式的所有 ebin 路徑。
--lib（函式庫） 無 傳回目前設定檔的函式庫路徑。
--priv（私有） 無 傳回目前設定檔的私有路徑。
--separator, -s（分隔符號） 字串 如果有多個傳回路徑，則使用分隔符號字元將它們連接起來。
--src（原始碼） 無 傳回目前設定檔的應用程式的原始碼路徑。
--rel（發行版） 無 傳回目前設定檔的發行版路徑。

release (發布)

建置專案的發行版。呼叫 rebar3 help release 以取得參數。

relup (熱更新)

透過呼叫 rebar3 release 而不清除 _build 目錄，從兩個已建置的發行版建立 relup。呼叫 rebar3 help relup 以取得參數。

report (報告)

產生要包含在錯誤報告中的上下文資料。

shell (終端機)

執行一個 shell，其中包含專案應用程式和相依套件的路徑。僅供開發使用；使用 發行版 進行生產。

選項 類型 說明
--config 字串 允許載入 設定檔（如果有的話）。預設為 relx 的 sys_config 項目（如果有的話）。
--name, --sname atom 以網路模式啟動節點。相當於 erl 的 -name 和 -sname 選項。
--setcookie 字串 設定分散式節點的 cookie。相當於 erl 的 -setcookie 選項。
--script（腳本） 字串 要在啟動應用程式之前評估的 escript 的路徑。
--apps 字串 以逗號分隔的要啟動的應用程式名稱列表。預設為 relx 發行版中的應用程式（如果有的話）。
--start-clean（乾淨啟動） 指定時，shell 不會啟動任何應用程式；可用於覆寫 rebar.config 中的發行版或 shell tuple 設定。
--relname, -r（發行版名稱） atom 如果存在多個發行版，請指定要選擇哪一個。
--relvsn, -v（發行版版本） 字串 如果存在多個發行版，請指定要使用哪個版本。
--env-file（環境變數檔案） 字串 在展開設定檔中的變數之前要設定的作業系統環境變數檔案的路徑。
--user_drv_args（使用者驅動程式參數） 字串 對於 26 以前的 Erlang 版本，此選項可用於將參數傳遞給 user_drv start 函式以建立自訂 shell。從 Erlang 26 開始，使用此選項定義的參數將套用至 shell start_interactive 函式。
--eval（評估） 字串 在啟動期間要執行的 Erlang 運算式。這些運算式將在最後執行，就在向使用者顯示 Erlang shell 提示之前。可以有多個 --eval 切換。大致相當於 erl 的 -eval 選項。

使用此命令啟動的 shell 有一個正在執行的代理，允許動態執行 Rebar3 命令，例如 r3:compile() 或 r3:upgrade()，並自動重新載入新的模組。可以透過呼叫 r3:do(Namespace, Command) 來訪問特定的命名空間。無法將參數傳遞給這些命令。

tar (打包)

建置專案發行版的壓縮 tar 封存。呼叫 rebar3 help tar 以取得參數。

tree (樹狀結構)

列印專案的相依套件和遞移相依套件的樹狀結構。

選項 類型 說明
-v, --verbose（詳細） 無 列印 git 和 hg 相依套件的儲存庫和分支/標籤/參考。

lock (鎖定)

取得要添加到 rebar.lock 檔案中未建置的相依套件。它們只會被下載，但它們的建置腳本都不應該運行。雖然對於 pre/post hooks 和 dep plugins 來說，這不一定是正確的。

unlock (解鎖)

解鎖相依套件。指定以逗號分隔的要解鎖的相依套件列表，並重新產生 rebar.lock 檔案，或者使用 -a,--all 解鎖所有相依套件並移除 rebar.lock 檔案。

當一個或多個相依套件已從 rebar.config 中移除，但仍保留在鎖定檔案中時，應使用此命令。

選項 類型 說明
<dependency>（相依套件） 字串 要解鎖的相依套件（以逗號分隔）。
-a, --all（全部） 無 解鎖所有相依套件。

update (更新)

更新套件索引。

upgrade (升級)

取得 rebar.config 中目前的相依套件規格，並擷取滿足它們的最新版本，同時相應地更新鎖定檔案。

選項 類型 說明
<dependency>（相依套件） 字串 要升級的相依套件（以逗號分隔）。
-a, --all（全部） 無 升級所有相依套件。

version (版本)

列印 rebar3 和目前 Erlang 的版本。

xref (交叉參考)

執行交叉參考分析。

上次修改時間：2024 年 3 月 10 日：completion_prv 的文件 (4e75dd1)