diff options
Diffstat (limited to 'lib/dialyzer/doc/src/dialyzer.xml')
| -rw-r--r-- | lib/dialyzer/doc/src/dialyzer.xml | 219 |
1 files changed, 152 insertions, 67 deletions
diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml index 1ec2ce830a..b6547b11e1 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>2010</year> + <year>2006</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -64,81 +64,146 @@ ]]></code> <p>Usage:</p> <code type="none"><![CDATA[ - dialyzer [--help] [--version] [--shell] [--quiet] [--verbose] - [-pa dir]* [--plt plt] [-Ddefine]* [-I include_dir]* - [--output_plt file] [-Wwarn]* [--src] - [-c applications] [-r applications] [-o outfile] + dialyzer [--help] [--version] [--shell] [--quiet] [--verbose] + [-pa dir]* [--plt plt] [--plts plt*] [-Ddefine]* + [-I include_dir]* [--output_plt file] [-Wwarn]* + [--src] [--gui | --wx] [files_or_dirs] [-r dirs] + [--apps applications] [-o outfile] [--build_plt] [--add_to_plt] [--remove_from_plt] [--check_plt] [--no_check_plt] [--plt_info] [--get_warnings] + [--no_native] [--fullpath] ]]></code> <p>Options:</p> <taglist> - <tag><c><![CDATA[-c applications]]></c>(or <c><![CDATA[--command-line applications]]></c>)</tag> - <item>use Dialyzer from the command line (no GUI) to detect defects in the - specified applications (directories or <c><![CDATA[.erl]]></c> or <c><![CDATA[.beam]]></c> files)</item> - <tag><c><![CDATA[-r applications]]></c></tag> - <item>same as <c><![CDATA[-c]]></c> only that directories are searched recursively for - subdirectories containing <c><![CDATA[.erl]]></c> or <c><![CDATA[.beam]]></c> files (depending on the - type of analysis)</item> - <tag><c><![CDATA[-o outfile]]></c>(or <c><![CDATA[--output outfile]]></c>)</tag> - <item>when using Dialyzer from the command line, send the analysis - results in the specified <c><![CDATA[outfile]]></c> rather than in stdout</item> - <tag><c><![CDATA[--src]]></c></tag> - <item>override the default, which is to analyze debug compiled BEAM - bytecode, and analyze starting from Erlang source code instead</item> + <tag><c><![CDATA[files_or_dirs]]></c> (for backwards compatibility also + as: <c><![CDATA[-c files_or_dirs]]></c></tag> + <item>Use Dialyzer from the command line to detect defects in the + specified files or directories containing <c><![CDATA[.erl]]></c> or + <c><![CDATA[.beam]]></c> files, depending on the type of the + analysis.</item> + <tag><c><![CDATA[-r dirs]]></c></tag> + <item>Same as the previous but the specified directories are searched + recursively for subdirectories containing <c><![CDATA[.erl]]></c> or + <c><![CDATA[.beam]]></c> files in them, depending on the type of + analysis.</item> + <tag><c><![CDATA[--apps applications]]></c></tag> + <item>Option typically used when building or modifying a plt as in: + <code type="none"><![CDATA[ + dialyzer --build_plt --apps erts kernel stdlib mnesia ... + ]]></code> + to conveniently refer to library applications corresponding to the + Erlang/OTP installation. However, the option is general and can also + be used during analysis in order to refer to Erlang/OTP applications. + In addition, file or directory names can also be included, as in: + <code type="none"><![CDATA[ + dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam + ]]></code></item> + <tag><c><![CDATA[-o outfile]]></c> (or + <c><![CDATA[--output outfile]]></c>)</tag> + <item>When using Dialyzer from the command line, send the analysis + results to the specified outfile rather than to stdout.</item> <tag><c><![CDATA[--raw]]></c></tag> <item>When using Dialyzer from the command line, output the raw analysis - results (Erlang terms) instead of the formatted result. - The raw format is easier to post-process (for instance, to filter - warnings or to output HTML pages).</item> - <tag><c><![CDATA[-Dname]]></c>(or <c><![CDATA[-Dname=value]]></c>)</tag> - <item>when analyzing from source, pass the define to Dialyzer (**)</item> + results (Erlang terms) instead of the formatted result. The raw format + is easier to post-process (for instance, to filter warnings or to + output HTML pages).</item> + <tag><c><![CDATA[--src]]></c></tag> + <item>Override the default, which is to analyze BEAM files, and + analyze starting from Erlang source code instead.</item> + <tag><c><![CDATA[-Dname]]></c> (or <c><![CDATA[-Dname=value]]></c>)</tag> + <item>When analyzing from source, pass the define to Dialyzer. (**)</item> <tag><c><![CDATA[-I include_dir]]></c></tag> - <item>when analyzing from source, pass the <c><![CDATA[include_dir]]></c> to Dialyzer (**)</item> + <item>When analyzing from source, pass the <c><![CDATA[include_dir]]></c> + to Dialyzer. (**)</item> <tag><c><![CDATA[-pa dir]]></c></tag> - <item>Include <c><![CDATA[dir]]></c> in the path for Erlang. Useful when analyzing files - that have <c><![CDATA[-include_lib()]]></c> directives.</item> + <item>Include <c><![CDATA[dir]]></c> in the path for Erlang (useful when + analyzing files that have <c><![CDATA['-include_lib()']]></c> + directives).</item> <tag><c><![CDATA[--output_plt file]]></c></tag> - <item>Store the PLT at the specified location after building it.</item> + <item>Store the plt at the specified file after building it.</item> <tag><c><![CDATA[--plt plt]]></c></tag> - <item>Use the specified plt as the initial persistent lookup table.</item> + <item>Use the specified plt as the initial plt (if the plt was built + during setup the files will be checked for consistency).</item> + <tag><c><![CDATA[--plts plt*]]></c></tag> + <item>Merge the specified plts to create the initial plt -- requires + that the plts are disjoint (i.e., do not have any module + appearing in more than one plt). + The plts are created in the usual way: + <code type="none"><![CDATA[ + dialyzer --build_plt --output_plt plt_1 files_to_include + ... + dialyzer --build_plt --output_plt plt_n files_to_include + ]]></code> + and then can be used in either of the following ways: + <code type="none"><![CDATA[ + dialyzer files_to_analyze --plts plt_1 ... plt_n + ]]></code> + or: + <code type="none"><![CDATA[ + dialyzer --plts plt_1 ... plt_n -- files_to_analyze + ]]></code> + (Note the -- delimiter in the second case)</item> <tag><c><![CDATA[-Wwarn]]></c></tag> - <item>a family of option which selectively turn on/off warnings. - (for help on the names of warnings use <c><![CDATA[dialyzer -Whelp]]></c>)</item> + <item>A family of options which selectively turn on/off warnings + (for help on the names of warnings use + <c><![CDATA[dialyzer -Whelp]]></c>).</item> <tag><c><![CDATA[--shell]]></c></tag> - <item>do not disable the Erlang shell while running the GUI</item> - <tag><c><![CDATA[--version (or -v)]]></c></tag> - <item>prints the Dialyzer version and some more information and exits</item> - <tag><c><![CDATA[--help (or -h)]]></c></tag> - <item>prints this message and exits</item> - <tag><c><![CDATA[--quiet (or -q)]]></c></tag> - <item>makes Dialyzer a bit more quiet</item> + <item>Do not disable the Erlang shell while running the GUI.</item> + <tag><c><![CDATA[--version]]></c> (or <c><![CDATA[-v]]></c>)</tag> + <item>Print the Dialyzer version and some more information and + exit.</item> + <tag><c><![CDATA[--help]]></c> (or <c><![CDATA[-h]]></c>)</tag> + <item>Print this message and exit.</item> + <tag><c><![CDATA[--quiet]]></c> (or <c><![CDATA[-q]]></c>)</tag> + <item>Make Dialyzer a bit more quiet.</item> <tag><c><![CDATA[--verbose]]></c></tag> - <item>makes Dialyzer a bit more verbose</item> - <tag><c><![CDATA[--check_plt]]></c></tag> - <item>Only checks if the initial PLT is up to date and rebuilds it if this is not the case</item> - <tag><c><![CDATA[--no_check_plt (or -n)]]></c></tag> - <item>Skip the PLT integrity check when running Dialyzer. - Useful when working with installed PLTs that never change.</item> + <item>Make Dialyzer a bit more verbose.</item> <tag><c><![CDATA[--build_plt]]></c></tag> - <item>The analysis starts from an empty PLT and creates a new one from - the files specified with -c and -r. Only works for beam files. - Use --plt or --output_plt to override the default PLT location.</item> - <tag><c><![CDATA[--add_to_plt]]></c></tag> - <item> The PLT is extended to also include the files specified with - -c and -r. Use --plt to specify which PLT to start from, and --output_plt - to specify where to put the PLT. Note that the analysis might include - files from the PLT if they depend on the new files. - This option only works with beam files.</item> + <item>The analysis starts from an empty plt and creates a new one from + the files specified with <c><![CDATA[-c]]></c> and + <c><![CDATA[-r]]></c>. Only works for beam files. Use + <c><![CDATA[--plt]]></c> or <c><![CDATA[--output_plt]]></c> to + override the default plt location.</item> + <tag><c><![CDATA[--add_to_plt]]></c></tag> + <item>The plt is extended to also include the files specified with + <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c>. Use + <c><![CDATA[--plt]]></c> to specify which plt to start from, + and <c><![CDATA[--output_plt]]></c> to specify where to put the plt. + Note that the analysis might include files from the plt if they depend + on the new files. This option only works with beam files.</item> <tag><c><![CDATA[--remove_from_plt]]></c></tag> - <item>The information from the files specified with -c and -r is removed - from the PLT. Note that this may cause a re-analysis of the remaining - dependent files.</item> + <item>The information from the files specified with + <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c> is removed + from the plt. Note that this may cause a re-analysis of the remaining + dependent files.</item> + <tag><c><![CDATA[--check_plt]]></c></tag> + <item>Check the plt for consistency and rebuild it if it is not + up-to-date.</item> + <tag><c><![CDATA[--no_check_plt]]></c></tag> + <item>Skip the plt check when running Dialyzer. Useful when working with + installed plts that never change.</item> + <tag><c><![CDATA[--plt_info]]></c></tag> + <item>Make Dialyzer print information about the plt and then quit. The + plt can be specified with <c><![CDATA[--plt(s)]]></c>.</item> <tag><c><![CDATA[--get_warnings]]></c></tag> - <item>Makes Dialyzer emit warnings even when manipulating the PLT. Only - emits warnings for files that are actually analyzed. The default is to - not emit any warnings when manipulating the PLT. This option has no - effect when performing a normal analysis.</item> + <item>Make Dialyzer emit warnings even when manipulating the plt. + Warnings are only emitted for files that are actually analyzed.</item> + <tag><c><![CDATA[--dump_callgraph file]]></c></tag> + <item>Dump the call graph into the specified file whose format is + determined by the file name extension. Supported extensions are: raw, + dot, and ps. If something else is used as file name extension, default + format '.raw' will be used.</item> + <tag><c><![CDATA[--no_native]]></c> (or <c><![CDATA[-nn]]></c>)</tag> + <item>Bypass the native code compilation of some key files that Dialyzer + heuristically performs when dialyzing many files; this avoids the + compilation time but it may result in (much) longer analysis + time.</item> + <tag><c><![CDATA[--fullpath]]></c></tag> + <item>Display the full path names of files for which warnings are emitted.</item> + <tag><c><![CDATA[--gui]]></c></tag> + <item>Use the gs-based GUI.</item> + <tag><c><![CDATA[--wx]]></c></tag> + <item>Use the wx-based GUI.</item> </taglist> <note> <p>* denotes that multiple occurrences of these options are possible.</p> @@ -148,33 +213,49 @@ <p>Warning options:</p> <taglist> <tag><c><![CDATA[-Wno_return]]></c></tag> - <item>Suppress warnings for functions of no return.</item> + <item>Suppress warnings for functions that will never return a + value.</item> <tag><c><![CDATA[-Wno_unused]]></c></tag> <item>Suppress warnings for unused functions.</item> <tag><c><![CDATA[-Wno_improper_lists]]></c></tag> <item>Suppress warnings for construction of improper lists.</item> + <tag><c><![CDATA[-Wno_tuple_as_fun]]></c></tag> + <item>Suppress warnings for using tuples instead of funs.</item> <tag><c><![CDATA[-Wno_fun_app]]></c></tag> <item>Suppress warnings for fun applications that will fail.</item> <tag><c><![CDATA[-Wno_match]]></c></tag> <item>Suppress warnings for patterns that are unused or cannot match.</item> + <tag><c><![CDATA[-Wno_opaque]]></c></tag> + <item>Suppress warnings for violations of opaqueness of data types.</item> + <tag><c><![CDATA[-Wunmatched_returns]]></c>***</tag> + <item>Include warnings for function calls which ignore a structured return + value or do not match against one of many possible return + value(s).</item> <tag><c><![CDATA[-Werror_handling]]></c>***</tag> <item>Include warnings for functions that only return by means of an exception.</item> - <tag><c><![CDATA[-Wunmatched_returns]]></c>***</tag> - <item>Include warnings for function calls which ignore a structured return - value or do not match against one of many possible return value(s).</item> + <tag><c><![CDATA[-Wrace_conditions]]></c>***</tag> + <item>Include warnings for possible race conditions.</item> + <tag><c><![CDATA[-Wbehaviours]]></c>***</tag> + <item>Include warnings about behaviour callbacks which drift from the + published recommended interfaces.</item> <tag><c><![CDATA[-Wunderspecs]]></c>***</tag> <item>Warn about underspecified functions - (the -spec is strictly more allowing than the success typing)</item> + (the -spec is strictly more allowing than the success typing).</item> + </taglist> + <p>The following options are also available but their use is not + recommended: (they are mostly for Dialyzer developers and internal + debugging)</p> + <taglist> <tag><c><![CDATA[-Woverspecs]]></c>***</tag> <item>Warn about overspecified functions - (the -spec is strictly less allowing than the success typing)</item> + (the -spec is strictly less allowing than the success typing).</item> <tag><c><![CDATA[-Wspecdiffs]]></c>***</tag> - <item>Warn when the -spec is different than the success typing</item> + <item>Warn when the -spec is different than the success typing.</item> </taglist> <note> - <p>*** These are options that turn on warnings rather than + <p>*** Identifies options that turn on warnings rather than turning them off.</p> </note> </section> @@ -203,6 +284,7 @@ Option : {files, [Filename : string()]} | {defines, [{Macro: atom(), Value : term()}]} | {from, src_code | byte_code} %% Defaults to byte_code | {init_plt, FileName : string()} %% If changed from default + | {plts, [FileName :: string()]} %% If changed from default | {include_dirs, [DirName : string()]} | {output_file, FileName : string()} | {output_plt, FileName :: string()} @@ -215,8 +297,11 @@ WarnOpts : no_return | no_improper_lists | no_fun_app | no_match + | no_opaque | no_fail_call | error_handling + | race_conditions + | behaviours | unmatched_returns | overspecs | underspecs |