Rebar2.x到Rebar3的迁移

此文翻译自rebar3官方文档。原文链接：https://rebar3.org/docs/tutorials/from_rebar2_to_rebar3

相较于rebar2.x，rebar3改变了很多内容。到目前为止，rebar3尝试在处理完全以Erlang编写的OTP程序时保持完全的兼容性。因此，尽管需要做好准备，但构建或者编写标准OTP应用程序的开发者几乎不会遇到不兼容的情况。

主要的改变包括但不限于将所有的工程文件移动到_build目录，以及获取依赖项的方式。

完全由Erlang编写，标准的OTP应用程序

迁移的第一步是删除老的构件目录：

• 删除 ebin/ 目录。 rebar3会读取并拷贝ebin/目录到自己的_build/子目录，因此其他工具所产生的.app和.beam文件仍然可用。如果你使用rebar2.x,用来放置工程构件的ebin/目录会与rebar3冲突。
• 如果你使用relx的话，移除_rel/目录。relx已经集成到rebar3中，其所属的工程构件会放到_build目录。
• 移除.rebar目录，这个目录将不会再被使用。
• 移除deps/目录，所有依赖都会放到_build目录，移除这个目录以防止冲突。
• 在.gitignore，.hgignore文件中移除以上所有文件的条目，可做可不做，影响不大。

清除这些目录以后，rebar.config文件也可以去掉一部分内容：

• 移除sub_dirs和lib_dirs条目，用不到了；rebar3会自动识别包含Erlang源文件和OTP程序的src/，app/*，lib/*目录。

你还要检查.app.src文件，确保以下几条原则：

• 所依赖的应用程序都在applications这个tuple中罗列出来
• 没有循环依赖
• 以下这几个字段都要有（针对release版本）：description，vsn，registered，applications，env

必需的目录结构

rebar3只显式处理release版本和OTP程序。所有依赖项只能是OTP应用程序，每个依赖对应一个条目。
确保你有以下目录结构：

src/*.{erl,app.src}

单目录，单个app结构。这种结构适用于带有单个顶级应用的OTP应用程序、OTP release版本和escripts。src目录会被递归地搜索，所有文件都会被处理，就好像它们都在最外的同一层目录一样。

还有一种方式，伞状的结构：

apps/app1/src/*.{erl,app.src}
apps/app2/src/*.{erl,app.src}
apps/app3/src/*.{erl,app.src}

或者

lib/app1/src/*.{erl,app.src}
lib/app2/src/*.{erl,app.src}
lib/app3/src/*.{erl,app.src}

这种格式将一次容纳许多OTP应用程序，并且仅适用于release版本和escript，而不能用作依赖项的OTP库。

处理依赖

rebar3支持Hex包和配置。所以，可以考虑：

• 把依赖项移动到packages，详见Dependencies和Publishing Packages
• meck，PropEr等依赖项，移动到test配置以脱离常规构建。很遗憾，很可能依赖项中还包含所以它们可能会残留在你的默认构建中。
• 不用再告诉rebar3去获取依赖，每次编译或者测试的时候，rebar3会去自动获取。

还要注意，如果依赖项已经编译好了，rebar3不会再重新编译它们；如果你每次编译都想重新编译依赖项可以使用_chekout依赖项。
rebar3也不会再检查或者强制依赖的版本，而是在发生冲突的时候使用“最接近root”的算法去选择版本，详情请见Dependencies。
这样说来，如果你的项目已经ready，文档中所有的rebar3指南都易于理解，方便使用。

其他的一些坑还有别的编译器

rebar3默认使用支持erlc的编译器：erlang，yecc，MIBs等等。
如果你用的是以下几种：

• C语言的代码，需要把东西移动到Makefiles，或者使用端口编译器插件（为了向后兼容rebar2.x）
• 如果使用了quickcheck或者proper，请使用插件
• diameter有自己的插件
• erlydtl有自己的插件
• 你将无法通过奇怪的构建工具交互来构建某些库，特别是edown和类似的库。 如果出现这些问题，请转到IRC上的#rebar频道，让社区成员为你提供最简单的解决方法。
• 不再支持reltool版本，而是使用Relx，文档在这

其他

• 如果你仍然使用makefiles创建短命令，请考虑使用别名
• 对于代码覆盖率，您将需要使用cover命令，如rebar3 do eunit, cover中一样。 有关更多详细信息，请参见cover文档。

使用Hex包时维持向后的兼容性

如果是大多数情况使用rebar3但是又想提供rebar2的兼容性，请在rebar.config.script中增加如下类似的内容，这些内容会使比较旧的rebar版本放弃Hex的包，并包含作为rebar3中的一些配置：

case erlang:function_exported(rebar3, main, 1) of
    true -> % rebar3
        CONFIG;
    false -> % rebar 2.x or older
        %% Rebuild deps, possibly including those that have been moved to
        %% profiles
        [{deps, [
            {my_dep, "VSN", {git, "https://...", {tag, "VSN"}}},
            ...
        ]} | lists:keydelete(deps, 1, CONFIG)]
end.