非常教程

Erlang 20参考手册

透析器 | dialyzer

透析器 | dialyzer

模块

透析器

模块摘要

透析器,用于ERlang程序的DIscrepancy AnaLYZer。

描述

Dialyzer是一款静态分析工具,用于识别单个Erlang模块或整个(一套)应用程序中的软件差异,例如明确的类型错误,因编程错误而死机或无法访问的代码以及不必要的测试。

Dialyzer从调试编译的BEAM字节码或Erlang源代码开始分析。报告差异的文件和行号以及差异是关于什么的指示。Dialyzer基于成功典型的概念进行分析,这种概念允许发出合理的警告(没有误报)。

使用指挥线的透析器

Dialyzer有一个用于自动化使用的命令行版本。本节提供了有关选项的简要说明。通过在shell中写入以下内容可以获得相同的信息:

dialyzer --help

有关Dialyzer操作的更多详细信息,请参见Using Dialyzer from the GUI用户指南中的一节。

命令行版本的退出状态:

0

分析过程中没有发现任何问题,也没有发出警告。

1

在分析过程中发现了一些问题。

2

在分析过程中没有发现任何问题,但是发出了警告。

用法:

dialyzer [--add_to_plt] [--apps applications] [--build_plt]
         [--check_plt] [-Ddefine]* [-Dname] [--dump_callgraph file]
         [files_or_dirs] [--fullpath] [--get_warnings] [--gui] [--help]
         [-I include_dir]* [--no_check_plt] [--no_native]
         [--no_native_cache] [-o outfile] [--output_plt file] [-pa dir]*
         [--plt plt] [--plt_info] [--plts plt*] [--quiet] [-r dirs]
         [--raw] [--remove_from_plt] [--shell] [--src] [--statistics]
         [--verbose] [--version] [-Wwarn]*

*表示该选项可能出现多次。

备选方案:

--add_to_plt

PLT扩展到还包括用-cand 指定的文件-r。使用--plt指定从哪个开始PLT,并--output_plt指定到哪里可以把PLT。注意,如果分析依赖于新文件,分析可能会包含来自PLT的文件。该选项仅适用于BEAM文件。

--apps applications

建立或修改PLT时通常使用此选项,如下所示:

dialyzer --build_plt --apps erts kernel stdlib mnesia ...

方便地参考与Erlang/OTP安装相对应的库应用程序。但是,此选项是通用的,在分析期间也可以用于参考Erlang/OTP应用程序。还可以包括文件或目录名,如:

dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam

--build_plt

分析从一个空的PLT开始,并使用-c和指定的文件创建一个新的PLT -r。该选项仅适用于BEAM文件。要覆盖默认的PLT位置,请使用--plt--output_plt

--check_plt

检查PLT的一致性,如果它不是最新的,则重建。

-Dname (或 -Dname=value**)**

从源代码分析时,将定义传递给Dialyzer。(**)

--dump_callgraph file

将调用图转储到格式由文件扩展名确定的指定文件中。支持扩展是:rawdot,和ps。如果使用其他文件作为文件扩展名,.raw则使用默认格式。

files_or_dirs (为了向后兼容 -c files_or_dirs** 也是**)**

根据分析的类型,使用命令行中的Dialyzer检测指定文件或包含.erl.beam文件的目录中的缺陷。

--fullpath

显示发出警告的文件的完整路径名称。

--get_warnings

即使操作PLT,透析器也会发出警告。警告仅针对分析的文件发出。

--gui

使用GUI。

--help (或 -h**)**

打印这条消息并退出。

-I include_dir

从源代码分析时,将其传递include_dir给Dialyzer。(**)

--no_check_plt

运行透析器时跳过PLT检查。在使用从未改变的已安装的PLT时,这非常有用。

--no_native (或 -nn**)**

在透析多个文件时绕过Dialyzer启发式执行的一些关键文件的本机代码编译。这样可以避免编译时间,但会导致(很多)更长的分析时间。

--no_native_cache

默认情况下,Dialyzer将本机编译的结果缓存到目录中$XDG_CACHE_HOME/erlang/dialyzer_hipe_cacheXDG_CACHE_HOME默认为$HOME/.cache。使用此选项可禁用缓存。

