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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2006</year><year>2016</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</title>
<prepared></prepared>
<docno></docno>
<date>2016-09-19</date>
<rev></rev>
<file>dialyzer_chapter.xml</file>
</header>
<section>
<title>Introduction</title>
<section>
<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>Prerequisites</title>
<p>It is assumed that the reader is familiar with the Erlang programming
language.</p>
</section>
</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>
<code type="none">
dialyzer --build_plt --apps erts kernel stdlib mnesia</code>
<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>
<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>
<code type="none">
dialyzer --add_to_plt --apps compiler --output_plt my.plt</code>
<p>Then you can 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 the Erlang compiler in this
one:</p>
<code type="none">
dialyzer --remove_from_plt --plt my.plt --apps compiler</code>
<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>
<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>To get information about a PLT, use the following option:</p>
<code type="none">
dialyzer --plt_info</code>
<p>To specify which PLT, use option <c>--plt</c>.</p>
<p>To get the output printed to a file, use option <c>--output_file</c>.</p>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>The information from the analysis is displayed in the <em>Log</em>
window and the <em>Warnings</em> window.</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 <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>
<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>
<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>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>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>
|
