diff options
Diffstat (limited to 'lib/dialyzer/doc/src')
| -rw-r--r-- | lib/dialyzer/doc/src/Makefile | 20 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/book.xml | 4 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/dialyzer.xml | 827 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/dialyzer_chapter.xml | 305 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/fascicules.xml | 18 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/note.gif | bin | 1539 -> 0 bytes | |||
| -rw-r--r-- | lib/dialyzer/doc/src/notes.xml | 530 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/part.xml | 5 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/part_notes.xml | 37 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/ref_man.xml | 6 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/typer.xml | 157 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/warning.gif | bin | 1498 -> 0 bytes |
12 files changed, 1325 insertions, 584 deletions
diff --git a/lib/dialyzer/doc/src/Makefile b/lib/dialyzer/doc/src/Makefile index 77d0a6fc68..3463b589e6 100644 --- a/lib/dialyzer/doc/src/Makefile +++ b/lib/dialyzer/doc/src/Makefile @@ -9,11 +9,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# +# # The Initial Developer of the Original Code is Ericsson Utvecklings AB. # Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings # AB. All Rights Reserved.'' -# +# include $(ERL_TOP)/make/target.mk include $(ERL_TOP)/make/$(TARGET)/otp.mk @@ -34,9 +34,9 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = ref_man.xml -XML_REF3_FILES = dialyzer.xml +XML_REF3_FILES = dialyzer.xml typer.xml -XML_PART_FILES = part.xml part_notes.xml +XML_PART_FILES = part.xml XML_CHAPTER_FILES = dialyzer_chapter.xml notes.xml BOOK_FILES = book.xml @@ -65,9 +65,9 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf # ---------------------------------------------------- -# FLAGS +# FLAGS # ---------------------------------------------------- -XML_FLAGS += +XML_FLAGS += # ---------------------------------------------------- # Targets @@ -85,19 +85,19 @@ html: gifs $(HTML_REF_MAN_FILE) man: $(MAN3_FILES) -gifs: $(GIF_FILES:%=$(HTMLDIR)/%) +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) -debug opt: +debug opt: clean clean_docs: rm -rf $(HTMLDIR)/* rm -f $(MAN3DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) - rm -f errs core *~ + rm -f errs core *~ # ---------------------------------------------------- # Release Target -# ---------------------------------------------------- +# ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs diff --git a/lib/dialyzer/doc/src/book.xml b/lib/dialyzer/doc/src/book.xml index 4cc2a9db7c..46df8b81b8 100644 --- a/lib/dialyzer/doc/src/book.xml +++ b/lib/dialyzer/doc/src/book.xml @@ -4,7 +4,7 @@ <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,7 +25,7 @@ <title>Dialyzer</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> <file>book.xml</file> </header> diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml index 3fd34241b2..e34ffd6def 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>2015</year> + <year>2006</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,341 +25,472 @@ <title>dialyzer</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-20</date> <rev></rev> + <file>dialyzer.xml</file> </header> <module>dialyzer</module> - <modulesummary>The Dialyzer, a DIscrepancy AnalYZer for ERlang programs</modulesummary> + <modulesummary>Dialyzer, a DIscrepancy AnaLYZer for ERlang programs. + </modulesummary> <description> - <p>The Dialyzer is a static analysis tool that identifies software - discrepancies such as definite type errors, code which has become - dead or unreachable due to some programming error, unnecessary - tests, etc. in single Erlang modules or entire (sets of) - applications. Dialyzer starts its analysis from either - debug-compiled BEAM bytecode or from Erlang source code. The file - and line number of a discrepancy is reported along with an - indication of what the discrepancy is about. Dialyzer bases its - analysis on the concept of success typings which allows for sound - warnings (no false positives).</p> - <p>Read more about Dialyzer and about how to use it from the GUI - in <seealso marker="dialyzer_chapter">Dialyzer User's - Guide</seealso>.</p> + <p>Dialyzer is a static analysis tool that identifies software + discrepancies, such as definite type errors, code that has become dead + or unreachable because of programming error, and unnecessary tests, + in single Erlang modules or entire (sets of) applications.</p> + + <p>Dialyzer starts its analysis from either + debug-compiled BEAM bytecode or from Erlang source code. The file + and line number of a discrepancy is reported along with an + indication of what the discrepancy is about. Dialyzer bases its + analysis on the concept of success typings, which allows for sound + warnings (no false positives).</p> </description> <section> - <title>Using the Dialyzer from the command line</title> - <p>Dialyzer also has a command line version for automated use. Below is a - brief description of the list of its options. The same information can - be obtained by writing</p> - <code type="none"> - dialyzer --help</code> - <p>in a shell. Please refer to the GUI description for more details on - the operation of Dialyzer.</p> - <p>The exit status of the command line version is:</p> + <marker id="command_line"></marker> + <title>Using Dialyzer from the Command Line</title> + <p>Dialyzer has a command-line version for automated use. This + section provides a brief description of the options. The same information + can be obtained by writing the following in a shell:</p> + <code type="none"> - 0 - No problems were encountered during the analysis and no - warnings were emitted. - 1 - Problems were encountered during the analysis. - 2 - No problems were encountered, but warnings were emitted.</code> - <p>Usage:</p> +dialyzer --help</code> + + <p>For more details about the operation of Dialyzer, see section + <seealso marker="dialyzer_chapter#dialyzer_gui"> + Using Dialyzer from the GUI</seealso> in the User's Guide.</p> + + <p><em>Exit status of the command-line version:</em></p> + + <taglist> + <tag><c>0</c></tag> + <item> + <p>No problems were found during the analysis and no warnings were + emitted.</p> + </item> + <tag><c>1</c></tag> + <item> + <p>Problems were found during the analysis.</p> + </item> + <tag><c>2</c></tag> + <item> + <p>No problems were found during the analysis, but warnings were + emitted.</p> + </item> + </taglist> + + <p><em>Usage:</em></p> + <code type="none"> - dialyzer [--help] [--version] [--shell] [--quiet] [--verbose] - [-pa dir]* [--plt plt] [--plts plt*] [-Ddefine]* - [-I include_dir]* [--output_plt file] [-Wwarn]* [--raw] - [--src] [--gui] [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] - [--dump_callgraph file] [--no_native] [--fullpath] - [--statistics] [--no_native_cache]</code> - <p>Options:</p> +dialyzer [--add_to_plt] [--apps applications] [--build_plt] + [--check_plt] [-Ddefine]* [-Dname] [--dump_callgraph file] + [files_or_dirs] [--fullpath] [--get_warnings] [--gui] [--help] + [-I include_dir]* [--no_check_plt] [--no_native] + [--no_native_cache] [-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> + + <note> + <p>* denotes that multiple occurrences of the option are possible.</p> + </note> + + <p><em>Options:</em></p> + <taglist> - <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: + <tag><c>--add_to_plt</c></tag> + <item> + <p>The PLT is extended to also include the files specified with + <c>-c</c> and <c>-r</c>. Use + <c>--plt</c> to specify which PLT to start from, + and <c>--output_plt</c> to specify where to put the PLT. + Notice that the analysis possibly can include files from the PLT if + they depend on the new files. This option only works for BEAM + files.</p> + </item> + <tag><c>--apps applications</c></tag> + <item> + <p>This option is typically used when building or modifying a PLT as + in:</p> <code type="none"> - 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: +dialyzer --build_plt --apps erts kernel stdlib mnesia ...</code> + <p>to refer conveniently to library applications corresponding to the + Erlang/OTP installation. However, this option is general and can also + be used during analysis to refer to Erlang/OTP applications. + File or directory names can also be included, as in:</p> <code type="none"> - 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[--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> - <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> - <tag><c><![CDATA[--output_plt file]]></c></tag> - <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 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: +dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam</code> + </item> + <tag><c>--build_plt</c></tag> + <item> + <p>The analysis starts from an empty PLT and creates a new one from + the files specified with <c>-c</c> and + <c>-r</c>. This option only works for BEAM files. + To override the default PLT location, use + <c>--plt</c> or <c>--output_plt</c>.</p> + </item> + <tag><c>--check_plt</c></tag> + <item> + <p>Check the PLT for consistency and rebuild it if it is not + up-to-date.</p> + </item> + <tag><c>-Dname</c> (or <c>-Dname=value</c>)</tag> + <item> + <p>When analyzing from source, pass the define to Dialyzer. + (**)</p> + </item> + <tag><c>--dump_callgraph file</c></tag> + <item> + <p>Dump the call graph into the specified file whose format is + determined by the filename extension. Supported extensions are: + <c>raw</c>, <c>dot</c>, and <c>ps</c>. If something else is used as + filename extension, default format <c>.raw</c> is used.</p> + </item> + <tag><c>files_or_dirs</c> (for backward compatibility also + as <c>-c files_or_dirs</c>)</tag> + <item> + <p>Use Dialyzer from the command line to detect defects in the + specified files or directories containing <c>.erl</c> or + <c>.beam</c> files, depending on the type of the + analysis.</p> + </item> + <tag><c>--fullpath</c></tag> + <item> + <p>Display the full path names of files for which warnings are + emitted.</p> + </item> + <tag><c>--get_warnings</c></tag> + <item> + <p>Make Dialyzer emit warnings even when manipulating the PLT. + Warnings are only emitted for files that are analyzed.</p> + </item> + <tag><c>--gui</c></tag> + <item> + <p>Use the GUI.</p></item> + <tag><c>--help</c> (or <c>-h</c>)</tag> + <item> + <p>Print this message and exit.</p> + </item> + <tag><c>-I include_dir</c></tag> + <item> + <p>When analyzing from source, pass the <c>include_dir</c> + to Dialyzer. (**)</p> + </item> + <tag><c>--no_check_plt</c></tag> + <item> + <p>Skip the PLT check when running Dialyzer. This is useful when + working with installed PLTs that never change.</p> + </item> + <tag><c>--no_native</c> (or <c>-nn</c>)</tag> + <item> + <p>Bypass the native code compilation of some key files that + Dialyzer heuristically performs when dialyzing many files. + This avoids the compilation time, but can result in (much) longer + analysis time.</p> + </item> + <tag><c>--no_native_cache</c></tag> + <item> + <p>By default, Dialyzer caches the results of native compilation + in directory <c>$XDG_CACHE_HOME/erlang/dialyzer_hipe_cache</c>. + <c>XDG_CACHE_HOME</c> defaults to <c>$HOME/.cache</c>. + Use this option to disable caching.</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>--output_plt file</c></tag> + <item> + <p>Store the PLT at the specified file after building it.</p> + </item> + <tag><c>-pa dir</c></tag> + <item> + <p>Include <c>dir</c> in the path for Erlang. This is useful + when analyzing files that have <c>-include_lib()</c> + directives.</p> + </item> + <tag><c>--plt plt</c></tag> + <item> + <p>Use the specified PLT as the initial PLT. If the PLT was built + during setup, the files are checked for consistency.</p> + </item> + <tag><c>--plt_info</c></tag> + <item> + <p>Make Dialyzer print information about the PLT and then quit. + The PLT can be specified with <c>--plt(s)</c>.</p> + </item> + <tag><c>--plts plt*</c></tag> + <item> + <p>Merge the specified PLTs to create the initial PLT. This requires + that the PLTs are disjoint (that is, do not have any module + appearing in more than one PLT). + The PLTs are created in the usual way:</p> <code type="none"> - 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: +dialyzer --build_plt --output_plt plt_1 files_to_include +... +dialyzer --build_plt --output_plt plt_n files_to_include</code> + <p>They can then be used in either of the following ways:</p> <code type="none"> - dialyzer files_to_analyze --plts plt_1 ... plt_n</code> - or: +dialyzer files_to_analyze --plts plt_1 ... plt_n</code> + <p>or</p> <code type="none"> - 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 options which selectively turn on/off warnings - (for help on the names of warnings use - <c><![CDATA[dialyzer -Whelp]]></c>). - Note that the options can also be given in the file with a - <c>-dialyzer()</c> attribute. See <seealso - marker="#suppression">Requesting or Suppressing Warnings in - Source Files</seealso> below for details.</item> - <tag><c><![CDATA[--shell]]></c></tag> - <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>Make Dialyzer a bit more verbose.</item> - <tag><c><![CDATA[--statistics]]></c></tag> - <item>Prints information about the progress of execution (analysis phases, - time spent in each and size of the relative input).</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><![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><![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>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[--no_native_cache]]></c></tag> - <item>By default, Dialyzer caches the results of native compilation in the - <c>$XDG_CACHE_HOME/erlang/dialyzer_hipe_cache</c> directory. - <c>XDG_CACHE_HOME</c> defaults to <c>$HOME/.cache</c>. - Use this option to disable caching.</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 GUI.</item> +dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code> + <p>Notice the <c>--</c> delimiter in the second case.</p> + </item> + <tag><c>--quiet</c> (or <c>-q</c>)</tag> + <item> + <p>Make Dialyzer a bit more quiet.</p> + </item> + <tag><c>-r dirs</c></tag> + <item> + <p>Same as <c>files_or_dirs</c>, but the specified + directories are searched + recursively for subdirectories containing <c>.erl</c> or + <c>.beam</c> files in them, depending on the type of + analysis.</p> + </item> + <tag><c>--raw</c></tag> + <item> + <p>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 example, to filter warnings or to + output HTML pages).</p> + </item> + <tag><c>--remove_from_plt</c></tag> + <item> + <p>The information from the files specified with + <c>-c</c> and <c>-r</c> is removed from + the PLT. Notice that this can cause a reanalysis of the remaining + dependent files.</p> + </item> + <tag><c>--shell</c></tag> + <item> + <p>Do not disable the Erlang shell while running the GUI.</p> + </item> + <tag><c>--src</c></tag> + <item> + <p>Override the default, which is to analyze BEAM files, and + analyze starting from Erlang source code instead.</p> + </item> + <tag><c>--statistics</c></tag> + <item> + <p>Print information about the progress of execution (analysis phases, + time spent in each, and size of the relative input).</p> + </item> + <tag><c>--verbose</c></tag> + <item> + <p>Make Dialyzer a bit more verbose.</p> + </item> + <tag><c>--version</c> (or <c>-v</c>)</tag> + <item> + <p>Print the Dialyzer version and some more information and + exit.</p> + </item> + <tag><c>-Wwarn</c></tag> + <item> + <p>A family of options that selectively turn on/off warnings. + (For help on the names of warnings, use + <c>dialyzer -Whelp</c>.) + Notice that the options can also be specified in the file with a + <c>-dialyzer()</c> attribute. For details, see section <seealso + marker="#suppression">Requesting or Suppressing Warnings in + Source Files</seealso>.</p> + </item> </taglist> + <note> - <p>* denotes that multiple occurrences of these options are possible.</p> - <p>** options <c><![CDATA[-D]]></c> and <c><![CDATA[-I]]></c> work both from command-line and in the Dialyzer GUI; - the syntax of defines and includes is the same as that used by <c><![CDATA[erlc]]></c>.</p> + <p>** options <c>-D</c> and <c>-I</c> work both + from the command line and in the Dialyzer GUI; the syntax of + defines and includes is the same as that used by + <seealso marker="erts:erlc">erlc(1)</seealso>.</p> </note> - <p>Warning options:</p> + + <p><em>Warning options:</em></p> + <taglist> - <tag><c><![CDATA[-Wno_return]]></c></tag> - <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_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[-Wno_fail_call]]></c></tag> - <item>Suppress warnings for failing calls.</item> - <tag><c><![CDATA[-Wno_contracts]]></c></tag> - <item>Suppress warnings about invalid contracts.</item> - <tag><c><![CDATA[-Wno_behaviours]]></c></tag> - <item>Suppress warnings about behaviour callbacks which drift from the - published recommended interfaces.</item> - <tag><c><![CDATA[-Wno_missing_calls]]></c></tag> - <item>Suppress warnings about calls to missing functions.</item> - <tag><c><![CDATA[-Wno_undefined_callbacks]]></c></tag> - <item>Suppress warnings about behaviours that have no - <c>-callback</c> attributes for their callbacks.</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[-Wrace_conditions]]></c>***</tag> - <item>Include warnings for possible race conditions. Note that the - analysis that finds data races performs intra-procedural data flow analysis - and can sometimes explode in time. Enable it at your own risk. - </item> -i <tag><c><![CDATA[-Wunderspecs]]></c>***</tag> - <item>Warn about underspecified functions - (the -spec is strictly more allowing than the success typing).</item> - <tag><c><![CDATA[-Wunknown]]></c>***</tag> - <item>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 the Dialyzer from Erlang, warnings about unknown - functions and types are returned; the default is not to return - these warnings.</item> + <tag><c>-Werror_handling</c> (***)</tag> + <item> + <p>Include warnings for functions that only return by an exception.</p> + </item> + <tag><c>-Wno_behaviours</c></tag> + <item> + <p>Suppress warnings about behavior callbacks that drift from the + published recommended interfaces.</p> + </item> + <tag><c>-Wno_contracts</c></tag> + <item> + <p>Suppress warnings about invalid contracts.</p> + </item> + <tag><c>-Wno_fail_call</c></tag> + <item> + <p>Suppress warnings for failing calls.</p> + </item> + <tag><c>-Wno_fun_app</c></tag> + <item> + <p>Suppress warnings for fun applications that will fail.</p> + </item> + <tag><c>-Wno_improper_lists</c></tag> + <item> + <p>Suppress warnings for construction of improper lists.</p> + </item> + <tag><c>-Wno_match</c></tag> + <item> + <p>Suppress warnings for patterns that are unused or cannot match.</p> + </item> + <tag><c>-Wno_missing_calls</c></tag> + <item> + <p>Suppress warnings about calls to missing functions.</p> + </item> + <tag><c>-Wno_opaque</c></tag> + <item> + <p>Suppress warnings for violations of opacity of data types.</p> + </item> + <tag><c>-Wno_return</c></tag> + <item> + <p>Suppress warnings for functions that will never return a value.</p> + </item> + <tag><c>-Wno_undefined_callbacks</c></tag> + <item> + <p>Suppress warnings about behaviors that have no + <c>-callback</c> attributes for their callbacks.</p> + </item> + <tag><c>-Wno_unused</c></tag> + <item> + <p>Suppress warnings for unused functions.</p> + </item> + <tag><c>-Wrace_conditions</c> (***)</tag> + <item> + <p>Include warnings for possible race conditions. Notice that the + analysis that finds data races performs intra-procedural data flow + analysis and can sometimes explode in time. Enable it at your own + risk.</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 + value or do not match against one of many possible return + value(s).</p> + </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> + + <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> - <tag><c><![CDATA[-Wspecdiffs]]></c>***</tag> - <item>Warn when the -spec is different than the success typing.</item> + <tag><c>-Woverspecs</c> (***)</tag> + <item> + <p>Warn about overspecified functions (the specification is strictly + less allowing than the success typing).</p> + </item> + <tag><c>-Wspecdiffs</c> (***)</tag> + <item> + <p>Warn when the specification is different than the success typing.</p> + </item> </taglist> + <note> - <p>*** Identifies options that turn on warnings rather than - turning them off.</p> + <p>*** denotes options that turn on warnings rather than + turning them off.</p> </note> </section> <section> - <title>Using the Dialyzer from Erlang</title> - <p>You can also use Dialyzer directly from Erlang. Both the GUI and the - command line versions are available. The options are similar to the ones - given from the command line, so please refer to the sections above for - a description of these.</p> + <title>Using Dialyzer from Erlang</title> + <p>Dialyzer can be used directly from Erlang. Both the GUI and the + command-line versions are also available. The options are similar to the + ones given from the command line, see section + <seealso marker="#command_line"> + Using Dialyzer from the Command Line</seealso>.</p> </section> <section> <marker id="suppression"></marker> <title>Requesting or Suppressing Warnings in Source Files</title> - <p> - The <c>-dialyzer()</c> attribute can be used for turning off + <p>Attribute <c>-dialyzer()</c> can be used for turning off warnings in a module by specifying functions or warning options. For example, to turn off all warnings for the function - <c>f/0</c>, include the following line: - </p> -<code type="none"> --dialyzer({nowarn_function, f/0}). -</code> + <c>f/0</c>, include the following line:</p> + + <code type="none"> +-dialyzer({nowarn_function, f/0}).</code> + <p>To turn off warnings for improper lists, add the following line - to the source file: - </p> -<code type="none"> --dialyzer(no_improper_lists). -</code> - <p>The <c>-dialyzer()</c> attribute is allowed after function - declarations. Lists of warning options or functions are allowed: - </p> -<code type="none"> --dialyzer([{nowarn_function, [f/0]}, no_improper_lists]). -</code> - <p> - Warning options can be restricted to functions: - </p> -<code type="none"> --dialyzer({no_improper_lists, g/0}). -</code> -<code type="none"> --dialyzer({[no_return, no_match], [g/0, h/0]}). -</code> - <p> - For help on the warning options use <c>dialyzer -Whelp</c>. The - options are also enumerated <seealso - marker="#gui/1">below</seealso> (<c>WarnOpts</c>). - </p> - <note> - <p> - The <c>-dialyzer()</c> attribute is not checked by the Erlang - Compiler, but by the Dialyzer itself. - </p> - </note> + to the source file:</p> + + <code type="none"> +-dialyzer(no_improper_lists).</code> + + <p>Attribute <c>-dialyzer()</c> is allowed after function + declarations. Lists of warning options or functions are allowed:</p> + + <code type="none"> +-dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).</code> + + <p>Warning options can be restricted to functions:</p> + + <code type="none"> +-dialyzer({no_improper_lists, g/0}).</code> + + <code type="none"> +-dialyzer({[no_return, no_match], [g/0, h/0]}).</code> + + <p>For help on the warning options, use <c>dialyzer -Whelp</c>. The + options are also enumerated, see function <seealso marker="#gui/1"> + <c>gui/1</c></seealso> below (<c>WarnOpts</c>).</p> + <note> - <p> - The warning option <c>-Wrace_conditions</c> has no effect when - set in source files. - </p> + <p>Warning option <c>-Wrace_conditions</c> has no effect when + set in source files.</p> </note> - <p> - The <c>-dialyzer()</c> attribute can also be used for turning on - warnings. For instance, if a module has been fixed regarding - unmatched returns, adding the line - </p> -<code type="none"> --dialyzer(unmatched_returns). -</code> - <p> - can help in assuring that no new unmatched return warnings are - introduced. - </p> + + <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 + that no new unmatched return warnings are introduced:</p> + + <code type="none"> +-dialyzer(unmatched_returns).</code> </section> <funcs> <func> + <name>format_warning(Msg) -> string()</name> + <fsummary>Get the string version of a warning message.</fsummary> + <type> + <v>Msg = {Tag, Id, msg()}</v> + <d>See <c>run/1</c>.</d> + </type> + <desc> + <p>Get a string from warnings as returned by + <seealso marker="#run/1"><c>run/1</c></seealso>.</p> + </desc> + </func> + + <func> <name>gui() -> ok | {error, Msg}</name> <name>gui(OptList) -> ok | {error, Msg}</name> - <fsummary>Dialyzer GUI version</fsummary> + <fsummary>Dialyzer GUI version.</fsummary> <type> - <v>OptList -- see below</v> + <v>OptList</v> + <d>See below.</d> </type> <desc> <p>Dialyzer GUI version.</p> @@ -368,9 +499,12 @@ OptList :: [Option] Option :: {files, [Filename :: string()]} | {files_rec, [DirName :: 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 + | {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()} @@ -383,76 +517,71 @@ Option :: {files, [Filename :: string()]} | {warnings, [WarnOpts]} | {get_warnings, bool()} -WarnOpts :: no_return - | no_unused - | no_improper_lists +WarnOpts :: error_handling + | no_behaviours + | no_contracts + | no_fail_call | no_fun_app + | no_improper_lists | no_match + | no_missing_calls | no_opaque - | no_fail_call - | no_contracts - | no_behaviours + | no_return | no_undefined_callbacks - | unmatched_returns - | error_handling + | no_unused | race_conditions - | overspecs | underspecs - | specdiffs - | unknown</code> + | unknown + | unmatched_returns + | overspecs + | specdiffs</code> </desc> </func> + <func> - <name>run(OptList) -> Warnings</name> - <fsummary>Dialyzer command line version</fsummary> - <type> - <v>OptList -- see gui/0,1</v> - <v>Warnings -- see below </v> - </type> + <name>plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}</name> + <fsummary>Return information about the specified PLT.</fsummary> <desc> - <p>Dialyzer command line version.</p> - <code type="none"> -Warnings :: [{Tag, Id, Msg}] -Tag :: 'warn_behaviour' - | 'warn_bin_construction' - | 'warn_callgraph' - | 'warn_contract_not_equal' - | 'warn_contract_range' - | 'warn_contract_subtype' - | 'warn_contract_supertype' - | 'warn_contract_syntax' - | 'warn_contract_types' - | 'warn_failing_call' - | 'warn_fun_app' - | 'warn_matching' - | 'warn_non_proper_list' - | 'warn_not_called' - | 'warn_opaque' - | 'warn_race_condition' - | 'warn_return_no_exit' - | 'warn_return_only_exit' - | 'warn_umatched_return' - | 'warn_undefined_callbacks' - | 'warn_unknown' -Id = {File :: string(), Line :: integer()} -Msg = msg() -- Undefined</code> + <p>Returns information about the specified PLT.</p> </desc> </func> + <func> - <name>format_warning(Msg) -> string()</name> - <fsummary>Get the string version of a warning message.</fsummary> + <name>run(OptList) -> Warnings</name> + <fsummary>Dialyzer command-line version.</fsummary> <type> - <v>Msg = {Tag, Id, msg()} -- See run/1</v> + <v>OptList</v> + <d>See <c>gui/0,1</c>.</d> + <v>Warnings</v> + <d>See below.</d> </type> <desc> - <p>Get a string from warnings as returned by dialyzer:run/1.</p> - </desc> - </func> - <func> - <name>plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}</name> - <fsummary>Returns information about the specified plt.</fsummary> - <desc> - <p>Returns information about the specified plt.</p> + <p>Dialyzer command-line version.</p> + <code type="none"> +Warnings :: [{Tag, Id, Msg}] +Tag :: 'warn_behaviour' + | 'warn_bin_construction' + | 'warn_callgraph' + | 'warn_contract_not_equal' + | 'warn_contract_range' + | 'warn_contract_subtype' + | 'warn_contract_supertype' + | 'warn_contract_syntax' + | 'warn_contract_types' + | 'warn_failing_call' + | 'warn_fun_app' + | 'warn_matching' + | 'warn_non_proper_list' + | 'warn_not_called' + | 'warn_opaque' + | 'warn_race_condition' + | 'warn_return_no_exit' + | 'warn_return_only_exit' + | 'warn_umatched_return' + | 'warn_undefined_callbacks' + | 'warn_unknown' +Id = {File :: string(), Line :: integer()} +Msg = msg() -- Undefined</code> </desc> </func> </funcs> diff --git a/lib/dialyzer/doc/src/dialyzer_chapter.xml b/lib/dialyzer/doc/src/dialyzer_chapter.xml index 9bfb7ea2e1..b5acf3732e 100644 --- a/lib/dialyzer/doc/src/dialyzer_chapter.xml +++ b/lib/dialyzer/doc/src/dialyzer_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,196 +25,211 @@ <title>Dialyzer</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> <file>dialyzer_chapter.xml</file> </header> <section> <title>Introduction</title> - <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies - such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules - or entire (sets of) applications.</p> - </section> - - <section> - <title>Using the Dialyzer from the GUI</title> - <section> - <title>Choosing the applications or modules</title> - <p>In the "File" window you will find a listing of the current directory. - Click your way to the directories/modules you want to add or type the - correct path in the entry.</p> - <p>Mark the directories/modules you want to analyze for discrepancies and - click "Add". You can either add the <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-files directly, or - you can add directories that contain these kinds of files. Note that - you are only allowed to add the type of files that can be analyzed in - the current mode of operation (see below), and that you cannot mix - <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-files.</p> + <title>Scope</title> + <p>Dialyzer is a static analysis tool that identifies software + discrepancies, such as definite type errors, code that has become dead + or unreachable because of programming error, and unnecessary tests, + in single Erlang modules or entire (sets of) applications.</p> + + <p>Dialyzer can be called from the command line, from Erlang, + and from a GUI.</p> </section> <section> - <title>The analysis modes</title> - <p>Dialyzer has two modes of analysis, "Byte Code" or "Source Code". - These are controlled by the buttons in the top-middle part of the - main window, under "Analysis Options".</p> - </section> - - <section> - <title>Controlling the discrepancies reported by the Dialyzer</title> - <p>Under the "Warnings" pull-down menu, there are buttons that control - which discrepancies are reported to the user in the "Warnings" window. - By clicking on these buttons, one can enable/disable a whole class of - warnings. Information about the classes of warnings can be found on - the "Warnings" item under the "Help" menu (at the rightmost top corner).</p> - <p>If modules are compiled with inlining, spurious warnings may be emitted. - In the "Options" menu you can choose to ignore inline-compiled modules - when analyzing byte code. When starting from source code this is not a - problem since the inlining is explicitly turned off by Dialyzer. The - option causes Dialyzer to suppress all warnings from inline-compiled - modules, since there is currently no way for Dialyzer to find what - parts of the code have been produced by inlining. </p> + <title>Prerequisites</title> + <p>It is assumed that the reader is familiar with the Erlang programming + language.</p> </section> + </section> - <section> - <title>Running the analysis</title> - <p>Once you have chosen the modules or directories you want to analyze, - click the "Run" button to start the analysis. If for some reason you - want to stop the analysis while it is running, push the "Stop" button.</p> - <p>The information from the analysis will be displayed in the Log and the - Warnings windows.</p> - </section> + <section> + <marker id="plt"/> + <title>The Persistent Lookup Table</title> + <p>Dialyzer stores the result of an analysis in a Persistent + Lookup Table (PLT). The PLT can then be used as a starting + point for later analyses. It is recommended to build a PLT with the + Erlang/OTP applications that you are using, but also to include your + own applications that you are using frequently.</p> + + <p>The PLT is built using option <c>--build_plt</c> to Dialyzer. + The following command builds the recommended minimal PLT for + Erlang/OTP:</p> - <section> - <title>Include directories and macro definitions</title> - <p>When analyzing from source you might have to supply Dialyzer with a - list of include directories and macro definitions (as you can do with - the <c><![CDATA[erlc]]></c> flags <c><![CDATA[-I]]></c> and <c><![CDATA[-D]]></c>). This can be done either by starting Dialyzer - with these flags from the command line as in:</p> - <code type="none"> + <code type="none"> +dialyzer --build_plt --apps erts kernel stdlib mnesia</code> - dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir - </code> - <p>or by adding these explicitly using the "Manage Macro Definitions" or - "Manage Include Directories" sub-menus in the "Options" menu.</p> - </section> + <p>Dialyzer looks if there is an environment variable called + <c>DIALYZER_PLT</c> and places the PLT at this location. If no such + variable is set, Dialyzer places the PLT at + <c>$HOME/.dialyzer_plt</c>. The placement can also be specified using + the options <c>--plt</c> or <c>--output_plt</c>.</p> - <section> - <title>Saving the information on the Log and Warnings windows</title> - <p>In the "File" menu there are options to save the contents of the Log - and the Warnings window. Just choose the options and enter the file to - save the contents in.</p> - <p>There are also buttons to clear the contents of each window.</p> - </section> + <p>Information can be added to an existing PLT using option + <c>--add_to_plt</c>. If you also want to include the Erlang compiler in + the PLT and place it in a new PLT, then use the following command:</p> - <section> - <title>Inspecting the inferred types of the analyzed functions</title> - <p>Dialyzer stores the information of the analyzed functions in a - Persistent Lookup Table (PLT). After an analysis you can inspect this - information. In the PLT menu you can choose to either search the PLT - or inspect the contents of the whole PLT. The information is presented - in edoc format.</p> - </section> - </section> + <code type="none"> +dialyzer --add_to_plt --apps compiler --output_plt my.plt</code> - <section> - <title>Using the Dialyzer from the command line</title> - <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p> - </section> + <p>Then you can add your favorite application my_app to the new + PLT:</p> - <section> - <title>Using the Dialyzer from Erlang</title> - <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p> - </section> + <code type="none"> +dialyzer --add_to_plt --plt my.plt -r my_app/ebin</code> - <section> - <title>More on the Persistent Lookup Table (PLT)</title> + <p>But you realize that it is unnecessary to have the Erlang compiler in this + one:</p> - <p> The persistent lookup table, or PLT, is used to store the - result of an analysis. The PLT can then be used as a starting - point for later analyses. It is recommended to build a PLT with - the otp applications that you are using, but also to include your - own applications that you are using frequently.</p> + <code type="none"> +dialyzer --remove_from_plt --plt my.plt --apps compiler</code> - <p>The PLT is built using the --build_plt option to dialyzer. The - following command builds the recommended minimal PLT for OTP.</p> + <p>Later, when you have fixed a bug in your application my_app, + you want to update the PLT so that it becomes fresh the next time + you run Dialyzer. In this case, run the following command:</p> <code type="none"> +dialyzer --check_plt --plt my.plt</code> - dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin\ - $ERL_TOP/lib/kernel/ebin \ - $ERL_TOP/lib/mnesia/ebin - </code> + <p>Dialyzer then reanalyzes the changed files + and the files that depend on these files. Notice that this + consistency check is performed automatically the next time you + run Dialyzer with this PLT. Option <c>--check_plt</c> is only + for doing so without doing any other analysis.</p> - <p>Dialyzer will look if there is an environment variable called - $DIALYZER_PLT and place the PLT at this location. If no such - variable is set, Dialyzer will place the PLT at - $HOME/.dialyzer_plt. The placement can also be specified using the - --plt, or --output_plt options.</p> - - <p>You can also add information to an existing plt using the - --add_to_plt option. Suppose you want to also include the compiler - in the PLT and place it in a new PLT, then give the command</p> + <p>To get information about a PLT, use the following option:</p> <code type="none"> +dialyzer --plt_info</code> - dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt - </code> + <p>To specify which PLT, use option <c>--plt</c>.</p> - <p>Then you would like to add your favorite application my_app to - the new plt.</p> + <p>To get the output printed to a file, use option <c>--output_file</c>.</p> - <code type="none"> + <p>Notice that when manipulating the PLT, no warnings are + emitted. To turn on warnings during (re)analysis of the PLT, use + option <c>--get_warnings</c>.</p> + </section> - dialyzer --add_to_plt --plt my.plt -r my_app/ebin - </code> + <section> + <title>Using Dialyzer from the Command Line</title> + <p>Dialyzer has a command-line version for automated use. + See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p> + </section> - <p>But you realize that it is unnecessary to have compiler in this one.</p> + <section> + <title>Using Dialyzer from Erlang</title> + <p>Dialyzer can also be used directly from Erlang. + See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p> + </section> - <code type="none"> + <section> + <marker id="dialyzer_gui"/> + <title>Using Dialyzer from the GUI</title> + <section> + <title>Choosing the Applications or Modules</title> + <p>The <em>File</em> window displays a listing of the current directory. + Click your way to the directories/modules you want to add or type the + correct path in the entry.</p> - dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin - </code> + <p>Mark the directories/modules you want to analyze for discrepancies and + click <em>Add</em>. You can either add the <c>.beam</c> and + <c>.erl</c> files directly, or add directories that contain + these kind of files. Notice that + you are only allowed to add the type of files that can be analyzed in + the current mode of operation (see below), and that you cannot mix + <c>.beam</c> and <c>.erl</c> files.</p> + </section> - <p> Later, when you have fixed a bug in your application my_app, - you want to update the plt so that it will be fresh the next time - you run Dialyzer, run the command</p> + <section> + <title>Analysis Modes</title> + <p>Dialyzer has two analysis modes: "Byte Code" and "Source Code". + They are controlled by the buttons in the top-middle part of the + main window, under <em>Analysis Options</em>.</p> + </section> - <code type="none"> + <section> + <title>Controlling the Discrepancies Reported by Dialyzer</title> + <p>Under the <em>Warnings</em> pull-down menu, there are buttons that + control which discrepancies are reported to the user in the + <em>Warnings</em> window. By clicking these buttons, you can + enable/disable a whole class of warnings. Information about the classes + of warnings is found on the "Warnings" item under the <em>Help</em> + menu (in the rightmost top corner).</p> + + <p>If modules are compiled with inlining, spurious warnings can be + emitted. In the <em>Options</em> menu you can choose to ignore + inline-compiled modules when analyzing byte code. + When starting from source code, this is not a problem because + inlining is explicitly turned off by Dialyzer. The option causes + Dialyzer to suppress all warnings from inline-compiled + modules, as there is currently no way for Dialyzer to find what + parts of the code have been produced by inlining.</p> + </section> - dialyzer --check_plt --plt my.plt - </code> + <section> + <title>Running the Analysis</title> + <p>Once you have chosen the modules or directories you want to analyze, + click the <em>Run</em> button to start the analysis. If you for some + reason want to stop the analysis while it is running, click the + <em>Stop</em> button.</p> - <p> Dialyzer will then reanalyze the files that have been changed, - and the files that depend on these files. Note that this - consistency check will be performed automatically the next time - you run Dialyzer with this plt. The --check_plt option is merely - for doing so without doing any other analysis.</p> + <p>The information from the analysis is displayed in the <em>Log</em> + window and the <em>Warnings</em> window.</p> + </section> - <p> To get some information about a plt use the option</p> - <code type="none"> + <section> + <title>Include Directories and Macro Definitions</title> + <p>When analyzing from source, you might have to supply Dialyzer + with a list of include directories and macro definitions (as you can do + with the <seealso marker="erts:erlc"><c>erlc</c></seealso> flags + <c>-I</c> and <c>-D</c>). This can be done + either by starting Dialyzer with these flags from the command + line as in:</p> + + <code type="none"> +dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir</code> - dialyzer --plt_info - </code> + <p>or by adding these explicitly using submenu + <em>Manage Macro Definitions</em> or + <em>Manage Include Directories</em> in the <em>Options</em> menu.</p> + </section> - <p>You can also specify which plt with the --plt option, and get the - output printed to a file with --output_file</p> + <section> + <title>Saving the Information on the Log and Warnings Windows</title> + <p>The <em>File</em> menu includes options to save the contents of the + <em>Log</em> window and the <em>Warnings</em> window. Simply choose the + options and enter the file to save the contents in.</p> - <p>Note that when manipulating the plt, no warnings are - emitted. To turn on warnings during (re)analysis of the plt, use - the option --get_warnings.</p> + <p>There are also buttons to clear the contents of each window.</p> + </section> + <section> + <title>Inspecting the Inferred Types of the Analyzed Functions</title> + <p>Dialyzer stores the information of the analyzed functions in a + Persistent Lookup Table (PLT), see section + <seealso marker="#plt">The Persistent Lookup Table</seealso>.</p> + + <p>After an analysis, you can inspect this information. + In the <em>PLT</em> menu you can choose to either search the PLT + or inspect the contents of the whole PLT. The information is presented + in <seealso marker="edoc:edoc"><c>EDoc</c></seealso> format.</p> + </section> </section> <section> - <title>Feedback and bug reports</title> - <p>At this point, we very much welcome user feedback (even wish-lists!). - If you notice something weird, especially if the Dialyzer reports any - discrepancy that is a false positive, please send an error report - describing the symptoms and how to reproduce them to:</p> - <code type="none"><![CDATA[ - ]]></code> + <title>Feedback and Bug Reports</title> + <p>We very much welcome user feedback - even wishlists! + If you notice anything weird, especially if Dialyzer reports + any discrepancy that is a false positive, please send an error report + describing the symptoms and how to reproduce them.</p> </section> </chapter> diff --git a/lib/dialyzer/doc/src/fascicules.xml b/lib/dialyzer/doc/src/fascicules.xml deleted file mode 100644 index 37feca543f..0000000000 --- a/lib/dialyzer/doc/src/fascicules.xml +++ /dev/null @@ -1,18 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> - -<fascicules> - <fascicule file="part" href="part_frame.html" entry="no"> - User's Guide - </fascicule> - <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> - Reference Manual - </fascicule> - <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> - Release Notes - </fascicule> - <fascicule file="" href="../../../../doc/print.html" entry="no"> - Off-Print - </fascicule> -</fascicules> - diff --git a/lib/dialyzer/doc/src/note.gif b/lib/dialyzer/doc/src/note.gif Binary files differdeleted file mode 100644 index 6fffe30419..0000000000 --- a/lib/dialyzer/doc/src/note.gif +++ /dev/null diff --git a/lib/dialyzer/doc/src/notes.xml b/lib/dialyzer/doc/src/notes.xml index 93d3b09f07..8d11252bff 100644 --- a/lib/dialyzer/doc/src/notes.xml +++ b/lib/dialyzer/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,6 +32,498 @@ <p>This document describes the changes made to the Dialyzer application.</p> +<section><title>Dialyzer 3.2.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix bugs concerning <c>erlang:abs/1</c> and + <c>erlang:bsl/2</c>. </p> + <p> + Own Id: OTP-14858 Aux Id: ERL-551 </p> + </item> + <item> + <p> Fix a bug that caused Dialyzer to crash instead of + emitting a warning. </p> + <p> + Own Id: OTP-14911</p> + </item> + <item> + <p> Fix a bug concerning parameterized opaque types. </p> + <p> + Own Id: OTP-14925 Aux Id: ERL-565 </p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.2.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> The error message returned from Dialyzer when, for + example, a modified record field type is not a subtype of + the declared type, no longer includes a call stack. The + bug was introduced in Erlang/OTP 19.3. </p> + <p> + Own Id: OTP-14742</p> + </item> + <item> + <p> A bug relating to maps and never returning functions + has been fixed. </p> + <p> + Own Id: OTP-14743</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.2.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug regarding map types that caused Dialyzer to + go into an infinite loop. A consequence of the fix is + that compound map keys such as maps and tuples sometimes + are handled with less precision than before. </p> + <p> + Own Id: OTP-14572 Aux Id: seq13319 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + General Unicode improvements.</p> + <p> + Own Id: OTP-14462</p> + </item> + <item> + <p> The check for unknown remote types is improved. </p> + <p> + Own Id: OTP-14606 Aux Id: OTP-14218 </p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug where merging PLT:s could lose info. The + bug was introduced in Erlang/OTP 20.0. </p> + <p> + Own Id: OTP-14558 Aux Id: ERIERL-53 </p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> The check of bad type variables in type declarations + was mistakingly removed in Erlang/OTP 18, and is now + re-introduced. </p> + <p> + Own Id: OTP-14423 Aux Id: OTP-14323 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Analyzing modules with binary construction with huge + strings is now much faster. The compiler also compiles + such modules slightly faster.</p> + <p> + Own Id: OTP-14125 Aux Id: ERL-308 </p> + </item> + <item> + <p> The peak memory consumption is reduced. </p> + <p> + Own Id: OTP-14127</p> + </item> + <item> + <p> Warnings about unknown types are now also generated + for types not used by any function specification. </p> + <p> + Own Id: OTP-14218 Aux Id: OTP-14127 </p> + </item> + <item> + <p>TypEr has been removed as separate application and is + now a part of the Dialyzer application. Documentation for + TypEr has been added in the Dialyzer application.</p> + <p> + Own Id: OTP-14336</p> + </item> + <item> + <p>The format of debug information that is stored in BEAM + files (when <c>debug_info</c> is used) has been changed. + The purpose of the change is to better support other + BEAM-based languages such as Elixir or LFE.</p> + <p>All tools included in OTP (dialyzer, debugger, cover, + and so on) will handle both the new format and the + previous format. Tools that retrieve the debug + information using <c>beam_lib:chunk(Beam, + [abstract_code])</c> will continue to work with both the + new and old format. Tools that call + <c>beam_lib:chunk(Beam, ["Abst"])</c> will not work with + the new format.</p> + <p>For more information, see the description of + <c>debug_info</c> in the documentation for + <c>beam_lib</c> and the description of the + <c>{debug_info,{Backend,Data}}</c> option in the + documentation for <c>compile</c>.</p> + <p> + Own Id: OTP-14369 Aux Id: PR-1367 </p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Report unknown types properly. A bug was introduced + in Erlang/OTP 19.3, where warnings about unknown types + were simply discarded. </p> + <p> + Own Id: OTP-14368</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug concerning parameterized opaque types. </p> + <p> + Own Id: OTP-14130</p> + </item> + <item> + <p> Improve a few warnings. One of them could cause a + crash. </p> + <p> + Own Id: OTP-14177</p> + </item> + <item> + <p>The dialyzer and observer applications will now use a + portable way to find the home directory. That means that + there is no longer any need to manually set the HOME + environment variable on Windows.</p> + <p> + Own Id: OTP-14249 Aux Id: ERL-161 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The peak memory consumption is reduced. </p><p> The + evaluation of huge SCCs in <c>dialyzer_typesig</c> is + optimized. </p><p> Analyzing modules with binary + construction with huge strings is now much faster. </p> + <p> + Own Id: OTP-14126 Aux Id: ERL-308 </p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.0.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix bugs regarding opaque types. </p> + <p> + Own Id: OTP-13693</p> + </item> + <item> + <p> Fix error handling of bad <c>-dialyzer()</c> + attributes. </p> + <p> + Own Id: OTP-13979 Aux Id: ERL-283 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> A few warning messages have been improved. </p> + <p> + Own Id: OTP-11403</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.0.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The translation of forms to types is improved for + opaque types in a few cases. </p> + <p> + Own Id: OTP-13682</p> + </item> + <item> + <p> Add warning suppression to compiler-generated case + statements. Warnings about clauses that cannot match and + are also compiler generated are suppressed unless none of + the clauses return. </p> + <p> + Own Id: OTP-13723 Aux Id: ERL-159, PR-1121 </p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fix a map related bug.</p> + <p> + Own Id: OTP-13709 Aux Id: ERL-177, PR-1115 </p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 3.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug in the translation of forms to types. </p> + <p> + Own Id: OTP-13520</p> + </item> + <item> + <p>Correct misspelling in Dialyzer's acronym definition. + </p> + <p> + Own Id: OTP-13544 Aux Id: PR-1007 </p> + </item> + <item> + <p>Dialyzer no longer crashes when there is an invalid + function call such as <c>42(7)</c> in a module being + analyzed. The compiler will now warn for invalid function + calls such as <c>X = 42, x(7)</c>.</p> + <p> + Own Id: OTP-13552 Aux Id: ERL-138 </p> + </item> + <item> + <p> Fix a bug that caused Dialyzer to go into an infinite + loop. </p> + <p> + Own Id: OTP-13653 Aux Id: ERL-157 </p> + </item> + <item> + <p>Fix a bug in Dialyzer related to call-site + analysis.</p> + <p> + Own Id: OTP-13655 Aux Id: PR-1092 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The evaluation of SCCs in <c>dialyzer_typesig</c> is + optimized. </p> <p> Maps are used instead of Dicts to + further optimize the evaluation. </p> + <p> + Own Id: OTP-10349</p> + </item> + <item> + <p> Since Erlang/OTP R14A, when support for parameterized + modules was added, <c>module()</c> has included + <c>tuple()</c>, but that part is removed; the type + <c>module()</c> is now the same as <c>atom()</c>, as + documented in the Reference Manual. </p> + <p> + Own Id: OTP-13244</p> + </item> + <item> + <p> The type specification syntax for Maps is improved: + </p> <list> <item> <p> The association type <c>KeyType := + ValueType</c> denotes an association that must be + present. </p> </item> <item> <p> The shorthand <c>...</c> + stands for the association type <c>any() => any()</c>. + </p> </item> </list> <p> An incompatible change is that + <c>#{}</c> stands for the empty map. The type + <c>map()</c> (a map of any size) can be written as + <c>#{...}</c>. </p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13542 Aux Id: PR-1014 </p> + </item> + <item> + <p>The translation of forms to types is improved. </p> + <p> + Own Id: OTP-13547</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 2.9</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Dialyzer no longer asserts that files and directories + to be removed from a PLT exist. </p> + <p> + Own Id: OTP-13103 Aux Id: ERL-40 </p> + </item> + <item> + <p> Fix a bug concerning parameterized opaque types. </p> + <p> + Own Id: OTP-13237</p> + </item> + <item> + <p> + Fix pretty printing of Core Maps</p> + <p> + Literal maps could cause Dialyzer to crash when pretty + printing the results.</p> + <p> + Own Id: OTP-13238</p> + </item> + <item> + <p> + If a behavior module contains an non-exported function + with the same name as one of the behavior's callbacks, + the callback info was inadvertently deleted from the PLT + as the <c>dialyzer_plt:delete_list/2</c> function was + cleaning up the callback table.</p> + <p> + Own Id: OTP-13287</p> + </item> + <item> + <p> Correct the contract for <c>erlang:byte_size/1</c> + </p> <p> Correct the handling of comparison operators for + map and bit string operands. </p> + <p> + Own Id: OTP-13312</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Dialyzer recognizes calls to <c>M:F/A</c> where <c>M</c>, + <c>F</c>, and <c>A</c> are all literals.</p> + <p> + Own Id: OTP-13217</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 2.8.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Reintroduce the <c>erlang:make_fun/3</c> BIF in + erl_bif_types.</p> + <p> + Own Id: OTP-13068</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 2.8.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Improve the translation of forms to types. </p> + <p> + Own Id: OTP-12865</p> + </item> + <item> + <p> Fix a bug concerning parameterized opaque types. </p> + <p> + Own Id: OTP-12866</p> + </item> + <item> + <p> Fix a bug concerning parameterized opaque types. </p> + <p> + Own Id: OTP-12940</p> + </item> + <item> + <p> Fix bugs concerning <c>erlang:abs/1</c>. </p> + <p> + Own Id: OTP-12948</p> + </item> + <item> + <p> Fix a bug concerning <c>lists:keydelete/3</c> with + union and opaque types. </p> + <p> + Own Id: OTP-12949</p> + </item> + <item> + <p> + Use new function <c>hipe:erts_checksum</c> to get correct + runtime checksum for cached beam files.</p> + <p> + Own Id: OTP-12964 Aux Id: OTP-12963, OTP-12962 </p> + </item> + </list> + </section> + +</section> + <section><title>Dialyzer 2.8</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -286,7 +778,7 @@ or modifying opaque types within the scope of a module. </p> <p> Hitherto the shape of terms (tuple, list, etc.) has been used to determine the opaque terms, but now the - contracts are used for decorating types with opaqueness. + contracts are used for decorating types with opacity. </p> <p> Own Id: OTP-10397</p> @@ -405,22 +897,28 @@ <p> EEP43: New data type - Maps</p> <p> - With Maps you may for instance: <taglist> <item><c>M0 = - #{ a => 1, b => 2}, % create - associations</c></item> <item><c>M1 = M0#{ a := 10 }, % - update values</c></item> <item><c>M2 = M1#{ "hi" => - "hello"}, % add new associations</c></item> <item><c>#{ - "hi" := V1, a := V2, b := V3} = M2. % match keys with - values</c></item> </taglist></p> + With Maps you may for instance:</p> + <taglist> + <tag/> <item><c>M0 = #{ a => 1, b => 2}, % create + associations</c></item> + <tag/><item><c>M1 = M0#{ a := 10 }, % update values</c></item> + <tag/><item><c>M2 = M1#{ "hi" => + "hello"}, % add new associations</c></item> + <tag/><item><c>#{ "hi" := V1, a := V2, b := V3} = M2. + % match keys with values</c></item> + </taglist> <p> For information on how to use Maps please see Map Expressions in the <seealso marker="doc/reference_manual:expressions#map_expressions"> Reference Manual</seealso>.</p> <p> The current implementation is without the following - features: <taglist> <item>No variable keys</item> - <item>No single value access</item> <item>No map - comprehensions</item> </taglist></p> + features:</p> + <taglist> + <tag/><item>No variable keys</item> + <tag/><item>No single value access</item> + <tag/><item>No map comprehensions</item> + </taglist> <p> Note that Maps is <em>experimental</em> during OTP 17.0.</p> <p> @@ -734,19 +1232,17 @@ Own Id: OTP-9731</p> </item> <item> - <p> <list> <item><p>No warnings for underspecs with remote types</p></item> <item><p> Fix crash in Typer</p></item> <item><p>Fix Dialyzer's warning for its own code</p></item> <item><p>Fix Dialyzer's warnings in HiPE</p></item> <item><p>Add file/line info in a particular Dialyzer crash</p></item> <item><p>Update - inets test results</p></item> </list></p> + inets test results</p></item> </list> <p> Own Id: OTP-9758</p> </item> <item> - <p> <list> <item><p>Correct callback spec in application module</p></item> <item><p>Refine warning about callback specs with extra ranges</p></item> <item><p>Cleanup @@ -757,7 +1253,7 @@ analysis</p></item> <item><p>Fix crash in Dialyzer</p></item> <item><p>Variable substitution was not generalizing any unknown variables.</p></item> - </list></p> + </list> <p> Own Id: OTP-9776</p> </item> @@ -1265,7 +1761,7 @@ <list> <item> <p>The analysis accepts opaque type declarations and - detects violations of opaqueness of terms of such types. + detects violations of opacity of terms of such types. Starting with R13, many Erlang/OTP standard libraries (array, dict, digraph, ets, gb_sets, gb_trees, queue, and sets) contain opaque type declarations of their main data diff --git a/lib/dialyzer/doc/src/part.xml b/lib/dialyzer/doc/src/part.xml index eff8e05257..9bfcf21a66 100644 --- a/lib/dialyzer/doc/src/part.xml +++ b/lib/dialyzer/doc/src/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,12 +25,11 @@ <title>Dialyzer User's Guide</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> <file>part.xml</file> </header> <description> - <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.</p> </description> <xi:include href="dialyzer_chapter.xml"/> </part> diff --git a/lib/dialyzer/doc/src/part_notes.xml b/lib/dialyzer/doc/src/part_notes.xml deleted file mode 100644 index ba8d30e1be..0000000000 --- a/lib/dialyzer/doc/src/part_notes.xml +++ /dev/null @@ -1,37 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>2006</year><year>2013</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>Dialyzer Release Notes</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - <file>part_notes.xml</file> - </header> - <description> - <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.</p> - </description> - <xi:include href="notes.xml"/> -</part> - diff --git a/lib/dialyzer/doc/src/ref_man.xml b/lib/dialyzer/doc/src/ref_man.xml index 9c3887b599..d8cf324232 100644 --- a/lib/dialyzer/doc/src/ref_man.xml +++ b/lib/dialyzer/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,12 +25,12 @@ <title>Dialyzer Reference Manual</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> </header> <description> - <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.</p> </description> <xi:include href="dialyzer.xml"/> + <xi:include href="typer.xml"/> </application> diff --git a/lib/dialyzer/doc/src/typer.xml b/lib/dialyzer/doc/src/typer.xml new file mode 100644 index 0000000000..1cfbe94807 --- /dev/null +++ b/lib/dialyzer/doc/src/typer.xml @@ -0,0 +1,157 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2006</year><year>2017</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>typer</title> + <prepared></prepared> + <docno></docno> + <date>2017-04-13</date> + <rev></rev> + <file>type.xml</file> + </header> + <module>typer</module> + <modulesummary>Typer, a Type annotator for ERlang programs. + </modulesummary> + <description> + <p>TypEr shows type information for Erlang modules to the user. + Additionally, it can annotate the code of files with such type + information.</p> + </description> + + <section> + <marker id="command_line"></marker> + <title>Using TypEr from the Command Line</title> + <p>TypEr is used from the command-line. This section provides a + brief description of the options. The same information can be + obtained by writing the following in a shell:</p> + + <code type="none"> +typer --help</code> + + <p><em>Usage:</em></p> + + <code type="none"> +typer [--help] [--version] [--plt PLT] [--edoc] + [--show | --show-exported | --annotate | --annotate-inc-files] + [-Ddefine]* [-I include_dir]* [-pa dir]* [-pz dir]* + [-T application]* [-r] file*</code> + + <note> + <p>* denotes that multiple occurrences of the option are possible.</p> + </note> + + <p><em>Options:</em></p> + + <taglist> + + <tag><c>--r</c></tag> + <item> + <p>Search directories recursively for .erl files below them.</p> + </item> + <tag><c>--show</c></tag> + <item> + <p>Print type specifications for all functions on stdout. + (This is the default behaviour; this option is not really + needed.)</p> + </item> + + <tag><c>--show-exported</c> (or <c>show_exported</c>)</tag> + <item> + <p>Same as <c>--show</c>, but print specifications for + exported functions only. Specs are displayed sorted + alphabetically on the function's name.</p> + </item> + + <tag><c>--annotate</c></tag> + <item> + <p>Annotate the specified files with type specifications.</p> + </item> + + <tag><c>--annotate-inc-files</c></tag> + <item> + <p>Same as <c>--annotate</c> but annotates all + <c>-include()</c> files as well as all .erl files. (Use this + option with caution - it has not been tested much).</p> + </item> + + <tag><c>--edoc</c></tag> + <item> + <p>Print type information as Edoc <c>@spec</c> comments, not + as type specs.</p> + </item> + + <tag><c>--plt</c></tag> + <item> + <p>Use the specified dialyzer PLT file rather than the default one.</p> + </item> + + <tag><c>-T file*</c></tag> + <item> + <p>The specified file(s) already contain type specifications + and these are to be trusted in order to print specs for the + rest of the files. (Multiple files or dirs, separated by + spaces, can be specified.)</p> + </item> + + <tag><c>-Dname</c> (or <c>-Dname=value</c>)</tag> + <item> + <p>Pass the defined name(s) to TypEr. (**)</p> + </item> + + <tag><c>-I</c></tag> + <item> + <p>Pass the include_dir to TypEr. (**)</p> + </item> + + <tag><c>-pa dir</c></tag> + <item> + <p>Include <c>dir</c> in the path for Erlang. This is useful + when analyzing files that have <c>-include_lib()</c> + directives or use parse transforms.</p> + </item> + + <tag><c>-pz dir</c></tag> + <item> + <p>Include <c>dir</c> in the path for Erlang. This is useful + when analyzing files that have <c>-include_lib()</c> + directives or use parse transforms.</p> + </item> + + <tag><c>--version</c> (or <c>-v</c>)</tag> + <item> + <p>Print the TypEr version and some more information and + exit.</p> + </item> + + </taglist> + + <note> + <p>** options <c>-D</c> and <c>-I</c> work both + from the command line and in the TypEr GUI; the syntax of + defines and includes is the same as that used by + <seealso marker="erts:erlc">erlc(1)</seealso>.</p> + </note> + + </section> + +</erlref> diff --git a/lib/dialyzer/doc/src/warning.gif b/lib/dialyzer/doc/src/warning.gif Binary files differdeleted file mode 100644 index 96af52360e..0000000000 --- a/lib/dialyzer/doc/src/warning.gif +++ /dev/null |