-o outfile (或 --output outfile**)**

从命令行使用Dialyzer时,将分析结果发送到指定的outfile而不是to stdout

--output_plt file

编译后将PLT存储在指定的文件中。

-pa dir

包含dir在Erlang的路径中。分析具有-include_lib()指令的文件时,这非常有用。

--plt plt

使用指定的PLT作为初始PLT。如果PLT是在安装过程中建立的,则会检查文件的一致性。

--plt_info

使透析器打印有关PLT的信息,然后退出。PLT可以用来指定--plt(s)

--plts plt*

合并指定的PLT以创建初始PLT。这要求PLT不相交(也就是说,没有任何模块出现在多个PLT中)。PLT以通常的方式创建:

dialyzer --build_plt --output_plt plt_1 files_to_include
...
dialyzer --build_plt --output_plt plt_n files_to_include

然后,它们可以以下列任何一种方式使用:

dialyzer files_to_analyze --plts plt_1 ... plt_n

dialyzer --plts plt_1 ... plt_n -- files_to_analyze

注意--第二种情况下的分隔符。

--quiet (或 -q**)**

让透析器安静一点。

-r dirs

files_or_dirs相同,但根据分析类型递归搜索包含子目录.erl或其中的.beam文件的指定目录。

--raw

从命令行使用Dialyzer时,输出原始分析结果(Erlang术语)而不是格式化结果。原始格式更容易后处理(例如,过滤警告或输出HTML页面)。

--remove_from_plt

从指定的文件中的信息-c-r从PLT删除。请注意,这可能导致对其余依赖文件的重新分析。

--shell

在运行GUI时,不要禁用Erlangshell。

--src

覆盖默认值,即分析BEAM文件,然后从Erlang源代码开始分析。

--statistics

打印有关执行进度的信息(分析阶段,花在每个阶段的时间和相关输入的大小)。

--verbose

让透析器更详细一点。

--version (或 -v**)**

打印透析器版本和更多信息并退出。

-Wwarn

一系列有选择地开启/关闭警告的选项。(有关警告名称的帮助,请使用dialyzer -Whelp。)请注意,也可以在具有-dialyzer()属性的文件中指定选项。有关详情,请参阅部分Requesting or Suppressing Warnings in Source Files

**选项-D并且-I可以在命令行和Dialyzer GUI中使用; 定义和包含的语法与所使用的相同erlc(1)

警告选项:

-Werror_handling(***)

包含仅由异常返回的函数的警告。

-Wno_behaviours

禁止有关行为回调的警告,这些回调从已发布的推荐接口中漂移。

-Wno_contracts

禁止有关无效合同的警告。

-Wno_fail_call

禁止对失败调用的警告。

-Wno_fun_app

禁止对可能失败的有趣应用程序发出警告。

-Wno_improper_lists

禁止构造不正确列表的警告。

-Wno_match

禁止对未使用或无法匹配的模式发出警告。

-Wno_missing_calls

禁止有关调用缺失函数的警告。

-Wno_opaque

禁止违反数据类型不透明度的警告。

-Wno_return

禁止对永远不会返回值的函数发出警告。

-Wno_undefined_callbacks

禁止对没有警告的行为发出警告。-callback它们回调的属性。

-Wno_unused

禁止未使用函数的警告。

-Wrace_conditions%28%2A%2A%2A%29

包括可能的竞赛条件的警告。请注意,发现数据竞争的分析执行过程内数据流分析,有时可能会在时间上爆炸。让它由你自己承担。

-Wunderspecs%28%2A%2A%2A%29

关于未指定函数%28的警告规范比成功键入%29更允许。

-Wunknown%28%2A%2A%2A%29

让有关未知函数和类型的警告影响命令行版本的退出状态。默认情况是在设置退出状态时忽略有关未知函数和类型的警告。当使用Erlang的Dialyzer时,将返回有关未知函数和类型的警告;默认情况是不返回这些警告。

-Wunmatched_returns%28%2A%2A%2A%29

包括对忽略结构化返回值或与许多可能的返回值%28s%29中的一个不匹配的函数调用的警告。

以下选项也可用,但不推荐使用它们(主要是供透析器开发人员使用和内部调试%29使用):

-Woverspecs%28%2A%2A%2A%29

