插件

插件可以安装在本地、项目中和/或全局。要本地安装插件,请在项目 `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 索引。再次强调,由于插件没有作为锁定文件的一部分被锁定,因此最好始终为它们指定版本。

自动编译和加载

对于 `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`。可以在 GitHubhex.pm 找到。

{plugins, [rebar3_run]}.

别名

从 3.5.0 版开始,别名插件已添加到 Rebar3 中。请参阅 </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: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.configerlydtl_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]}.

compileclean 函数位于 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.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 页面 中提供。