插件

插件可以安裝在本地、專案或全域。若要安裝本地插件,請在專案的 rebar.config 檔案中的 plugins 下指定它。全域安裝的插件會在 ~/.config/rebar3/rebar.config 中設定,並在您於專案中使用 Rebar3 指令時自動安裝。

包含插件

建置應用程式所需的插件應以與 deps 中列出的相依性相同的格式包含在 plugins 下。它們建置在 _build/<profile>/plugins/ 目錄下,並列在 rebar3 help 的輸出中,可作為任務和在 provider_hooks 中使用

{plugins, [{rebar_erl_vsn, "~> 0.1"}]}.
{provider_hooks, [{pre, [{compile, {default, erl_vsn}}]}]}.

上述設定將導致在 compile 任務之前執行 erl_vsn 任務。此插件會將定義新增至編譯設定,例如,如果在 Erlang 17 以上的版本上執行,它將在編譯期間於 erl_opts 中包含 {d, 'maps'}

專案插件和覆寫指令

某些插件如果能夠覆寫可用指令,則效果最佳。但是,當包含插件的專案被用作相依性時,插件不應該能夠執行此操作。 project_plugins 定義僅在專案直接由 rebar3 指令建置時可用的插件,例如從應用程式/專案的頂層目錄執行 rebar3

例如,cuttlefish 插件僅在建置發行版本時才需要,因此不擷取它並使其可供每個應用程式相依性使用是有意義的。如果它與建置發行版本或tarball 的方式相同,則效果最佳。因此,當包含在 project_plugins 中時

{project_plugins, [rebar3_cuttlefish]}.

執行 rebar3 releaserebar3 tar 將執行 rebar3_cuttlefish 提供者,而不是內建提供者。

此外,在某些情況下,您只需要一個用於開發的插件。假設您有 protobufs 並將產生的模組提交到儲存庫並包含在 Hex 套件中,那麼當應用程式是相依性時,protobuf 插件不需要可用,並且僅用於開發目的。在 project_plugins 之前,通常會看到一個在其下添加了插件的 dev 設定檔,但这需要執行 rebar3 as dev protobuf 並處理 _build 下的另一個設定檔。使用專案插件,設定可以改為

{project_plugins, [rebar3_gpb_plugin]}.

現在我們只需要執行 rebar3 protobuf。我們不包含任何鉤子,因為我們會將產生的程式碼提交到儲存庫,並且如果此專案用作相依性,則不會擷取插件。

升級插件

插件的工作方式有點像相依性(儘管它們目前沒有被版本鎖定);除非您要求更新它們,否則它們不會自動更新。

  • 您可以透過呼叫 rebar3 plugins upgrade <plugin_name> 來升級專案本機插件。
  • 您可以透過呼叫 rebar3 as global plugins upgrade <plugin_name> 來升級全域插件,這將調用一個隱藏的全域設定檔,專門用於切換插件的升級上下文。

如果您使用 Hex 套件作為插件,但沒有看到預期的版本,請記住使用呼叫 rebar3 update 以取得最新的 Hex 索引。再次強調,由於插件沒有作為鎖定檔案的一部分鎖定,因此始終為它們指定版本可能是一個好主意。

自動編譯和載入

對於 auto 插件,建議將條目放在全域 rebar3 設定中,該設定應設為 ~/.config/rebar3/rebar.config

{plugins, [rebar3_auto]}.

執行 rebar3 auto 將啟動 shell,與執行 rebar3 shell 相同,但將會監聽專案應用程式來源目錄中的檔案變更。當檔案變更時,它將通知 Rebar3 代理程式執行編譯並重新載入模組。

自動測試

對於 autotest 插件,建議將條目放在全域 rebar3 設定中,該設定應設為 ~/.config/rebar3/rebar.config

{plugins, [{rebar3_autotest, "0.1.1"}]}.

執行 rebar3 as test autotest 將啟動 eunit 一次,並為您的來源、標頭和測試檔案設定監控,以便它在其中一個檔案發生變更時重新執行 eunit

Hex 套件管理

對於 hex 插件,建議將條目放在全域 rebar3 設定中,該設定應設為 ~/.config/rebar3/rebar.config

{plugins, [rebar3_hex]}.

使用方法請參考Hex 套件管理章節和發佈套件教學。要檢視套件,請前往hex.pm,要開啟問題,請前往GitHub

Port 編譯器

此插件為 rebar3 提供了舊的 rebar 介面,用於建置 C 和 C++ 程式碼。套件可以在hex.pm找到,問題可以在GitHub找到。

