命令

每个 Rebar3 命令的用法。

每个命令代表一个任务，该任务运行一个或多个提供程序来完成该任务。

alias

列出别名定义（来自 rebar.config）。

示例输出

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

as

高阶任务，它接受一个配置文件名称和要在该配置文件下运行的任务列表。

compile

在确保所有依赖项都可用并获取它们（如果它们不存在）之后，compile 将编译所需的依赖项以及项目的应用程序的 .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 原子 指定完成文件的类型。默认情况下，它使用 $SHELL 变量自动检测。有效值为 bash 和 zsh。

🚧

zsh 特定要求

确保在 .zshrc 文件中调用了 autoload -Uz compinit; compinit。

为了获得更好的用户体验，请设置默认自动完成并在需要时覆盖它。可以通过生成全局完成文件并在 .bashrc 或 .zshrc 中加载它来设置默认自动完成。

要生成全局（独立于项目）完成文件，请在 rebar3 项目外部运行 rebar3 completion --file path/to/global/completion/file。

clean

删除应用程序中编译的 BEAM 文件。

clean 命令默认情况下会删除顶级应用程序的 BEAM 文件。它在尊重配置文件的同时这样做，这意味着“rebar3 clean”只会清理默认配置文件，“rebar3 as test clean”只会清理测试配置文件。

选项 类型 描述
--all/-a 无 清理所有应用程序，包括依赖项
--apps 逗号分隔的字符串列表 清理特定应用程序或依赖项列表
--profile/-p 字符串 指定配置文件（作为 rebar3 as clean 的替代方法）

ct

运行位于 test/ 目录下的项目的通用测试。

大多数通用测试选项 如 Erlang 文档中 ct_run 中所述。下面描述了一些常见的选项

