← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/dialyzer/doc/manual.txt

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/dialyzer/doc/manual.txt
2
2
## File:      doc/manual.txt
3
3
## Author(s): Tobias Lindahl <tobiasl@it.uu.se>
4
4
##            Kostis Sagonas <kostis@it.uu.se>
5
 
##
6
 
## $Id$
7
5
##----------------------------------------------------------------------------
8
6
 
9
7
The DIALYZER, a DIscrepany AnaLYZer for ERlang programs.
125
123
 
126
124
 
127
125
Usage: dialyzer [--help] [--version] [--shell] [--quiet] [--verbose]
128
 
                [-pa dir]* [--plt plt] [-Ddefine]* [-I include_dir]* 
129
 
                [--output_plt file] [-Wwarn]* [--src] 
130
 
                [-c applications] [-r applications] [-o outfile]
131
 
                [--build_plt] [--add_to_plt] [--remove_from_plt] [--check_plt]
132
 
                [--plt_info] [--get_warnings]
 
126
                [-pa dir]* [--plt plt] [--plts plt*] [-Ddefine]*
 
127
                [-I include_dir]* [--output_plt file] [-Wwarn]*
 
128
                [--src] [--gui | --wx] [files_or_dirs] [-r dirs]
 
129
                [--apps applications] [-o outfile]
 
130
                [--build_plt] [--add_to_plt] [--remove_from_plt]
 
131
                [--check_plt] [--no_check_plt] [--plt_info] [--get_warnings]
 
132
                [--no_native] [--fullpath]
133
133
 
134
134
Options: 
135
 
   -c applications (or --command-line applications)
136
 
       Use Dialyzer from the command line (no GUI) to detect defects in the
137
 
       specified applications (directories or .erl or .beam files)
138
 
   -r applications
139
 
       Same as -c only that directories are searched recursively for 
140
 
       subdirectories containing .erl or .beam files (depending on the 
141
 
       type of analysis)
 
135
   files_or_dirs (for backwards compatibility also as: -c files_or_dirs)
 
136
       Use Dialyzer from the command line to detect defects in the
 
137
       specified files or directories containing .erl or .beam files,
 
138
       depending on the type of the analysis.
 
139
   -r dirs
 
140
       Same as the previous but the specified directories are searched
 
141
       recursively for subdirectories containing .erl or .beam files in
 
142
       them, depending on the type of analysis.
 
143
   --apps applications
 
144
       Option typically used when building or modifying a plt as in:
 
145
         dialyzer --build_plt --apps erts kernel stdlib mnesia ...
 
146
       to conveniently refer to library applications corresponding to the
 
147
       Erlang/OTP installation. However, the option is general and can also
 
148
       be used during analysis in order to refer to Erlang/OTP applications.
 
149
       In addition, file or directory names can also be included, as in:
 
150
         dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam
142
151
   -o outfile (or --output outfile)
143
152
       When using Dialyzer from the command line, send the analysis
144
 
       results in the specified \"outfile\" rather than in stdout
 
153
       results to the specified outfile rather than to stdout.
145
154
   --raw
146
155
       When using Dialyzer from the command line, output the raw analysis
147
156
       results (Erlang terms) instead of the formatted result.
148
157
       The raw format is easier to post-process (for instance, to filter
149
 
       warnings or to output HTML pages)
 
158
       warnings or to output HTML pages).
150
159
   --src
151
 
       Override the default, which is to analyze BEAM bytecode, and
152
 
       analyze starting from Erlang source code instead
 
160
       Override the default, which is to analyze BEAM files, and
 
161
       analyze starting from Erlang source code instead.
153
162
   -Dname (or -Dname=value)
154
 
       When analyzing from source, pass the define to Dialyzer (**)
 
163
       When analyzing from source, pass the define to Dialyzer. (**)
155
164
   -I include_dir
156
 
       When analyzing from source, pass the include_dir to Dialyzer (**)
 
165
       When analyzing from source, pass the include_dir to Dialyzer. (**)
 
166
   -pa dir
 
167
       Include dir in the path for Erlang (useful when analyzing files
 
168
       that have '-include_lib()' directives).
157
169
   --output_plt file
158
 
       Store the plt at the specified file after building it
 
170
       Store the plt at the specified file after building it.
159
171
   --plt plt
160
172
       Use the specified plt as the initial plt (if the plt was built 
161
 
       during setup the files will be checked for consistency)