在您的專案的 rebar.config 中,新增 pc 插件並在 provider_hooks 中呼叫它以進行 compileclean

{plugins, [pc]}.

{provider_hooks,
 [
  {pre,
   [
    {compile, {pc, compile}},
    {clean, {pc, clean}}
   ]
  }
 ]
}.

可用的設定變數

%% Supported configuration variables:
%%
%% * port_specs - Erlang list of tuples of the forms
%%                {ArchRegex, TargetFile, Sources, Options}
%%                {ArchRegex, TargetFile, Sources}
%%                {TargetFile, Sources}
%%
%% * port_env - Erlang list of key/value pairs which will control
%%              the environment when running the compiler and linker.
%%              Variables set in the surrounding system shell are taken
%%              into consideration when expanding port_env.
%%
%%              By default, the following variables are defined:
%%              CC       - C compiler
%%              CXX      - C++ compiler
%%              CFLAGS   - C compiler
%%              CXXFLAGS - C++ compiler
%%              LDFLAGS  - Link flags
%%              ERL_CFLAGS  - default -I paths for erts and ei
%%              ERL_LDFLAGS - default -L and -lerl_interface -lei
%%              DRV_CFLAGS  - flags that will be used for compiling
%%              DRV_LDFLAGS - flags that will be used for linking
%%              EXE_CFLAGS  - flags that will be used for compiling
%%              EXE_LDFLAGS - flags that will be used for linking
%%              ERL_EI_LIBDIR - ei library directory
%%              DRV_CXX_TEMPLATE      - C++ command template
%%              DRV_CC_TEMPLATE       - C command template
%%              DRV_LINK_TEMPLATE     - C Linker command template
%%              DRV_LINK_CXX_TEMPLATE - C++ Linker command template
%%              EXE_CXX_TEMPLATE      - C++ command template
%%              EXE_CC_TEMPLATE       - C command template
%%              EXE_LINK_TEMPLATE     - C Linker command template
%%              EXE_LINK_CXX_TEMPLATE - C++ Linker command template
%%
%%              Note that if you wish to extend (vs. replace) these variables,
%%              you MUST include a shell-style reference in your definition.
%%              e.g. to extend CFLAGS, do something like:
%%
%%              {port_env, [{"CFLAGS", "$CFLAGS -MyOtherOptions"}]}
%%
%%              It is also possible to specify platform specific options
%%              by specifying a triplet where the first string is a regex
%%              that is checked against Erlang's system architecture string.
%%              e.g. to specify a CFLAG that only applies to x86_64 on linux
%%              do:
%%
%%              {port_env, [{"x86_64.*-linux", "CFLAGS",
%%                           "$CFLAGS -X86Options"}]}
%%
%%              Cross-arch environment variables to configure toolchain:
%%              GET_ARCH to set the tool chain name to use
%%              GET_ARCH_WORDSIZE (optional - to determine word size)"
%%              word size is 32
%%              GET_ARCH_VSN (optional - "
%%              l version of CC/CXX is requested),

執行發行版本

rebar3 run 將啟動發行版本主控台,而不必執行 _build/default/rel/<release>/bin/<release> console。可以在GitHubhex.pm找到。

{plugins, [rebar3_run]}.

別名

從 3.5.0 版開始,Rebar3 中已新增 alias 插件。請參閱 </docs/workflow/#create-aliases-for-common-tasks> 以取得說明。

對於先前版本,用於將單個指令別名以執行多個任務的插件可以在GitHubHex.pm找到。

{plugins, [rebar_alias]}.

{alias, [{check, [eunit, {ct, "--sys_config=config/app.config"}]}]}.

可以透過將 Provider 替換為 {Provider, Args} 來傳遞參數(與命令列一樣)。

QuickCheck

一個 Rebar3 插件,可以執行 Erlang QuickCheck 屬性。可以在 GitHubHex.pm 找到。

{plugins, [rebar3_eqc]}.

QuickCheck 的設定選項位於 eqc_opts 下,例如 {eqc_opts, [{numtests, 500}]}.

設定選項 類型 說明
numtests 整數 測試執行次數,預設為 100。
testing_time 整數 執行屬性的時間(以秒為單位)。如果同時指定了兩者,則忽略 testing_time 設定。

同樣地,可以在命令列上传递設定