警告指定过高的功能%28规范比成功键入%29更不允许。

-Wspecdiffs%28%2A%2A%2A%29

当规范与成功键入不同时发出警告。

%2A%2A%2A表示打开警告而不是关闭警告的选项。

使用Erlang公司的透析器

透析器可直接从二郎使用。GUI和命令行版本都是可用的。这些选项类似于命令行中给出的选项,请参见Using Dialyzer from the Command Line...

请求或抑制源文件中的警告

属性-dialyzer()可以通过指定函数或警告选项来关闭模块中的警告。例如,关闭函数的所有警告f/0,包括以下一行:

-dialyzer({nowarn_function, f/0}).

若要关闭对不正确列表的警告,请将以下行添加到源文件中:

-dialyzer(no_improper_lists).

属性-dialyzer()在函数声明之后允许。允许列出警告选项或函数:

-dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).

警告选项可以仅限于函数:

-dialyzer({no_improper_lists, g/0}).
-dialyzer({[no_return, no_match], [g/0, h/0]}).

有关警告选项的帮助,请使用dialyzer -Whelp.这些选项也被枚举,请参见函数gui/1低于%28WarnOpts29%。

警告选项-Wrace_conditions在源文件中设置时没有任何效果。

属性-dialyzer()也可用于打开警告。例如,如果一个模块已经修复了不匹配的返回,那么添加以下行可以帮助确保不引入新的不匹配的返回警告:

-dialyzer(unmatched_returns).

出口

format_warning(Msg) -> string()

类型

run/1...

从由run/1...

gui() -> ok | {error, Msg}gui(OptList) -> ok | {error, Msg}

类型

见下文。

透析器GUI版本。

OptList  :: [Option]
Option   :: {files,          [Filename :: string()]}
          | {files_rec,      [DirName :: string()]}
          | {defines,        [{Macro :: atom(), Value :: term()}]}
          | {from,           src_code | byte_code}
                               %% Defaults to byte_code
          | {init_plt,       FileName :: string()}
                               %% If changed from default
          | {plts,           [FileName :: string()]}
                               %% If changed from default
          | {include_dirs,   [DirName :: string()]}
          | {output_file,    FileName :: string()}
          | {output_plt,     FileName :: string()}
          | {check_plt,      boolean()},
          | {analysis_type,  'succ_typings' |
                             'plt_add' |
                             'plt_build' |
                             'plt_check' |
                             'plt_remove'}
          | {warnings,       [WarnOpts]}
          | {get_warnings,   bool()}

WarnOpts :: error_handling
          | no_behaviours
          | no_contracts
          | no_fail_call
          | no_fun_app
          | no_improper_lists
          | no_match
	  | no_missing_calls
          | no_opaque
	  | no_return
          | no_undefined_callbacks
          | no_unused
          | race_conditions
          | underspecs
          | unknown
          | unmatched_returns
          | overspecs
          | specdiffs

plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}

返回有关指定PLT的信息。

run(OptList) -> Warnings

类型

gui/0,1...

见下文。

透析器命令行版本。

Warnings :: [{Tag, Id, Msg}]
Tag      :: 'warn_behaviour'
          | 'warn_bin_construction'
          | 'warn_callgraph'
          | 'warn_contract_not_equal'
          | 'warn_contract_range'
          | 'warn_contract_subtype'
          | 'warn_contract_supertype'
          | 'warn_contract_syntax'
          | 'warn_contract_types'
          | 'warn_failing_call'
          | 'warn_fun_app'
          | 'warn_matching'
          | 'warn_non_proper_list'
          | 'warn_not_called'
          | 'warn_opaque'
          | 'warn_race_condition'
          | 'warn_return_no_exit'
          | 'warn_return_only_exit'
          | 'warn_umatched_return'
          | 'warn_undefined_callbacks'
          | 'warn_unknown'
Id  = {File :: string(), Line :: integer()}
Msg = msg() -- Undefined

透析器 | dialyzer相关

Erlang 20

Erlang 是一种通用的面向并发的编程语言,可应付大规模开发活动的程序设计语言和运行环境。

主页 https://www.erlang.org/
源码 https://github.com/erlang/otp
版本 20
发布版本 20.1