插件
插件可以安装在本地、项目中和/或全局。要本地安装插件,请在项目 `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` 提供程序,而不是内置提供程序。
此外,在某些情况下,您只需要一个插件用于开发。假设您有 protobuf 并将生成的模块提交到仓库并包含在 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 包管理
- 端口编译器
- 运行发布
- 别名
- QuickCheck
- PropEr
- Diameter
- ErlyDTL
- Neotoma
- 协议缓冲区
- 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。
端口编译器
此插件为 `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 中。请参阅 </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 | 列表 | 支持 diameter_make:codec/2 中的选项,除了 inherits 之外。 |
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 | 属性列表 | 传递给 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}}]}
]}.
协议缓冲区
使用 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 编译器之前自动构建,请将 provider
pre
钩子添加到 rebar.config
中。
{provider_hooks, [
{pre, [{compile, {protobuf, compile}}]}
]}.
完整的文档可在插件的 README 中找到。
Appup
用于生成、编译和验证 .appup.src
文件的插件。此插件已发布到 Hex,可以通过以下方式添加到您的项目中:
{plugins, [rebar3_appup_plugin]}.
compile
和 clean
函数位于 appup
命名空间下。要使其在 Erlang 编译器之前自动构建,请将 provider
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 页面 中提供。