選項 類型 說明
-n 整數 測試執行次數,預設為 100。
-t 整數 執行屬性的時間(以秒為單位)。如果同時指定了兩者,則忽略 testing_time 設定。
-p 字串 要執行的屬性。可以是 module:propertyproperty,插件將會決定模組。

PropEr

PropEr 是 Quviq QuickCheck 的免費替代方案。該插件在 Hex 上作為套件提供或在GitHub上提供

%% the plugin itself
{plugins, [rebar3_proper]}.

%% The PropEr dependency is still required to compile the test cases
{profiles,
    [{test, [
        {deps, [{proper, "1.1.1-beta"}]}
    ]}
]}.

所有 PropEr 的設定選項都可以在 rebar.config 中的 {proper_opts, Options} 下傳遞,或作為命令列參數傳遞

rebar.config 鍵 命令列 說明
{dir, String} -d, –dir 存放屬性測試的目錄(預設為“test”)
{module, [Modules]} -m, –module 要測試的一個或多個模組的名稱
{properties, [PropNames]} -p, –prop 指定模組中要測試的屬性的名稱
{numtests, N} -n, –numtests 測試給定屬性時要執行的測試次數
verbose | quiet -v, –verbose 每個測試的屬性是否顯示其輸出(預設為 true/verbose)
{cover, true | false} -c, –cover 產生覆蓋率數據(預設值:false)
long_result –long_result 啟用長結果模式,在失敗時顯示反例,而不僅僅是 false
{start_size, N} –start_size 指定大小參數的初始值
{max_size, N} –max_size 指定大小參數的最大值
{max_shrinks, N} –max_shrinks 指定在返回之前應縮小失敗測試案例的最大次數
noshrink –noshrink 指示 PropEr 不要嘗試縮小任何失敗的測試案例
{constraint_tries, N} –constraint_tries 指定在產生器子系統放棄產生滿足 ?SUCHTHAT 約束的實例之前嘗試的最大次數
{spec_timeout, Millisecs} –spec_timeout 持續時間(以毫秒為單位),在此持續時間之後,PropEr 認為輸入失敗
any_to_integer –any_to_integer 將 any() 類型的實例轉換為整數以加快執行速度

Diameter

rebar3_diameter_compiler 插件會在 Rebar3 專案中編譯 diameter .dia 檔案。

{plugins, [rebar3_diameter_compiler]}.

自動編譯和清理 diameter 字典的鉤子

{provider_hooks, [
    {pre, [
        {compile, {diameter, compile}},
        {clean, {diameter, clean}}
    ]}
]}.

配置選項

設定選項 類型 說明
dia_opts 列表 除了 inherits 之外,支援 diameter_make:codec/2 的所有選項。
dia_first_files 列表 需要優先編譯的檔案序列。

ErlyDTL

erlydtl 編譯器已移至單獨的插件。

{plugins, [
    {rebar3_erlydtl_plugin, ".*",
     {git, "https://github.com/tsloughter/rebar3_erlydtl_plugin.git", {branch, "master"}}}
]}.

配置選項以列表形式放在 rebar.configerlydtl_opts 下。

設定選項 類型 說明
doc_root 字串 在哪裡找到要編譯的模板。預設為「priv/templates」。
compiler_options 屬性列表 (proplist) 要傳遞給 erlydtl 的模板編譯選項。說明在此
out_dir 字串 放置已編譯模板 beam 檔案的位置,預設為「ebin」。
source_ext 字串 模板原始檔的副檔名,預設為「.dtl」。
module_ext 字串 附加到模板模組名稱的字元,預設為「_dtl」。
recursive 布林值 決定是否需要遞迴掃描 doc_root(s) 以查找匹配模板檔案名稱的布林值。預設為「true」。

Neotoma

使用 Sean Cribbs neotoma 應用程式 建置 PEG 檔案的插件。此插件已發佈到 Hex,因此可以使用以下指令將其添加到您的專案中

{plugins, [rebar3_neotoma_plugin]}.

compile 函式位於 neotoma 命名空間下。要在 Erlang 編譯器之前自動執行,請將 pre_hook 添加到 rebar.config

{provider_hooks, [
    {pre, [{compile, {neotoma, compile}}]}
]}.

Protocol Buffers

使用 gpb

使用 Tomas Abrahamsson 的 gpb 建置 .proto 檔案的插件。此插件已發佈到 Hex,因此可以使用以下指令將其添加到您的專案中

{erl_opts, [{i, "./_build/default/plugins/gpb/include/"}]}.
{plugins, [{rebar3_gpb_plugin, "2.10.0"}]}.

