1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2006</year><year>2013</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[
[email protected], [email protected]
]]></code>
</section>
</chapter>
|