162
 
   -pa dir
163
 
       Include dir in the path for Erlang (useful when analyzing files
164
 
       that have '-include_lib()' directives)
 
173
       during setup the files will be checked for consistency).
 
174
   --plts plt*
 
175
      Merge the specified plts to create the initial plt -- requires
 
176
      that the plts are disjoint (i.e., do not have any module
 
177
      appearing in more than one plt).
 
178
      The plts are created in the usual way:
 
179
        dialyzer --build_plt --output_plt plt_1 files_to_include
 
180
        ...
 
181
        dialyzer --build_plt --output_plt plt_n files_to_include
 
182
      and then can be used in either of the following ways:
 
183
        dialyzer files_to_analyze --plts plt_1 ... plt_n
 
184
      or:
 
185
        dialyzer --plts plt_1 ... plt_n -- files_to_analyze
 
186
      (Note the -- delimiter in the second case)
165
187
   -Wwarn
166
188
       A family of options which selectively turn on/off warnings
167
 
       (for help on the names of warnings use dialyzer -Whelp)
 
189
       (for help on the names of warnings use dialyzer -Whelp).
168
190
   --shell
169
 
       Do not disable the Erlang shell while running the GUI
 
191
       Do not disable the Erlang shell while running the GUI.
170
192
   --version (or -v)
171
 
       Prints the Dialyzer version and some more information and exits
 
193
       Print the Dialyzer version and some more information and exit.
172
194
   --help (or -h)
173
 
       Prints this message and exits
 
195
       Print this message and exit.
174
196
   --quiet (or -q)
175
 
       Makes Dialyzer a bit more quiet
 
197
       Make Dialyzer a bit more quiet.
176
198
   --verbose
177
 
       Makes Dialyzer a bit more verbose
 
199
       Make Dialyzer a bit more verbose.
178
200
   --build_plt
179
201
       The analysis starts from an empty plt and creates a new one from the
180
202
       files specified with -c and -r. Only works for beam files.
181
203
       Use --plt or --output_plt to override the default plt location.
182
204
   --add_to_plt
183
205
       The plt is extended to also include the files specified with -c and -r.
184
 
       Use --plt to specify wich plt to start from, and --output_plt to 
 
206
       Use --plt to specify which plt to start from, and --output_plt to
185
207
       specify where to put the plt. Note that the analysis might include 
186
208
       files from the plt if they depend on the new files. 
187
209
       This option only works with beam files.
190
212
       from the plt. Note that this may cause a re-analysis of the remaining
191
213
       dependent files.
192
214
   --check_plt
193
 
       Checks the plt for consistency and rebuilds it if it is not up-to-date.
 
215
       Check the plt for consistency and rebuild it if it is not up-to-date.
194
216
   --no_check_plt
195
217
       Skip the plt check when running Dialyzer. Useful when working with
196
218
       installed plts that never change.
197
219
   --plt_info
198
 
       Makes Dialyzer print information about the plt and then quit. The plt 
199
 
       can be specified with --plt.
 
220
       Make Dialyzer print information about the plt and then quit. The plt
 
221
       can be specified with --plt(s).
200
222
   --get_warnings
201
 
       Makes Dialyzer emit warnings even when manipulating the plt. Only 
202
 
       emits warnings for files that are actually analyzed.
 
223
       Make Dialyzer emit warnings even when manipulating the plt. Warnings
 
224
       are only emitted for files that are actually analyzed.
 
225
   --dump_callgraph file
 
226
       Dump the call graph into the specified file whose format is determined
 
227
       by the file name extension. Supported extensions are: raw, dot, and ps.
 
228
       If something else is used as file name extension, default format '.raw'
 
229
       will be used.
 
230
   --no_native (or -nn)
 
231
       Bypass the native code compilation of some key files that Dialyzer
 
232
       heuristically performs when dialyzing many files; this avoids the
 
233
       compilation time but it may result in (much) longer analysis time.
 
234
  --fullpath
 
235
      Display the full path names of files for which warnings are emitted.
 
236
   --gui
 
237
       Use the gs-based GUI.
 
238
   --wx
 
239
       Use the wx-based GUI.
203
240
 
204
241
Note:
205
242
  * denotes that multiple occurrences of these options are possible.
213
250
     Suppress warnings for unused functions.
214
251
  -Wno_improper_lists
215
252
     Suppress warnings for construction of improper lists.
 
