diff options
Diffstat (limited to 'lib/dialyzer/doc/src/dialyzer.xml')
| -rw-r--r-- | lib/dialyzer/doc/src/dialyzer.xml | 98 |
1 files changed, 78 insertions, 20 deletions
diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml index 63a6fb8aca..334cfcb8d7 100644 --- a/lib/dialyzer/doc/src/dialyzer.xml +++ b/lib/dialyzer/doc/src/dialyzer.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2006</year><year>2022</year> + <year>2006</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -86,11 +86,11 @@ dialyzer [--add_to_plt] [--apps applications] [--build_plt] [--check_plt] [-Ddefine]* [-Dname]* [--dump_callgraph file] [--error_location flag] [files_or_dirs] [--fullpath] [--get_warnings] [--gui] [--help] [-I include_dir]* - [--no_check_plt] [--no_indentation] [-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]*</code> + [--incremental] [--metrics_file] [--no_check_plt] [--no_indentation] + [--no_spec] [-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] [--warning_apps applications] [-Wwarn]*</code> <note> <p>* denotes that multiple occurrences of the option are possible.</p> @@ -111,6 +111,18 @@ dialyzer [--add_to_plt] [--apps applications] [--build_plt] </item> <tag><c>--apps applications</c></tag> <item> + <p> By default, warnings will be reported to all applications given by + <c>--apps</c>. However, if <c>--warning_apps</c> is used, only those applications + given to <c>--warning_apps</c> will have warnings reported. All applications + given by <c>--apps</c>, but not <c>--warning_apps</c>, will be analysed to provide + context to the analysis, but warnings will not be reported for them. + For example, you may want to include libraries you depend on in the + analysis with <c>--apps</c> so discrepancies in their usage can be found, + but only include your own code with <c>--warning_apps</c> so that + discrepancies are only reported in code that you own.</p> + </item> + <tag><c>--warning_apps applications</c></tag> + <item> <p>This option is typically used when building or modifying a PLT as in:</p> <code type="none"> @@ -195,17 +207,38 @@ dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam</code> <p>Skip the PLT check when running Dialyzer. This is useful when working with installed PLTs that never change.</p> </item> + <tag><c>--incremental</c></tag> + <item> + <p>The analysis starts from an existing incremental PLT, or builds one from + scratch if one does not exist, and runs the minimal amount of additional + analysis to report all issues in the given set of apps. Notably, incremental + PLT files are not compatible with "classic" PLT files, and vice versa. + The initial incremental PLT will be updated unless an alternative output + incremental PLT is given.</p> + </item> <tag><c>--no_indentation</c></tag> <item> <p>Do not insert line breaks in types, contracts, and Erlang Code when formatting warnings.</p> </item> + <tag><c>--no_spec</c></tag> + <item> + <p>Ignore functions specs. This is useful for debugging when + one suspects that some specs are incorrect.</p> + </item> <tag><c>-o outfile</c> (or <c>--output outfile</c>)</tag> <item> <p>When using Dialyzer from the command line, send the analysis results to the specified outfile rather than to <c>stdout</c>.</p> </item> + <tag><c>--metrics_file file</c></tag> + <item> + <p> Write metrics about Dialyzer's incrementality (for example, total number of + modules considered, how many modules were changed since the PLT was + last updated, how many modules needed to be analyzed) to a file. This + can be useful for tracking and debugging Dialyzer's incrementality.</p> + </item> <tag><c>--output_plt file</c></tag> <item> <p>Store the PLT at the specified file after building it.</p> @@ -377,20 +410,18 @@ dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code> <item> <p>Suppress warnings for unused functions.</p> </item> + <tag><c>-Wno_unknown</c></tag> + <item> + <p>Suppress warnings about unknown functions and types. The default is to + warn about unknown functions and types when setting the exit + status. When using Dialyzer from Erlang, warnings about unknown functions + and types are returned.</p> + </item> <tag><c>-Wunderspecs</c> (***)</tag> <item> <p>Warn about underspecified functions (the specification is strictly more allowing than the success typing).</p> </item> - <tag><c>-Wunknown</c> (***)</tag> - <item> - <p>Let warnings about unknown functions and types affect the - exit status of the command-line version. The default is to ignore - warnings about unknown functions and types when setting the exit - status. When using Dialyzer from Erlang, warnings about unknown - functions and types are returned; the default is not to return - these warnings.</p> - </item> <tag><c>-Wunmatched_returns</c> (***)</tag> <item> <p>Include warnings for function calls that ignore a structured return @@ -476,6 +507,32 @@ dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code> <p>Currently the only option used is the <seeerl marker="#error_location"><c>error_location</c></seeerl> option. </p> + + <p><em>Dialyzer configuration file:</em></p> + + <p>Dialyzer's configuration file may also be used to augment the default + options and those given directly to the Dialyzer command. It is commonly + used to avoid repeating options which would otherwise need to be given + explicitly to Dialyzer on every invocation. + </p> + + <p>The location of the configuration file can be set via the + <c>DIALYZER_CONFIG</c> environment variable, and defaults to + within the <c>user_config</c> from <seemfa marker="stdlib:filename#basedir/3"> + <c>filename:basedir/3</c></seemfa>. + </p> + + <p>An example configuration file's contents might be:</p> + + <code type="none"> + {incremental, + {default_apps,[stdlib,kernel,erts]}, + {default_warning_apps,[stdlib]} + }. + {warnings, [no_improper_lists]}. + {add_pathsa,["/users/samwise/potatoes/ebin"]}. + {add_pathsz,["/users/smeagol/fish/ebin"]}. + </code> </section> <section> @@ -523,11 +580,6 @@ dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code> options are also enumerated, see type <seetype marker="#warn_option"> <c>warn_option()</c></seetype>.</p> - <note> - <p>Warning option <c>-Wrace_conditions</c> has no effect when - set in source files.</p> - </note> - <p>Attribute <c>-dialyzer()</c> can also be used for turning on warnings. For example, if a module has been fixed regarding unmatched returns, adding the following line can help in assuring @@ -567,6 +619,12 @@ dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code> <name name="file_location"></name> </datatype> <datatype> + <name name="filename_opt"></name> + </datatype> + <datatype> + <name name="format_option"></name> + </datatype> + <datatype> <name name="warn_option"></name> <desc> <p>See section <seeerl |