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 --input_list_file file:
129 Analyze the file names that are listed in the specified file (one
130 file name per line).
131 --no_check_plt:
133 Skip the PLT check when running Dialyzer. This is useful when work‐
134 ing with installed PLTs that never change.
135 --no_indentation:
137 Do not insert line breaks in types, contracts, and Erlang Code when
138 formatting warnings.
139 -o outfile (or --output outfile):
141 When using Dialyzer from the command line, send the analysis re‐
142 sults to the specified outfile rather than to stdout.
143 --output_plt file:
145 Store the PLT at the specified file after building it.
146 -pa dir:
148 Include dir in the path for Erlang. This is useful when analyzing
149 files that have -include_lib() directives.
150 --plt plt:
152 Use the specified PLT as the initial PLT. If the PLT was built dur‐
153 ing setup, the files are checked for consistency.
154 --plt_info:
156 Make Dialyzer print information about the PLT and then quit. The
157 PLT can be specified with --plt(s).
158 --plts plt*:
160 Merge the specified PLTs to create the initial PLT. This requires
161 that the PLTs are disjoint (that is, do not have any module appear‐
162 ing in more than one PLT). The PLTs are created in the usual way:
163 dialyzer --build_plt --output_plt plt_1 files_to_include
165 dialyzer --build_plt --output_plt plt_n files_to_include
166 They can then be used in either of the following ways:
168 dialyzer files_to_analyze --plts plt_1 ... plt_n
170 or
172 dialyzer --plts plt_1 ... plt_n -- files_to_analyze
174 Notice the -- delimiter in the second case.
176 --quiet (or -q):
178 Make Dialyzer a bit more quiet.
179 -r dirs:
181 Same as files_or_dirs, but the specified directories are searched
182 recursively for subdirectories containing .erl or .beam files in
183 them, depending on the type of analysis.
184 --raw:
186 When using Dialyzer from the command line, output the raw analysis
187 results (Erlang terms) instead of the formatted result. The raw
188 format is easier to post-process (for example, to filter warnings
189 or to output HTML pages).
190 --remove_from_plt:
192 The information from the files specified with -c and -r is removed
193 from the PLT. Notice that this can cause a reanalysis of the re‐
194 maining dependent files.
195 --shell:
197 Do not disable the Erlang shell while running the GUI.
198 --src:
200 Override the default, which is to analyze BEAM files, and analyze
201 starting from Erlang source code instead.
202 --statistics:
204 Print information about the progress of execution (analysis phases,
205 time spent in each, and size of the relative input).
206 --verbose:
208 Make Dialyzer a bit more verbose.
209 --version (or -v):
211 Print the Dialyzer version and some more information and exit.
212 -Wwarn:
214 A family of options that selectively turn on/off warnings. (For
215 help on the names of warnings, use dialyzer -Whelp.) Notice that
216 the options can also be specified in the file with a -dialyzer()
217 attribute. For details, see section Requesting or Suppressing Warn‐
218 ings in Source Files.
219 Note:
221 ** options -D and -I work both from the command line and in the Dia‐
222 lyzer GUI; the syntax of defines and includes is the same as that used
223 by erlc(1).
224 Warning options:
227 -Werror_handling (***):
229 Include warnings for functions that only return by an exception.
230 -Wextra_return (***):
232 Warn about functions whose specification includes types that the
233 function cannot return.
234 -Wmissing_return (***):
236 Warn about functions that return values that are not part of the
237 specification.
238 -Wno_behaviours:
240 Suppress warnings about behavior callbacks that drift from the pub‐
241 lished recommended interfaces.
242 -Wno_contracts:
244 Suppress warnings about invalid contracts.
245 -Wno_fail_call:
247 Suppress warnings for failing calls.
248 -Wno_fun_app:
250 Suppress warnings for fun applications that will fail.
251 -Wno_improper_lists:
253 Suppress warnings for construction of improper lists.
254 -Wno_match:
256 Suppress warnings for patterns that are unused or cannot match.
257 -Wno_missing_calls:
259 Suppress warnings about calls to missing functions.
260 -Wno_opaque:
262 Suppress warnings for violations of opacity of data types.
263 -Wno_return:
265 Suppress warnings for functions that will never return a value.
266 -Wno_undefined_callbacks:
268 Suppress warnings about behaviors that have no -callback attributes
269 for their callbacks.
270 -Wno_unused:
272 Suppress warnings for unused functions.
273 -Wunderspecs (***):
275 Warn about underspecified functions (the specification is strictly
276 more allowing than the success typing).
277 -Wunknown (***):
279 Let warnings about unknown functions and types affect the exit sta‐
280 tus of the command-line version. The default is to ignore warnings
281 about unknown functions and types when setting the exit status.
282 When using Dialyzer from Erlang, warnings about unknown functions
283 and types are returned; the default is not to return these warn‐
284 ings.
285 -Wunmatched_returns (***):
287 Include warnings for function calls that ignore a structured return
288 value or do not match against one of many possible return values.
289 However, no warnings are included if the possible return values are
290 a union of atoms or a union of numbers.
291 The following options are also available, but their use is not recom‐
293 mended (they are mostly for Dialyzer developers and internal debug‐
294 ging):
295 -Woverspecs (***):
297 Warn about overspecified functions (the specification is strictly
298 less allowing than the success typing).
299 -Wspecdiffs (***):
301 Warn when the specification is different than the success typing.
302 Note:
304 *** denotes options that turn on warnings rather than turning them off.
305 The following option is not strictly needed as it specifies the de‐
308 fault. It is primarily intended to be used with the -dialyzer attri‐
309 bute. For an example see section Requesting or Suppressing Warnings in
310 Source Files.
311 -Wno_underspecs:
313 Suppress warnings about underspecified functions (the specification
314 is strictly more allowing than the success typing).
315 -Wno_extra_return:
317 Suppress warnings about functions whose specification includes
318 types that the function cannot return.
319 -Wno_missing_return:
321 Suppress warnings about functions that return values that are not
322 part of the specification.
323
325 Dialyzer can be used directly from Erlang. Both the GUI and the com‐
326 mand-line versions are also available. The options are similar to the
327 ones given from the command line, see section Using Dialyzer from the
328 Command Line.
329
331 The (host operating system) environment variable ERL_COMPILER_OPTIONS
332 can be used to give default Dialyzer options. Its value must be a valid
333 Erlang term. If the value is a list, it is used as is. If it is not a
334 list, it is put into a list.
335 The list is appended to any options given to run/1 or on the command
337 line.
338 The list can be retrieved with compile:env_compiler_options/0.
340 Currently the only option used is the error_location option.
342
344 Attribute -dialyzer() can be used for turning off warnings in a module
345 by specifying functions or warning options. For example, to turn off
346 all warnings for the function f/0, include the following line:
347 -dialyzer({nowarn_function, f/0}).
349 To turn off warnings for improper lists, add the following line to the
351 source file:
352 -dialyzer(no_improper_lists).
354 Attribute -dialyzer() is allowed after function declarations. Lists of
356 warning options or functions are allowed:
357 -dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).
359 Warning options can be restricted to functions:
361 -dialyzer({no_improper_lists, g/0}).
363 -dialyzer({[no_return, no_match], [g/0, h/0]}).
365 The warning option for underspecified functions, -Wunderspecs, can re‐
367 sult in useful warnings, but often functions with specifications that
368 are strictly more allowing than the success typing cannot easily be
369 modified to be less allowing. To turn off the warning for underspeci‐
370 fied function f/0, include the following line:
371 -dialyzer({no_underspecs, f/0}).
373 For help on the warning options, use dialyzer -Whelp. The options are
375 also enumerated, see type warn_option().
376 Note:
378 Warning option -Wrace_conditions has no effect when set in source
379 files.
380 Attribute -dialyzer() can also be used for turning on warnings. For ex‐
383 ample, if a module has been fixed regarding unmatched returns, adding
384 the following line can help in assuring that no new unmatched return
385 warnings are introduced:
386 -dialyzer(unmatched_returns).
388
390 dial_option() =
391 {files, [FileName :: file:filename()]} |
392 {files_rec, [DirName :: file:filename()]} |
393 {defines, [{Macro :: atom(), Value :: term()}]} |
394 {from, src_code | byte_code} |
395 {init_plt, FileName :: file:filename()} |
396 {plts, [FileName :: file:filename()]} |
397 {include_dirs, [DirName :: file:filename()]} |
398 {output_file, FileName :: file:filename()} |
399 {output_plt, FileName :: file:filename()} |
400 {check_plt, boolean()} |
401 {analysis_type,
402 succ_typings | plt_add | plt_build | plt_check | plt_remove} |
403 {warnings, [warn_option()]} |
404 {get_warnings, boolean()} |
405 {error_location, error_location()}
406 Option from defaults to byte_code. Options init_plt and plts
408 change the default.
409 dial_warn_tag() =
411 warn_behaviour | warn_bin_construction | warn_callgraph |
412 warn_contract_not_equal | warn_contract_range |
413 warn_contract_subtype | warn_contract_supertype |
414 warn_contract_syntax | warn_contract_types |
415 warn_failing_call | warn_fun_app | warn_map_construction |
416 warn_matching | warn_non_proper_list | warn_not_called |
417 warn_opaque | warn_return_no_exit | warn_return_only_exit |
418 warn_undefined_callbacks | warn_unknown | warn_umatched_return
419 dial_warning() =
421 {Tag :: dial_warn_tag(),
422 Id :: file_location(),
423 Msg :: {atom(), [term()]}}
424 error_location() = column | line
426 If the value of this option is line, an integer Line is used as
428 Location in messages. If the value is column, a pair {Line, Col‐
429 umn} is used as Location. The default is column.
430 file_location() =
432 {File :: file:filename(), Location :: erl_anno:location()}
433 warn_option() =
435 error_handling | no_behaviours | no_contracts | no_fail_call |
436 no_fun_app | no_improper_lists | no_match | no_missing_calls |
437 no_opaque | no_return | no_undefined_callbacks |
438 no_underspecs | no_unused | underspecs | unknown |
439 unmatched_returns | overspecs | specdiffs | extra_return |
440 no_extra_return | missing_return | no_missing_return
441 See section Warning options for a description of the warning op‐
443 tions.
444
446 format_warning(Warnings) -> string()
447 Types:
449 Warnings = dial_warning()
451 Get a string from warnings as returned by run/1.
453 format_warning(Warnings, Options) -> string()
455 Types:
457 Warnings = dial_warning()
459 Options = filename_opt() | [format_option()]
460 format_option() =
461 {indent_opt, boolean()} |
462 {filename_opt, filename_opt()} |
463 {error_location, error_location()}
464 filename_opt() = basename | fullpath
465 Get a string from warnings as returned by run/1.
467 If indent_opt is set to true (default), line breaks are inserted
469 in types, contracts, and Erlang code to improve readability.
470 If error_location is set to column (default), locations are for‐
472 matted as Line:Column if the column number is available, other‐
473 wise locations are formatted as Line even if the column number
474 is available.
475 gui() -> ok
477 gui(Options) -> ok
479 Types:
481 Options = [dial_option()]
483 Dialyzer GUI version.
485 plt_info(Plt) -> {ok, Result} | {error, Reason}
487 Types:
489 Plt = file:filename()
491 Result = [{files, [file:filename()]}]
492 Reason = not_valid | no_such_file | read_error
493 Returns information about the specified PLT.
495 run(Options) -> Warnings
497 Types:
499 Options = [dial_option()]
501 Warnings = [dial_warning()]
502 Dialyzer command-line version.
504Ericsson AB dialyzer 5.0.5 dialyzer(3)