选项 类型 描述
--dir 逗号分隔的字符串列表 编译并运行指定目录中的所有测试套件。
--suite 逗号分隔的字符串列表 编译并运行所有指定的测试套件。必须通过完整路径指定，可以是绝对路径或相对于当前目录的相对路径。
--group 逗号分隔的字符串列表 要运行的测试组。请参阅通用测试文档。
--case 逗号分隔的字符串列表 要运行的测试用例列表。请参阅通用测试文档。
--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 逗号分隔的字符串列表 运行测试时要使用的配置文件。请参阅 [通用测试文档。](https://erlang.org.cn/doc/apps/common_test/index.html
--allow_user_terms 布尔值 允许在配置文件中使用用户定义的配置值。请参阅通用测试文档。
--decrypt_key 字符串 如果配置文件已加密，请设置解密密钥。
--decrypt_file 字符串 如果配置文件已加密，请指向包含解密密钥的文件。
--logdir 字符串 将测试日志写入的目录。请参阅通用测试文档。
默认值：_build/test/logs
--logopts 逗号分隔的字符串列表 设置通用测试日志记录选项。请参阅通用测试文档。
默认值：_build/test/logs
--readable 布尔值 在每个测试的基础上添加测试名称及其结果，并且仅在测试失败时在终端中显示通用测试日志。
默认值：true
--verbose、-v 布尔值 启用详细输出。默认值：false
--verbosity 整数 设置通用测试的详细程度级别
--cover、-c 布尔值 生成覆盖率数据
--cover_export_name 字符串 更改代码覆盖率文件的名称
--label 字符串 设置测试标签
--basic_html 布尔值 显示基本 HTML
--stylesheet 字符串 要应用于 HTML 输出的 CSS 样式表
--create_priv_dir auto_per_run | auto_per_tc | manual_per_tc 更改通用测试完成的私有（临时）目录创建的行为
--include 字符串 包含包含文件的其他目录。为与 ct_run 保持一致而添加的选项，通常 rebar3 应该处理包含文件路径
--name、--sname 字符串 启动具有给定名称的分布式节点
--setcookie 字符串 设置分布式 Cookie 的值
--compile_only 布尔值 使用指定的测试配置编译项目，但不运行测试。

在 test 配置文件中运行。

cover

对通用测试或 Eunit 测试套件调用的模块执行覆盖率分析。在 {cover_enabled, true} 选项位于您的 rebar 配置文件中时，或如果单独使用这些命令时使用了覆盖率标志，则将其作为 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 中 dialyzer 选项的 proplist 中

选项 描述
warnings dialyzer 警告列表
get_warnings 更改 PLT 文件时显示警告（布尔值）
plt_apps

 确定包含在 PLT 文件中的应用程序的策略，top_level_deps 只包含直接依赖项，或 all_deps 包含所有嵌套依赖项（直接依赖应用程序列在它们的 .app 文件的 applications 和 included_applications 中）。
plt_extra_apps 要包含在 PLT 文件中的应用程序列表（base_plt_apps 中的应用程序已在列表中）。
plt_location PLT 文件的位置，local 表示存储在配置文件的基本目录中（默认值）或自定义目录中。
plt_prefix PLT 文件的前缀，默认为“rebar3”。
base_plt_apps 要包含在基本 PLT 文件中的应用程序列表。
base_plt_location 基本 PLT 文件的位置，global 表示存储在 $HOME/.cache/rebar3 中（默认值）或自定义目录中。
base_plt_prefix 基本 PLT 文件的前缀，默认为“rebar3”。
incremental 增量分析模式。

edoc

使用 doc 生成文档。

在 docs 配置文件中运行。

escriptize

生成一个包含项目及其依赖项 BEAM 文件的 escript 可执行文件。

配置选项 类型 描述
escript_main_app 原子 要转换为 escript 的应用程序名称。如果只有一个顶级应用程序，则默认为顶级应用程序。当使用伞形存储库（具有多个顶级应用程序）时，*必须*指定此值。
escript_name 字符串 生成的 escript 的名称，以及引导的默认模块名称（Module:main(_)）。默认为 escript_main_app 的值。
escript_incl_apps 原子列表 除了主应用程序及其依赖项（来自应用程序文件）之外，还包含在 escript 存档中的应用程序列表。默认为 []。
escript_emu_args 字符串 Escript 模拟器参数（在 escript 声明中的 %%! 之后）。字符串必须以 %%! 开头并以换行符结尾。例如字符串为 "%%! +sbtu +A0\n"。默认值为 "%%! -escript main MainApp\n"。
escript_shebang 字符串 要运行的 escript 文件的位置。默认为 "#!/usr/bin/env escript\n"。字符串中必须包含换行符。
escript_comment 字符串 要放入生成的 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 不同，此命令不需要用于获取依赖项。编译命令将导致获取依赖项，然后在它们不存在时构建它们。如果您有特定用例需要单独获取依赖项（与编译分开），则此命令很有用。

获取项目依赖项。

help

显示任务列表或给定任务或子任务的帮助。

选项 描述
<task> 要打印帮助的任务。
<namespace> <task> 在 <namespace> 中要打印帮助的任务。

new

从模板创建新项目。通过不提供任何参数可以查看可用模板列表。

选项 描述
--force, -f 覆盖现有文件。
help <template> 显示每个模板的所有变量和参数。

path

打印当前配置文件中构建目录的路径。

选项 类型 描述
--app 逗号分隔的字符串列表 要返回路径的应用程序的逗号分隔列表。
--base 无 返回当前配置文件的基本路径。
--bin 无 返回当前配置文件的 bin 路径。
--ebin 无 返回当前配置文件的应用程序的所有 ebin 路径。
--lib 无 返回当前配置文件的 lib 路径。
--priv 无 返回当前配置文件的 priv 路径。
--separator, -s 字符串 如果有多个返回路径，则用于连接它们的分割符字符。
--src 无 返回当前配置文件的应用程序的 src 路径。
--rel 无 返回当前配置文件的 rel 路径。

release

构建项目的版本。调用 rebar3 help release 以获取参数。

relup

通过调用 rebar3 release（不清除 _build 目录）创建两个已构建版本的 relup。调用 rebar3 help relup 以获取参数。

report

生成要包含在错误报告中的上下文数据。

shell

运行一个 shell，其中项目应用程序和依赖项位于路径中。仅供开发使用；在生产环境中使用 版本。

选项 类型 描述
--config 字符串 允许加载 配置文件（如果有）。如果存在，则默认为为 relx 定义的 sys_config 条目。
--name、--sname 原子 在网络模式下启动节点。等效于 erl 的 -name 和 -sname 选项。
--setcookie 字符串 为分布式节点设置 cookie。等效于 erl 的 -setcookie 选项。
--script 字符串 要在启动应用程序之前计算的 escript 的路径。
--apps 字符串 要引导的应用程序名称的逗号分隔列表。如果存在，则默认为 relx 版本中的应用程序。
--start-clean 如果指定，则 shell 不会引导任何应用程序；这对于覆盖 rebar.config 中的版本或 shell 元组配置很有用。
--relname, -r 原子 如果存在多个版本，请指定要选择哪个版本。
--relvsn, -v 字符串 如果存在多个版本，请指定要使用哪个版本。
--env-file 字符串 要设置的 os 环境变量的文件路径，在扩展配置文件中的变量之前。
--user_drv_args 字符串 对于 Erlang 26 之前的版本，此选项可用于将参数传递给用于创建自定义 shell 的 user_drv 启动函数。从 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 文件的未构建依赖项。它们可能刚刚下载，但它们的构建脚本都不应运行。尽管使用预/后挂钩和依赖项插件并非总是如此。

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)