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 errors, 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 [--incremental] [--metrics_file] [--no_check_plt] [--no_indentation]
51 [--no_spec] [-o outfile] [--output_plt file] [-pa dir]* [--plt plt]
52 [--plt_info] [--plts plt*] [--quiet] [-r dirs] [--raw]
53 [--remove_from_plt] [--shell] [--src] [--statistics] [--verbose]
54 [--version] [--warning_apps applications] [-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 By default, warnings will be reported to all applications given by
71 --apps. However, if --warning_apps is used, only those applications
72 given to --warning_apps will have warnings reported. All applica‐
73 tions given by --apps, but not --warning_apps, will be analysed to
74 provide context to the analysis, but warnings will not be reported
75 for them. For example, you may want to include libraries you depend
76 on in the analysis with --apps so discrepancies in their usage can
77 be found, but only include your own code with --warning_apps so
78 that discrepancies are only reported in code that you own.
79 --warning_apps applications:
81 This option is typically used when building or modifying a PLT as
82 in:
83 dialyzer --build_plt --apps erts kernel stdlib mnesia ...
85 to refer conveniently to library applications corresponding to the
87 Erlang/OTP installation. However, this option is general and can
88 also be used during analysis to refer to Erlang/OTP applications.
89 File or directory names can also be included, as in:
90 dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam
92 --build_plt:
94 The analysis starts from an empty PLT and creates a new one from
95 the files specified with -c and -r. This option only works for BEAM
96 files. To override the default PLT location, use --plt or --out‐
97 put_plt.
98 --check_plt:
100 Check the PLT for consistency and rebuild it if it is not up-to-
101 date.
102 -Dname (or -Dname=value):
104 When analyzing from source, pass the define to Dialyzer. (**)
105 --dump_callgraph file:
107 Dump the call graph into the specified file whose format is deter‐
108 mined by the filename extension. Supported extensions are: raw,
109 dot, and ps. If something else is used as filename extension, de‐
110 fault format .raw is used.
111 --error_location column | line:
113 Use a pair {Line, Column} or an integer Line to pinpoint the loca‐
114 tion of warnings. The default is to use a pair {Line, Column}. When
115 formatted, the line and the column are separated by a colon.
116 files_or_dirs (for backward compatibility also as -c files_or_dirs):
118 Use Dialyzer from the command line to detect defects in the speci‐
119 fied files or directories containing .erl or .beam files, depending
120 on the type of the analysis.
121 --fullpath:
123 Display the full path names of files for which warnings are emit‐
124 ted.
125 --get_warnings:
127 Make Dialyzer emit warnings even when manipulating the PLT. Warn‐
128 ings are only emitted for files that are analyzed.
129 --gui:
131 Use the GUI.
132 --help (or -h):
134 Print this message and exit.
135 -I include_dir:
137 When analyzing from source, pass the include_dir to Dialyzer. (**)
138 --input_list_file file:
140 Analyze the file names that are listed in the specified file (one
141 file name per line).
142 --no_check_plt:
144 Skip the PLT check when running Dialyzer. This is useful when work‐
145 ing with installed PLTs that never change.
146 --incremental:
148 The analysis starts from an existing incremental PLT, or builds one
149 from scratch if one does not exist, and runs the minimal amount of
150 additional analysis to report all issues in the given set of apps.
151 Notably, incremental PLT files are not compatible with "classic"
152 PLT files, and vice versa. The initial incremental PLT will be up‐
153 dated unless an alternative output incremental PLT is given.
154 --no_indentation:
156 Do not insert line breaks in types, contracts, and Erlang Code when
157 formatting warnings.
158 --no_spec:
160 Ignore functions specs. This is useful for debugging when one sus‐
161 pects that some specs are incorrect.
162 -o outfile (or --output outfile):
164 When using Dialyzer from the command line, send the analysis re‐
165 sults to the specified outfile rather than to stdout.
166 --metrics_file file:
168 Write metrics about Dialyzer's incrementality (for example, total
169 number of modules considered, how many modules were changed since
170 the PLT was last updated, how many modules needed to be analyzed)
171 to a file. This can be useful for tracking and debugging Dialyzer's
172 incrementality.
173 --output_plt file:
175 Store the PLT at the specified file after building it.
176 -pa dir:
178 Include dir in the path for Erlang. This is useful when analyzing
179 files that have -include_lib() directives.
180 --plt plt:
182 Use the specified PLT as the initial PLT. If the PLT was built dur‐
183 ing setup, the files are checked for consistency.
184 --plt_info:
186 Make Dialyzer print information about the PLT and then quit. The
187 PLT can be specified with --plt(s).
188 --plts plt*:
190 Merge the specified PLTs to create the initial PLT. This requires
191 that the PLTs are disjoint (that is, do not have any module appear‐
192 ing in more than one PLT). The PLTs are created in the usual way:
193 dialyzer --build_plt --output_plt plt_1 files_to_include
195 dialyzer --build_plt --output_plt plt_n files_to_include
196 They can then be used in either of the following ways:
198 dialyzer files_to_analyze --plts plt_1 ... plt_n
200 or
202 dialyzer --plts plt_1 ... plt_n -- files_to_analyze
204 Notice the -- delimiter in the second case.
206 --quiet (or -q):
208 Make Dialyzer a bit more quiet.
209 -r dirs:
211 Same as files_or_dirs, but the specified directories are searched
212 recursively for subdirectories containing .erl or .beam files in
213 them, depending on the type of analysis.
214 --raw:
216 When using Dialyzer from the command line, output the raw analysis
217 results (Erlang terms) instead of the formatted result. The raw
218 format is easier to post-process (for example, to filter warnings
219 or to output HTML pages).
220 --remove_from_plt:
222 The information from the files specified with -c and -r is removed
223 from the PLT. Notice that this can cause a reanalysis of the re‐
224 maining dependent files.
225 --shell:
227 Do not disable the Erlang shell while running the GUI.
228 --src:
230 Override the default, which is to analyze BEAM files, and analyze
231 starting from Erlang source code instead.
232 --statistics:
234 Print information about the progress of execution (analysis phases,
235 time spent in each, and size of the relative input).
236 --verbose:
238 Make Dialyzer a bit more verbose.
239 --version (or -v):
241 Print the Dialyzer version and some more information and exit.
242 -Wwarn:
244 A family of options that selectively turn on/off warnings. (For
245 help on the names of warnings, use dialyzer -Whelp.) Notice that
246 the options can also be specified in the file with a -dialyzer()
247 attribute. For details, see section Requesting or Suppressing Warn‐
248 ings in Source Files.
249 Note:
251 ** options -D and -I work both from the command line and in the Dia‐
252 lyzer GUI; the syntax of defines and includes is the same as that used
253 by erlc(1).
254 Warning options:
257 -Werror_handling (***):
259 Include warnings for functions that only return by an exception.
260 -Wextra_return (***):
262 Warn about functions whose specification includes types that the
263 function cannot return.
264 -Wmissing_return (***):
266 Warn about functions that return values that are not part of the
267 specification.
268 -Wno_behaviours:
270 Suppress warnings about behavior callbacks that drift from the pub‐
271 lished recommended interfaces.
272 -Wno_contracts:
274 Suppress warnings about invalid contracts.
275 -Wno_fail_call:
277 Suppress warnings for failing calls.
278 -Wno_fun_app:
280 Suppress warnings for fun applications that will fail.
281 -Wno_improper_lists:
283 Suppress warnings for construction of improper lists.
284 -Wno_match:
286 Suppress warnings for patterns that are unused or cannot match.
287 -Wno_missing_calls:
289 Suppress warnings about calls to missing functions.
290 -Wno_opaque:
292 Suppress warnings for violations of opacity of data types.
293 -Wno_return:
295 Suppress warnings for functions that will never return a value.
296 -Wno_undefined_callbacks:
298 Suppress warnings about behaviors that have no -callback attributes
299 for their callbacks.
300 -Wno_unused:
302 Suppress warnings for unused functions.
303 -Wno_unknown:
305 Suppress warnings about unknown functions and types. The default is
306 to warn about unknown functions and types when setting the exit
307 status. When using Dialyzer from Erlang, warnings about unknown
308 functions and types are returned.
309 -Wunderspecs (***):
311 Warn about underspecified functions (the specification is strictly
312 more allowing than the success typing).
313 -Wunmatched_returns (***):
315 Include warnings for function calls that ignore a structured return
316 value or do not match against one of many possible return values.
317 However, no warnings are included if the possible return values are
318 a union of atoms or a union of numbers.
319 The following options are also available, but their use is not recom‐
321 mended (they are mostly for Dialyzer developers and internal debug‐
322 ging):
323 -Woverspecs (***):
325 Warn about overspecified functions (the specification is strictly
326 less allowing than the success typing).
327 -Wspecdiffs (***):
329 Warn when the specification is different than the success typing.
330 Note:
332 *** denotes options that turn on warnings rather than turning them off.
333 The following option is not strictly needed as it specifies the de‐
336 fault. It is primarily intended to be used with the -dialyzer attri‐
337 bute. For an example see section Requesting or Suppressing Warnings in
338 Source Files.
339 -Wno_underspecs:
341 Suppress warnings about underspecified functions (the specification
342 is strictly more allowing than the success typing).
343 -Wno_extra_return:
345 Suppress warnings about functions whose specification includes
346 types that the function cannot return.
347 -Wno_missing_return:
349 Suppress warnings about functions that return values that are not
350 part of the specification.
351
353 Dialyzer can be used directly from Erlang. Both the GUI and the com‐
354 mand-line versions are also available. The options are similar to the
355 ones given from the command line, see section Using Dialyzer from the
356 Command Line.
357
359 The (host operating system) environment variable ERL_COMPILER_OPTIONS
360 can be used to give default Dialyzer options. Its value must be a valid
361 Erlang term. If the value is a list, it is used as is. If it is not a
362 list, it is put into a list.
363 The list is appended to any options given to run/1 or on the command
365 line.
366 The list can be retrieved with compile:env_compiler_options/0.
368 Currently the only option used is the error_location option.
370 Dialyzer configuration file:
372 Dialyzer's configuration file may also be used to augment the default
374 options and those given directly to the Dialyzer command. It is com‐
375 monly used to avoid repeating options which would otherwise need to be
376 given explicitly to Dialyzer on every invocation.
377 The location of the configuration file can be set via the DIALYZER_CON‐
379 FIG environment variable, and defaults to within the user_config from
380 filename:basedir/3.
381 An example configuration file's contents might be:
383 {incremental,
385 {default_apps,[stdlib,kernel,erts]},
386 {default_warning_apps,[stdlib]}
387 }.
388 {warnings, [no_improper_lists]}.
389 {add_pathsa,["/users/samwise/potatoes/ebin"]}.
390 {add_pathsz,["/users/smeagol/fish/ebin"]}.
391
394 Attribute -dialyzer() can be used for turning off warnings in a module
395 by specifying functions or warning options. For example, to turn off
396 all warnings for the function f/0, include the following line:
397 -dialyzer({nowarn_function, f/0}).
399 To turn off warnings for improper lists, add the following line to the
401 source file:
402 -dialyzer(no_improper_lists).
404 Attribute -dialyzer() is allowed after function declarations. Lists of
406 warning options or functions are allowed:
407 -dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).
409 Warning options can be restricted to functions:
411 -dialyzer({no_improper_lists, g/0}).
413 -dialyzer({[no_return, no_match], [g/0, h/0]}).
415 The warning option for underspecified functions, -Wunderspecs, can re‐
417 sult in useful warnings, but often functions with specifications that
418 are strictly more allowing than the success typing cannot easily be
419 modified to be less allowing. To turn off the warning for underspeci‐
420 fied function f/0, include the following line:
421 -dialyzer({no_underspecs, f/0}).
423 For help on the warning options, use dialyzer -Whelp. The options are
425 also enumerated, see type warn_option().
426 Attribute -dialyzer() can also be used for turning on warnings. For ex‐
428 ample, if a module has been fixed regarding unmatched returns, adding
429 the following line can help in assuring that no new unmatched return
430 warnings are introduced:
431 -dialyzer(unmatched_returns).
433
435 dial_option() =
436 {files, [FileName :: file:filename()]} |
437 {files_rec, [DirName :: file:filename()]} |
438 {defines, [{Macro :: atom(), Value :: term()}]} |
439 {from, src_code | byte_code} |
440 {init_plt, FileName :: file:filename()} |
441 {plts, [FileName :: file:filename()]} |
442 {include_dirs, [DirName :: file:filename()]} |
443 {output_file, FileName :: file:filename()} |
444 {metrics_file, FileName :: file:filename()} |
445 {module_lookup_file, FileName :: file:filename()} |
446 {output_plt, FileName :: file:filename()} |
447 {check_plt, boolean()} |
448 {analysis_type,
449 succ_typings | plt_add | plt_build | plt_check | plt_remove |
450 incremental} |
451 {warnings, [warn_option()]} |
452 {get_warnings, boolean()} |
453 {use_spec, boolean()} |
454 {filename_opt, filename_opt()} |
455 {callgraph_file, file:filename()} |
456 {mod_deps_file, file:filename()} |
457 {warning_files_rec, [DirName :: file:filename()]} |
458 {error_location, error_location()}
459 Option from defaults to byte_code. Options init_plt and plts
461 change the default.
462 dial_warn_tag() =
464 warn_behaviour | warn_bin_construction | warn_callgraph |
465 warn_contract_extra_return | warn_contract_missing_return |
466 warn_contract_not_equal | warn_contract_range |
467 warn_contract_subtype | warn_contract_supertype |
468 warn_contract_syntax | warn_contract_types |
469 warn_failing_call | warn_fun_app | warn_map_construction |
470 warn_matching | warn_non_proper_list | warn_not_called |
471 warn_opaque | warn_overlapping_contract |
472 warn_return_no_exit | warn_return_only_exit |
473 warn_undefined_callbacks | warn_unknown | warn_umatched_return
474 dial_warning() =
476 {Tag :: dial_warn_tag(),
477 Id :: file_location(),
478 Msg :: {atom(), [term()]}}
479 error_location() = column | line
481 If the value of this option is line, an integer Line is used as
483 Location in messages. If the value is column, a pair {Line, Col‐
484 umn} is used as Location. The default is column.
485 file_location() =
487 {File :: file:filename(), Location :: erl_anno:location()}
488 filename_opt() = basename | fullpath
490 format_option() =
492 {indent_opt, boolean()} |
493 {filename_opt, filename_opt()} |
494 {error_location, error_location()}
495 warn_option() =
497 error_handling | no_behaviours | no_contracts | no_fail_call |
498 no_fun_app | no_improper_lists | no_match | no_missing_calls |
499 no_opaque | no_return | no_undefined_callbacks |
500 no_underspecs | no_unknown | no_unused | underspecs |
501 unknown | unmatched_returns | overspecs | specdiffs |
502 extra_return | no_extra_return | missing_return |
503 no_missing_return
504 See section Warning options for a description of the warning op‐
506 tions.
507
509 format_warning(Warnings) -> string()
510 Types:
512 Warnings = dial_warning()
514 Get a string from warnings as returned by run/1.
516 format_warning(Warnings, Options) -> string()
518 Types:
520 Warnings = dial_warning()
522 Options = filename_opt() | [format_option()]
523 format_option() =
524 {indent_opt, boolean()} |
525 {filename_opt, filename_opt()} |
526 {error_location, error_location()}
527 filename_opt() = basename | fullpath
528 Get a string from warnings as returned by run/1.
530 If indent_opt is set to true (default), line breaks are inserted
532 in types, contracts, and Erlang code to improve readability.
533 If error_location is set to column (default), locations are for‐
535 matted as Line:Column if the column number is available, other‐
536 wise locations are formatted as Line even if the column number
537 is available.
538 gui() -> ok
540 gui(Options) -> ok
542 Types:
544 Options = [dial_option()]
546 Dialyzer GUI version.
548 plt_info(Plt) ->
550 {ok, ClassicResult | IncrementalResult} |
551 {error, Reason}
552 Types:
554 Plt = file:filename()
556 ClassicResult = [{files, [file:filename()]}]
557 IncrementalResult = {incremental, [{modules, [module()]}]}
558 Reason = not_valid | no_such_file | read_error
559 Returns information about the specified PLT.
561 run(Options) -> Warnings
563 Types:
565 Options = [dial_option()]
567 Warnings = [dial_warning()]
568 Dialyzer command-line version.
570Ericsson AB dialyzer 5.1.1 dialyzer(3)