善待Erlang 代码 -- Xref 实践

Xref 是一个交叉引用工具，通过分析定义的函数间的调用关系，用于查找函数、 模块、 应用程序和版本之间的依赖关系。

通俗而言，Xref 可以检查代码中函数的调用关系。比如在 moduleA 中的 funA 调用了moduleB 中的funB， 但是moduleB 中并未定义funB，此错误在代码编译期间不能被发现，但是可以通过Xref 检查。

栗子

使用reabr 创建一个application ，命名为xref_test，目录结构如下：

 $ tree
 .
 ├── ebin
 │   ├── test.beam
 │   ├── xref_test.app
 │   ├── xref_test_app.beam
 │   └── xref_test_sup.beam
 ├── rebar
 ├── src
 │   ├── test.erl
 │   ├── xref_test.app.src
 │   ├── xref_test_app.erl
 │   └── xref_test_sup.erl
 └── xref.config

  directories,  files

其中 test.erl 的代码为:

 $ cat ./src/test.erl
 -module(test).
 -export([start/]).
 start() ->
     test_2:start().

在test module 中定义start/0  函数，其中调用了test_2:start/0 函数，但是此函数并没有定义。这种情况，必然会引发错误，但是在编译期间，并不能发现。

 $ ./rebar com
 ==> xref_test (compile)
 Compiled src/xref_test_app.erl
 Compiled src/test.erl
 Compiled src/xref_test_sup.erl

OK，上述执行是顺利完成的。但是在运行时，必然会发生错误。

 > test:start().
 ** exception error: undefined function test_2:start/

那么，怎样才能在运行之前发现这个错误呢？Xref 就应该隆重登场了。

rebar xref

在rebar 中，集成了xref 工具，相关的配置信息如下：

 {xref_warnings, false}.
 %% optional extra paths to include in xref:set_library_path/.
 %% specified relative location of rebar.config.
 %% e.g. {xref_extra_paths,["../gtknode/src"]}
 {xref_extra_paths,[]}.
 %% xref checks to run
 {xref_checks, [undefined_function_calls, undefined_functions,
                locals_not_used, exports_not_used,
                deprecated_function_calls, deprecated_functions]}.
 %% Optional custom xref queries (xref manual has details) specified as
 %%     {xref_queries, [{query_string(), expected_query_result()},...]}
 %% The following for example removes all references to mod:*foo/
 %% functions from undefined external function calls as those are in a
 %% generated module
 {xref_queries,
  [{"(XC - UC) || (XU - X - B"
    " - (\"mod\":\".*foo\"/\"4\"))",[]}]}.

在rebar.config 文件中，配置好这些信息，执行：

 $ ./rebar xref
 ==> xref_test (xref)
 Warning: test_2:start/ is undefined function (Xref)
 src/test.erl:: Warning: test:start/ calls undefined function test_2:start/ (Xref)
 ERROR: xref failed while processing /Users/redink/erlang/test/xref_test: rebar_abort

这个时候，错误就能够清晰的看出来了。

xref_runner

xref_runner 是独立于rebar xref 的一个工具，支持在非rebar 组织的项目中使用xref ，友好度很高。

https://github.com/inaka/xref_runner

在rebar node 组织的Erlang release 中，可以使用xref_runner 方便的对apps 目录下的application 进行xref 检查。

xrefr.config 定义：

 $ cat xrefr.config
 [
    {xref, [
             {config, #{dirs => ["./apps/appname/ebin"],
                extra_paths => [
                 "./deps/***/ebin"]}},
             {checks, [
                      undefined_functions
                      , undefined_function_calls
                      , locals_not_used
                      %%, exports_not_used
                      , deprecated_function_calls
                      , deprecated_functions
                      ]},
             {xref_default, {verbose}}
           ]
    }
 ].

总结

Xref 非常有用，能帮我们在运行之前尽快的发现代码的错误以及潜在的错误。

扩展阅读：

http://www.erlang.org/doc/apps/tools/xref_chapter.html