1dialyzer(3) Erlang Module Definition dialyzer(3)
2
6 dialyzer - Dialyzer, a DIscrepancy AnaLYZer for ERlang programs.
7
10 Dialyzer is a static analysis tool that identifies software discrepan‐
11 cies, such as definite type errors, code that has become dead or un‐
12 reachable because of programming error, and unnecessary tests, in sin‐
13 gle Erlang modules or entire (sets of) applications.
14 Dialyzer starts its analysis from either debug-compiled BEAM bytecode
16 or from Erlang source code. The file and line number of a discrepancy
17 is reported along with an indication of what the discrepancy is about.
18 Dialyzer bases its analysis on the concept of success typings, which
19 allows for sound warnings (no false positives).
20
22 Dialyzer has a command-line version for automated use. This section
23 provides a brief description of the options. The same information can
24 be obtained by writing the following in a shell:
25 dialyzer --help
27 For more details about the operation of Dialyzer, see section Using
29 Dialyzer from the GUI in the User's Guide.
30 Exit status of the command-line version:
32 0:
34 No problems were found during the analysis and no warnings were
35 emitted.
36 1:
38 Problems were found during the analysis.
39 2:
41 No problems were found during the analysis, but warnings were emit‐
42 ted.
43 Usage:
45 dialyzer [--add_to_plt] [--apps applications] [--build_plt]
47 [--check_plt] [-Ddefine]* [-Dname]* [--dump_callgraph file]
48 [--error_location flag] [files_or_dirs] [--fullpath]
49 [--get_warnings] [--gui] [--help] [-I include_dir]*
50 [--no_check_plt] [--no_indentation] [-o outfile]
51 [--output_plt file] [-pa dir]* [--plt plt] [--plt_info]
52 [--plts plt*] [--quiet] [-r dirs] [--raw] [--remove_from_plt]
53 [--shell] [--src] [--statistics] [--verbose] [--version]
54 [-Wwarn]*
55 Note:
57 * denotes that multiple occurrences of the option are possible.
58 Options of the command-line version:
61 --add_to_plt:
63 The PLT is extended to also include the files specified with -c and
64 -r. Use --plt to specify which PLT to start from, and --output_plt
65 to specify where to put the PLT. Notice that the analysis possibly
66 can include files from the PLT if they depend on the new files.
67 This option only works for BEAM files.
68 --apps applications:
70 This option is typically used when building or modifying a PLT as
71 in:
72 dialyzer --build_plt --apps erts kernel stdlib mnesia ...
74 to refer conveniently to library applications corresponding to the
76 Erlang/OTP installation. However, this option is general and can
77 also be used during analysis to refer to Erlang/OTP applications.
78 File or directory names can also be included, as in:
79 dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam
81 --build_plt:
83 The analysis starts from an empty PLT and creates a new one from
84 the files specified with -c and -r. This option only works for BEAM
85 files. To override the default PLT location, use --plt or --out‐
86 put_plt.
87 --check_plt:
89 Check the PLT for consistency and rebuild it if it is not up-to-
90 date.
91 -Dname (or -Dname=value):
93 When analyzing from source, pass the define to Dialyzer. (**)
94 --dump_callgraph file:
96 Dump the call graph into the specified file whose format is deter‐
97 mined by the filename extension. Supported extensions are: raw,
98 dot, and ps. If something else is used as filename extension, de‐
99 fault format .raw is used.
100 --error_location column | line:
102 Use a pair {Line, Column} or an integer Line to pinpoint the loca‐
103 tion of warnings. The default is to use a pair {Line, Column}. When
104 formatted, the line and the column are separated by a colon.
105 files_or_dirs (for backward compatibility also as -c files_or_dirs):
107 Use Dialyzer from the command line to detect defects in the speci‐
108 fied files or directories containing .erl or .beam files, depending
109 on the type of the analysis.
110 --fullpath:
112 Display the full path names of files for which warnings are emit‐
113 ted.
114 --get_warnings:
116 Make Dialyzer emit warnings even when manipulating the PLT. Warn‐
117 ings are only emitted for files that are analyzed.
118 --gui:
120 Use the GUI.
121 --help (or -h):
123 Print this message and exit.
124 -I include_dir:
126 When analyzing from source, pass the include_dir to Dialyzer. (**)
127 --no_check_plt:
129 Skip the PLT check when running Dialyzer. This is useful when work‐
130 ing with installed PLTs that never change.
131 --no_indentation:
133 Do not insert line breaks in types, contracts, and Erlang Code when
134 formatting warnings.
135 -o outfile (or --output outfile):
137 When using Dialyzer from the command line, send the analysis re‐
138 sults to the specified outfile rather than to stdout.
139 --output_plt file:
141 Store the PLT at the specified file after building it.
142 -pa dir:
144 Include dir in the path for Erlang. This is useful when analyzing
145 files that have -include_lib() directives.
146 --plt plt:
148 Use the specified PLT as the initial PLT. If the PLT was built dur‐
149 ing setup, the files are checked for consistency.
150 --plt_info:
152 Make Dialyzer print information about the PLT and then quit. The
153 PLT can be specified with --plt(s).
154 --plts plt*:
156 Merge the specified PLTs to create the initial PLT. This requires
157 that the PLTs are disjoint (that is, do not have any module appear‐
158 ing in more than one PLT). The PLTs are created in the usual way:
159 dialyzer --build_plt --output_plt plt_1 files_to_include
161 dialyzer --build_plt --output_plt plt_n files_to_include
162 They can then be used in either of the following ways:
164 dialyzer files_to_analyze --plts plt_1 ... plt_n
166 or
168 dialyzer --plts plt_1 ... plt_n -- files_to_analyze
170 Notice the -- delimiter in the second case.
172 --quiet (or -q):
174 Make Dialyzer a bit more quiet.
175 -r dirs:
177 Same as files_or_dirs, but the specified directories are searched
178 recursively for subdirectories containing .erl or .beam files in
179 them, depending on the type of analysis.
180 --raw:
182 When using Dialyzer from the command line, output the raw analysis
183 results (Erlang terms) instead of the formatted result. The raw
184 format is easier to post-process (for example, to filter warnings
185 or to output HTML pages).
186 --remove_from_plt:
188 The information from the files specified with -c and -r is removed
189 from the PLT. Notice that this can cause a reanalysis of the re‐
190 maining dependent files.
191 --shell:
193 Do not disable the Erlang shell while running the GUI.
194 --src:
196 Override the default, which is to analyze BEAM files, and analyze
197 starting from Erlang source code instead.
198 --statistics:
200 Print information about the progress of execution (analysis phases,
201 time spent in each, and size of the relative input).
202 --verbose:
204 Make Dialyzer a bit more verbose.
205 --version (or -v):
207 Print the Dialyzer version and some more information and exit.
208 -Wwarn:
210 A family of options that selectively turn on/off warnings. (For
211 help on the names of warnings, use dialyzer -Whelp.) Notice that
212 the options can also be specified in the file with a -dialyzer()
213 attribute. For details, see section Requesting or Suppressing Warn‐
214 ings in Source Files.
215 Note:
217 ** options -D and -I work both from the command line and in the Dia‐
218 lyzer GUI; the syntax of defines and includes is the same as that used
219 by erlc(1).
220 Warning options:
223 -Werror_handling (***):
225 Include warnings for functions that only return by an exception.
226 -Wno_behaviours:
228 Suppress warnings about behavior callbacks that drift from the pub‐
229 lished recommended interfaces.
230 -Wno_contracts:
232 Suppress warnings about invalid contracts.
233 -Wno_fail_call:
235 Suppress warnings for failing calls.
236 -Wno_fun_app:
238 Suppress warnings for fun applications that will fail.
239 -Wno_improper_lists:
241 Suppress warnings for construction of improper lists.
242 -Wno_match:
244 Suppress warnings for patterns that are unused or cannot match.
245 -Wno_missing_calls:
247 Suppress warnings about calls to missing functions.
248 -Wno_opaque:
250 Suppress warnings for violations of opacity of data types.
251 -Wno_return:
253 Suppress warnings for functions that will never return a value.
254 -Wno_undefined_callbacks:
256 Suppress warnings about behaviors that have no -callback attributes
257 for their callbacks.
258 -Wno_unused:
260 Suppress warnings for unused functions.
261 -Wrace_conditions (***):
263 Include warnings for possible race conditions. Notice that the
264 analysis that finds data races performs intra-procedural data flow
265 analysis and can sometimes explode in time. Enable it at your own
266 risk.
267 -Wunderspecs (***):
269 Warn about underspecified functions (the specification is strictly
270 more allowing than the success typing).
271 -Wunknown (***):
273 Let warnings about unknown functions and types affect the exit sta‐
274 tus of the command-line version. The default is to ignore warnings
275 about unknown functions and types when setting the exit status.
276 When using Dialyzer from Erlang, warnings about unknown functions
277 and types are returned; the default is not to return these warn‐
278 ings.
279 -Wunmatched_returns (***):
281 Include warnings for function calls that ignore a structured return
282 value or do not match against one of many possible return values.
283 However, no warnings are included if the possible return values are
284 a union of atoms or a union of numbers.
285 The following options are also available, but their use is not recom‐
287 mended (they are mostly for Dialyzer developers and internal debug‐
288 ging):
289 -Woverspecs (***):
291 Warn about overspecified functions (the specification is strictly
292 less allowing than the success typing).
293 -Wspecdiffs (***):
295 Warn when the specification is different than the success typing.
296 Note:
298 *** denotes options that turn on warnings rather than turning them off.
299 The following option is not strictly needed as it specifies the de‐
302 fault. It is primarily intended to be used with the -dialyzer attri‐
303 bute. For an example see section Requesting or Suppressing Warnings in
304 Source Files.
305 -Wno_underspecs:
307 Suppress warnings about underspecified functions (the specification
308 is strictly more allowing than the success typing).
309
311 Dialyzer can be used directly from Erlang. Both the GUI and the com‐
312 mand-line versions are also available. The options are similar to the
313 ones given from the command line, see section Using Dialyzer from the
314 Command Line.
315
317 The (host operating system) environment variable ERL_COMPILER_OPTIONS
318 can be used to give default Dialyzer options. Its value must be a valid
319 Erlang term. If the value is a list, it is used as is. If it is not a
320 list, it is put into a list.
321 The list is appended to any options given to run/1 or on the command
323 line.
324 The list can be retrieved with compile:env_compiler_options/0.
326 Currently the only option used is the error_location option.
328
330 Attribute -dialyzer() can be used for turning off warnings in a module
331 by specifying functions or warning options. For example, to turn off
332 all warnings for the function f/0, include the following line:
333 -dialyzer({nowarn_function, f/0}).
335 To turn off warnings for improper lists, add the following line to the
337 source file:
338 -dialyzer(no_improper_lists).
340 Attribute -dialyzer() is allowed after function declarations. Lists of
342 warning options or functions are allowed:
343 -dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).
345 Warning options can be restricted to functions:
347 -dialyzer({no_improper_lists, g/0}).
349 -dialyzer({[no_return, no_match], [g/0, h/0]}).
351 The warning option for underspecified functions, -Wunderspecs, can re‐
353 sult in useful warnings, but often functions with specifications that
354 are strictly more allowing than the success typing cannot easily be
355 modified to be less allowing. To turn off the warning for underspeci‐
356 fied function f/0, include the following line:
357 -dialyzer({no_underspecs, f/0}).
359 For help on the warning options, use dialyzer -Whelp. The options are
361 also enumerated, see type warn_option().
362 Note:
364 Warning option -Wrace_conditions has no effect when set in source
365 files.
366 Attribute -dialyzer() can also be used for turning on warnings. For ex‐
369 ample, if a module has been fixed regarding unmatched returns, adding
370 the following line can help in assuring that no new unmatched return
371 warnings are introduced:
372 -dialyzer(unmatched_returns).
374
376 dial_option() =
377 {files, [FileName :: file:filename()]} |
378 {files_rec, [DirName :: file:filename()]} |
379 {defines, [{Macro :: atom(), Value :: term()}]} |
380 {from, src_code | byte_code} |
381 {init_plt, FileName :: file:filename()} |
382 {plts, [FileName :: file:filename()]} |
383 {include_dirs, [DirName :: file:filename()]} |
384 {output_file, FileName :: file:filename()} |
385 {output_plt, FileName :: file:filename()} |
386 {check_plt, boolean()} |
387 {analysis_type,
388 succ_typings | plt_add | plt_build | plt_check | plt_remove} |
389 {warnings, [warn_option()]} |
390 {get_warnings, boolean()} |
391 {error_location, error_location()}
392 Option from defaults to byte_code. Options init_plt and plts
394 change the default.
395 dial_warn_tag() =
397 warn_behaviour | warn_bin_construction | warn_callgraph |
398 warn_contract_not_equal | warn_contract_range |
399 warn_contract_subtype | warn_contract_supertype |
400 warn_contract_syntax | warn_contract_types |
401 warn_failing_call | warn_fun_app | warn_map_construction |
402 warn_matching | warn_non_proper_list | warn_not_called |
403 warn_opaque | warn_race_condition | warn_return_no_exit |
404 warn_return_only_exit | warn_undefined_callbacks |
405 warn_unknown | warn_umatched_return
406 dial_warning() =
408 {Tag :: dial_warn_tag(),
409 Id :: file_location(),
410 Msg :: {atom(), [term()]}}
411 error_location() = column | line
413 If the value of this option is line, an integer Line is used as
415 Location in messages. If the value is column, a pair {Line, Col‐
416 umn} is used as Location. The default is column.
417 file_location() =
419 {File :: file:filename(), Location :: erl_anno:location()}
420 warn_option() =
422 error_handling | no_behaviours | no_contracts | no_fail_call |
423 no_fun_app | no_improper_lists | no_match | no_missing_calls |
424 no_opaque | no_return | no_undefined_callbacks |
425 no_underspecs | no_unused | race_conditions | underspecs |
426 unknown | unmatched_returns | overspecs | specdiffs
427 See section Warning options for a description of the warning op‐
429 tions.
430
432 format_warning(Warnings) -> string()
433 Types:
435 Warnings = dial_warning()
437 Get a string from warnings as returned by run/1.
439 format_warning(Warnings, Options) -> string()
441 Types:
443 Warnings = dial_warning()
445 Options = filename_opt() | [format_option()]
446 format_option() =
447 {indent_opt, boolean()} |
448 {filename_opt, filename_opt()} |
449 {error_location, error_location()}
450 filename_opt() = basename | fullpath
451 Get a string from warnings as returned by run/1.
453 If indent_opt is set to true (default), line breaks are inserted
455 in types, contracts, and Erlang code to improve readability.
456 If error_location is set to column (default), locations are for‐
458 matted as Line:Column if the column number is available, other‐
459 wise locations are formatted as Line even if the column number
460 is available.
461 gui() -> ok
463 gui(Options) -> ok
465 Types:
467 Options = [dial_option()]
469 Dialyzer GUI version.
471 plt_info(Plt) -> {ok, Result} | {error, Reason}
473 Types:
475 Plt = file:filename()
477 Result = [{files, [file:filename()]}]
478 Reason = not_valid | no_such_file | read_error
479 Returns information about the specified PLT.
481 run(Options) -> Warnings
483 Types:
485 Options = [dial_option()]
487 Warnings = [dial_warning()]
488 Dialyzer command-line version.
490Ericsson AB dialyzer 4.4.2 dialyzer(3)