{gpb_opts, [{i, "proto"},
        {o_erl, "src"},
        {o_hrl, "include"}]}.

compile 函式位於 protobuf 命名空間下。要在 Erlang 編譯器之前自動建置,請將提供者 pre 鉤子添加到 rebar.config

{provider_hooks, [
    {pre, [{compile, {protobuf, compile}}]}
]}.

完整的文檔可在插件的 README 中找到。

Appup

用於生成、編譯和驗證 .appup.src 檔案的插件。此插件已發佈到 Hex,因此可以使用以下指令將其添加到您的專案中

{plugins, [rebar3_appup_plugin]}.

compileclean 函式位於 appup 命名空間下。要在 Erlang 編譯器之前自動建置,請將提供者 pre 鉤子添加到 rebar.config

{provider_hooks, [
    {post, [{compile, {appup, compile}},
            {clean, {appup, clean}}]}
]}.

要比較兩個版本並生成帶有執行版本升級所需指令的 .appup,請執行

git checkout <from version>
rebar3 release
git checkout <to version>
rebar3 release
rebar3 appup generate
rebar3 relup tar
參數 類型 說明
previous 可選 要比較的先前版本的路徑位置
current 可選 要比較的當前版本的路徑位置,預設為 _build/<profile>/rel/<app_name>
target_dir 可選 生成 .appup 檔案的位置。
previous_version 可選 要更新的版本

完整的文檔可在插件的 README 中找到。

供應商相依性

本節包含用於在專案中儲存供應商依賴項的插件。

從 Rebar3 3.7.0 開始,您可以使用 rebar3_path_deps 作為插件,指定用於依賴項檢索的相對供應商路徑。即使插件用於依賴項,本地路徑也應該有效。

讓我們先在您的專案 hello_world 中建立一個新的 OTP 應用程式 hello_utils

# inside of hello-world/
$ rebar3 new app hello_utils

這將建立一個名為 hello_utils 的新資料夾,其中包含可供使用的 rebar.configsrc 資料夾。

為了讓 Rebar3 知道這一點,請打開 hello_world/rebar.config 並將 hello_utils 添加到您的依賴項中

{deps, [
  {hello_utils, {path, "hello_utils"}},
  ...
]

這告訴 Rebar3 我們依賴於一個名為 hello_utils 的應用程式,該應用程式位於 hello_utils 目錄中(相對於它所寫入的 rebar.config 檔案)。

然後將插件添加到您的 rebar.config

{plugins, [
   rebar3_path_deps
]}.

然後編譯您的應用程式

$ rebar3 compile
===> Compiling rebar3_path_deps
===> Verifying dependencies...
===> Fetching hello_utils ({path,"hello_utils",
                            {mtime,<<"2018-10-17T11:21:18Z">>}})
===> Compiling hello_utils
===> Compiling hello_world

這樣就涵蓋了所有內容。

對於 3.7.0 之前的版本,以下插件更佳,但僅適用於專案的頂層。

{plugins, [rebar3_vendor]}.

要將提取的依賴項儲存在 ./deps/ 下以進行提交

rebar3 vendor store

要從 ./deps/ 中取出供應商依賴項並將它們放在建置目錄中的適當位置

rebar3 vendor apply

SVN 相依性

rebar3_svn_deps 插件允許使用 SVN 儲存庫作為依賴項

由於 SVN 在分支和層次結構方面遵循與 Git 或 Hg 依賴項不同的方法,因此請按照插件說明使用它。

Elixir 相依性

從 Rebar3 3.7.0 開始,rebar_mix 插件支援 Mix 依賴項。README 頁面中詳細說明了要求和說明,其中包括協定合併等功能。

將插件添加到您的 rebar 配置中

{plugins, [rebar_mix]}.

{provider_hooks, [{post, [{compile, {mix, consolidate_protocols}}]}]}.

consolidate_protocols 鉤子將 beam 放置在 _build/<profile>/consolidated 中,建置版本時需要將其包含在版本中。使用

{overlay, [{copy, "{{base_dir}}/consolidated", "releases/{{release_version}}/consolidated"}]}

並更新您的 vm.args.src 以包含

-pa releases/${REL_VSN}/consolidated

🚧

使用舊版 Rebar3 的 Elixir

對於 3.7.0 之前的 Rebar3 版本,rebar3_elixir_compile 插件是首選,儘管它需要手動將所有傳遞依賴項提升到專案根目錄。插件的 README 頁面 上提供了完整的範例和配置說明。