插件
插件可以安裝在本地、專案或全域。若要安裝本地插件,請在專案的 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 release
或 rebar3 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 索引。再次強調,由於插件沒有作為鎖定檔案的一部分鎖定,因此始終為它們指定版本可能是一個好主意。
推薦的插件
- 自動編譯和載入
- 自動測試
- Hex 套件管理
- Port 編譯器
- 執行發行版本
- 別名
- QuickCheck
- PropEr
- Diameter
- ErlyDTL
- Neotoma
- Protocol Buffers
- Appup
- 供應商相依性
- Elixir 相依性
自動編譯和載入
對於 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
中呼叫它以進行 compile
和 clean
{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
。可以在GitHub和hex.pm找到。
{plugins, [rebar3_run]}.
別名
從 3.5.0 版開始,Rebar3 中已新增 alias 插件。請參閱 </docs/workflow/#create-aliases-for-common-tasks> 以取得說明。
對於先前版本,用於將單個指令別名以執行多個任務的插件可以在GitHub和Hex.pm找到。
{plugins, [rebar_alias]}.
{alias, [{check, [eunit, {ct, "--sys_config=config/app.config"}]}]}.
可以透過將 Provider
替換為 {Provider, Args}
來傳遞參數(與命令列一樣)。
QuickCheck
一個 Rebar3 插件,可以執行 Erlang QuickCheck 屬性。可以在 GitHub 和 Hex.pm 找到。
{plugins, [rebar3_eqc]}.
QuickCheck 的設定選項位於 eqc_opts
下,例如 {eqc_opts, [{numtests, 500}]}.
設定選項 | 類型 | 說明 |
---|---|---|
numtests | 整數 | 測試執行次數,預設為 100。 |
testing_time | 整數 | 執行屬性的時間(以秒為單位)。如果同時指定了兩者,則忽略 testing_time 設定。 |
同樣地,可以在命令列上传递設定
選項 | 類型 | 說明 |
---|---|---|
-n | 整數 | 測試執行次數,預設為 100。 |
-t | 整數 | 執行屬性的時間(以秒為單位)。如果同時指定了兩者,則忽略 testing_time 設定。 |
-p | 字串 | 要執行的屬性。可以是 module:property 或 property ,插件將會決定模組。 |
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.config
的 erlydtl_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]}.
compile
和 clean
函式位於 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.config
和 src
資料夾。
為了讓 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 頁面 上提供了完整的範例和配置說明。