aboutsummaryrefslogtreecommitdiffstats
path: root/lib/dialyzer/doc/src/dialyzer_chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/dialyzer/doc/src/dialyzer_chapter.xml')
-rw-r--r--lib/dialyzer/doc/src/dialyzer_chapter.xml217
1 files changed, 217 insertions, 0 deletions
diff --git a/lib/dialyzer/doc/src/dialyzer_chapter.xml b/lib/dialyzer/doc/src/dialyzer_chapter.xml
new file mode 100644
index 0000000000..d15069991e
--- /dev/null
+++ b/lib/dialyzer/doc/src/dialyzer_chapter.xml
@@ -0,0 +1,217 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2006</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Dialyzer</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></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>
+ </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>
+ </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>
+ <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">
+
+ 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>
+
+ <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>
+
+ <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>
+
+ <section>
+ <title>Using the Dialyzer from the command line</title>
+ <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p>
+ </section>
+
+ <section>
+ <title>Using the Dialyzer from Erlang</title>
+ <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p>
+ </section>
+
+ <section>
+ <title>More on the Persistent Lookup Table (PLT)</title>
+
+ <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>
+
+ <p>The PLT is built using the --build_plt option to dialyzer. The
+ following command builds the recommended minimal PLT for OTP.</p>
+
+ <code type="none">
+
+ dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin $ERL_TOP/lib/kernel/ebin $ERL_TOP/lib/mnesia/ebin
+ </code>
+
+ <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>
+
+ <code type="none">
+
+ dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt
+ </code>
+
+ <p>Then you would like to add your favorite application my_app to
+ the new plt.</p>
+
+ <code type="none">
+
+ dialyzer --add_to_plt --plt my.plt -r my_app/ebin
+ </code>
+
+ <p>But you realize that it is unnecessary to have compiler in this one.</p>
+
+ <code type="none">
+
+ dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin
+ </code>
+
+ <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>
+
+ <code type="none">
+
+ dialyzer --check_plt --plt my.plt
+ </code>
+
+ <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> To get some information about a plt use the option</p>
+ <code type="none">
+
+ dialyzer --plt_info
+ </code>
+
+ <p>You can also specify which plt with the --plt option, and get the
+ output printed to a file with --output_file</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>
+
+ </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>
+ </section>
+</chapter>
+