1dialyzer(3) Erlang Module Definition dialyzer(3)
2
3
4
6 dialyzer - Dialyzer, a DIscrepancy AnaLYZer for ERlang programs.
7
8
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
15 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
26 dialyzer --help
27
28 For more details about the operation of Dialyzer, see section Using
29 Dialyzer from the GUI in the User's Guide.
30
31 Exit status of the command-line version:
32
33 0:
34 No problems were found during the analysis and no warnings were
35 emitted.
36
37 1:
38 Problems were found during the analysis.
39
40 2:
41 No problems were found during the analysis, but warnings were emit‐
42 ted.
43
44 Usage:
45
46 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
56 Note:
57 * denotes that multiple occurrences of the option are possible.
58
59
60 Options of the command-line version:
61
62 --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
69 --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
80 --warning_apps applications:
81 This option is typically used when building or modifying a PLT as
82 in:
83
84 dialyzer --build_plt --apps erts kernel stdlib mnesia ...
85
86 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
91 dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam
92
93 --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
99 --check_plt:
100 Check the PLT for consistency and rebuild it if it is not up-to-
101 date.
102
103 -Dname (or -Dname=value):
104 When analyzing from source, pass the define to Dialyzer. (**)
105
106 --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
112 --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
117 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
122 --fullpath:
123 Display the full path names of files for which warnings are emit‐
124 ted.
125
126 --get_warnings:
127 Make Dialyzer emit warnings even when manipulating the PLT. Warn‐
128 ings are only emitted for files that are analyzed.
129
130 --gui:
131 Use the GUI.
132
133 --help (or -h):
134 Print this message and exit.
135
136 -I include_dir:
137 When analyzing from source, pass the include_dir to Dialyzer. (**)
138
139 --input_list_file file:
140 Analyze the file names that are listed in the specified file (one
141 file name per line).
142
143 --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
147 --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
155 --no_indentation:
156 Do not insert line breaks in types, contracts, and Erlang Code when
157 formatting warnings.
158
159 --no_spec:
160 Ignore functions specs. This is useful for debugging when one sus‐
161 pects that some specs are incorrect.
162
163 -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
167 --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
174 --output_plt file:
175 Store the PLT at the specified file after building it.
176
177 -pa dir:
178 Include dir in the path for Erlang. This is useful when analyzing
179 files that have -include_lib() directives.
180
181 --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
185 --plt_info:
186 Make Dialyzer print information about the PLT and then quit. The
187 PLT can be specified with --plt(s).
188
189 --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
194 dialyzer --build_plt --output_plt plt_1 files_to_include
195 dialyzer --build_plt --output_plt plt_n files_to_include
196
197 They can then be used in either of the following ways:
198
199 dialyzer files_to_analyze --plts plt_1 ... plt_n
200
201 or
202
203 dialyzer --plts plt_1 ... plt_n -- files_to_analyze
204
205 Notice the -- delimiter in the second case.
206
207 --quiet (or -q):
208 Make Dialyzer a bit more quiet.
209
210 -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
215 --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
221 --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
226 --shell:
227 Do not disable the Erlang shell while running the GUI.
228
229 --src:
230 Override the default, which is to analyze BEAM files, and analyze
231 starting from Erlang source code instead.
232
233 --statistics:
234 Print information about the progress of execution (analysis phases,
235 time spent in each, and size of the relative input).
236
237 --verbose:
238 Make Dialyzer a bit more verbose.
239
240 --version (or -v):
241 Print the Dialyzer version and some more information and exit.
242
243 -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
250 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
255
256 Warning options:
257
258 -Werror_handling (***):
259 Include warnings for functions that only return by an exception.
260
261 -Wextra_return (***):
262 Warn about functions whose specification includes types that the
263 function cannot return.
264
265 -Wmissing_return (***):
266 Warn about functions that return values that are not part of the
267 specification.
268
269 -Wno_behaviours:
270 Suppress warnings about behavior callbacks that drift from the pub‐
271 lished recommended interfaces.
272
273 -Wno_contracts:
274 Suppress warnings about invalid contracts.
275
276 -Wno_fail_call:
277 Suppress warnings for failing calls.
278
279 -Wno_fun_app:
280 Suppress warnings for fun applications that will fail.
281
282 -Wno_improper_lists:
283 Suppress warnings for construction of improper lists.
284
285 -Wno_match:
286 Suppress warnings for patterns that are unused or cannot match.
287
288 -Wno_missing_calls:
289 Suppress warnings about calls to missing functions.
290
291 -Wno_opaque:
292 Suppress warnings for violations of opacity of data types.
293
294 -Wno_return:
295 Suppress warnings for functions that will never return a value.
296
297 -Wno_undefined_callbacks:
298 Suppress warnings about behaviors that have no -callback attributes
299 for their callbacks.
300
301 -Wno_unused:
302 Suppress warnings for unused functions.
303
304 -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
310 -Wunderspecs (***):
311 Warn about underspecified functions (the specification is strictly
312 more allowing than the success typing).
313
314 -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
320 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
324 -Woverspecs (***):
325 Warn about overspecified functions (the specification is strictly
326 less allowing than the success typing).
327
328 -Wspecdiffs (***):
329 Warn when the specification is different than the success typing.
330
331 Note:
332 *** denotes options that turn on warnings rather than turning them off.
333
334
335 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
340 -Wno_underspecs:
341 Suppress warnings about underspecified functions (the specification
342 is strictly more allowing than the success typing).
343
344 -Wno_extra_return:
345 Suppress warnings about functions whose specification includes
346 types that the function cannot return.
347
348 -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
364 The list is appended to any options given to run/1 or on the command
365 line.
366
367 The list can be retrieved with compile:env_compiler_options/0.
368
369 Currently the only option used is the error_location option.
370
371 Dialyzer configuration file:
372
373 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
378 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
382 An example configuration file's contents might be:
383
384 {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
392
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
398 -dialyzer({nowarn_function, f/0}).
399
400 To turn off warnings for improper lists, add the following line to the
401 source file:
402
403 -dialyzer(no_improper_lists).
404
405 Attribute -dialyzer() is allowed after function declarations. Lists of
406 warning options or functions are allowed:
407
408 -dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).
409
410 Warning options can be restricted to functions:
411
412 -dialyzer({no_improper_lists, g/0}).
413
414 -dialyzer({[no_return, no_match], [g/0, h/0]}).
415
416 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
422 -dialyzer({no_underspecs, f/0}).
423
424 For help on the warning options, use dialyzer -Whelp. The options are
425 also enumerated, see type warn_option().
426
427 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
432 -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
460 Option from defaults to byte_code. Options init_plt and plts
461 change the default.
462
463 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
475 dial_warning() =
476 {Tag :: dial_warn_tag(),
477 Id :: file_location(),
478 Msg :: {atom(), [term()]}}
479
480 error_location() = column | line
481
482 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
486 file_location() =
487 {File :: file:filename(), Location :: erl_anno:location()}
488
489 filename_opt() = basename | fullpath
490
491 format_option() =
492 {indent_opt, boolean()} |
493 {filename_opt, filename_opt()} |
494 {error_location, error_location()}
495
496 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
505 See section Warning options for a description of the warning op‐
506 tions.
507
509 format_warning(Warnings) -> string()
510
511 Types:
512
513 Warnings = dial_warning()
514
515 Get a string from warnings as returned by run/1.
516
517 format_warning(Warnings, Options) -> string()
518
519 Types:
520
521 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
529 Get a string from warnings as returned by run/1.
530
531 If indent_opt is set to true (default), line breaks are inserted
532 in types, contracts, and Erlang code to improve readability.
533
534 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
539 gui() -> ok
540
541 gui(Options) -> ok
542
543 Types:
544
545 Options = [dial_option()]
546
547 Dialyzer GUI version.
548
549 plt_info(Plt) ->
550 {ok, ClassicResult | IncrementalResult} |
551 {error, Reason}
552
553 Types:
554
555 Plt = file:filename()
556 ClassicResult = [{files, [file:filename()]}]
557 IncrementalResult = {incremental, [{modules, [module()]}]}
558 Reason = not_valid | no_such_file | read_error
559
560 Returns information about the specified PLT.
561
562 run(Options) -> Warnings
563
564 Types:
565
566 Options = [dial_option()]
567 Warnings = [dial_warning()]
568
569 Dialyzer command-line version.
570
571
572
573Ericsson AB dialyzer 5.1.1 dialyzer(3)