253
  -Wno_tuple_as_fun
 
254
     Suppress warnings for using tuples instead of funs.
216
255
  -Wno_fun_app
217
256
     Suppress warnings for fun applications that will fail.
218
257
  -Wno_match
219
258
     Suppress warnings for patterns that are unused or cannot match.
 
259
  -Wno_opaque
 
260
     Suppress warnings for violations of opaqueness of data types.
220
261
  -Wunmatched_returns ***
221
 
     Include warnings for function calls which ignore the return value(s).
 
262
     Include warnings for function calls which ignore a structured return
 
263
     value or do not match against one of many possible return value(s).
222
264
  -Werror_handling ***
223
265
     Include warnings for functions that only return by means of an exception.
 
266
  -Wrace_conditions ***
 
267
     Include warnings for possible race conditions.
 
268
  -Wbehaviours ***
 
269
     Include warnings about behaviour callbacks which drift from the published
 
270
     recommended interfaces.
224
271
  -Wunderspecs ***
225
272
     Warn about underspecified functions 
226
 
     (the -spec is strictly more allowing than the success typing)
 
273
     (those whose -spec is strictly more allowing than the success typing).
 
274
 
 
275
The following options are also available but their use is not recommended:
 
276
(they are mostly for Dialyzer developers and internal debugging)
227
277
  -Woverspecs ***
228
278
     Warn about overspecified functions 
229
 
     (the -spec is strictly less allowing than the success typing)
 
279
     (those whose -spec is strictly less allowing than the success typing).
230
280
  -Wspecdiffs ***
231
 
     Warn when the -spec is different than the success typing
 
281
     Warn when the -spec is different than the success typing.
232
282
 
233
283
Note:
234
 
   *** These are options that turn on warnings rather than turning them off.
 
284
   *** Identifies options that turn on warnings rather than turning them off.
235
285
 
236
286
 
237
287
-----------------------------------------------
268
318
          | {defines,        [{Macro :: atom(), Value :: term()}]}
269
319
          | {from,           src_code | byte_code} %% Defaults to byte_code
270
320
          | {init_plt,       FileName :: string()} %% If changed from default
 
321
          | {plts,           [FileName :: string()]} %% If changed from default
271
322
          | {include_dirs,   [DirName :: string()]} 
272
323
          | {output_file,    FileName :: string()}
273
324
          | {output_plt,     FileName :: string()}
274
 
          | {analysis_type,  'success_typings' | 'plt_add' |
 
325
          | {analysis_type,  'succ_typings' | 'plt_add' |
275
326
                             'plt_build' | 'plt_check' | 'plt_remove'}
276
327
          | {warnings,       [WarnOpts]}
277
328
 
307
358
The PLT is built using the --build_plt option to dialyzer. The
308
359
following command builds the recommended minimal PLT for OTP.
309
360
 
310
 
dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin\
311
 
                        $ERL_TOP/lib/kernel/ebin\
312
 
                        $ERL_TOP/lib/mnesia/ebin
 
361
   dialyzer --build_plt --apps erts kernel stdlib mnesia
313
362
 
314
363
Dialyzer will look if there is an environment variable called
315
364
$DIALYZER_PLT and place the PLT at this location. If no such variable
321
370
option. Suppose you want to also include the compiler in the PLT and
322
371
place it in a new PLT, then give the command
323
372
 
324
 
dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt
 
373
  dialyzer --add_to_plt --apps compiler --output_plt my.plt
325
374
 
326
375
Then you would like to add your favorite application my_app to the new
327
376
plt.
328
377
 
329
 
dialyzer --add_to_plt --plt my.plt -r <path>/my_app/ebin
 
378
  dialyzer --add_to_plt --plt my.plt -r <path>/my_app/ebin
330
379
 
331
380
But you realize that it is unnecessary to have compiler in this one.
332
381
 
333
 
dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin
 
382
  dialyzer --remove_from_plt --plt my.plt ---apps compiler
334
383
 
335
384
Later, when you have fixed a bug in your application my_app, you want
336
385
to update the plt so that it will be fresh the next time you run
337
386
Dialyzer, run the command
338
387
 
339
 
dialyzer --check_plt --plt my.plt
 
388
  dialyzer --check_plt --plt my.plt
340
389
 
341
390
Dialyzer will then reanalyze the files that have been changed, and the
342
391
files that depend on these files. Note that this consistency check