manual.txt

OTP是开放电信平台的简称

##----------------------------------------------------------------------------
## File:      doc/manual.txt
## Author(s): Tobias Lindahl <[e-mail]>
##	      Kostis Sagonas <[e-mail]>
##
## $Id$
##----------------------------------------------------------------------------

The DIALYZER, a DIscrepany AnaLYZer for ERlang programs.


-----------------------------------------------
--
-- Using the Dialyzer from the GUI
--
-----------------------------------------------

Choosing the applications or modules
====================================

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.

Mark the directories/modules you want to analyze for discrepancies and
click "Add". You can either add the .beam and .erl-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
.beam and .erl-files.

The analysis modes
==================
Dialyzer has several modes of analysis. These are controlled by the
buttons in the top-middle part of the main window, under "Analysis Options".

The parameters are:
* File Type:
    - Byte code:
	The analysis starts from .beam bytecode files.
	The files must be compiled with +debug_info. If this is not 
	the case you must provide the option --old_style to Dialyzer. 
	Note that this analysis is more imprecise, so we strongly recommend
	compiling with +debug_info.
    - Source code:
	The analysis starts from .erl files. 

* Analysis:
    - Dataflow:
        Use a dataflow analysis to find discrepancies. This analysis mode
        is more precise than previous versions of Dialyzer. It also provides
        file and line number information.
    - Success Typings:
        A significantly stronger analysis that finds more discrepancies than
        dataflow. However, it takes 2 to 2.5 times longer time, and can also
        give warnings that might be harder to interpret, even though they are
        still correct.
    - Old Style:
        For those that need to analyze beam files that have not been compiled
        with +debug_info, this mode provides analysis in the idiom of older 
        versions of Dialyzer.

Controlling the discrepancies reported by the Dialyzer
======================================================
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).

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. 


Running the analysis
====================
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.

The information from the analysis will be displayed in the Log and the
Warnings windows.


Include directories and macro definitions
=========================================
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 erlc flags -I and -D). This can be done either by starting Dialyzer
with these flags from the command line as in:

    ./dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir

or by adding these explicitly using the "Manage Macro Definitions" or
"Manage Include Directories" sub-menus in the "Options" menu.


Saving the information on the Log and Warnings windows
======================================================
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.

There are also buttons to clear the contents of each window.


Inspecting the inferred types of the analyzed functions
=======================================================
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.

NOTE: Currently, the information which is displayed is NOT the type
signatures of the functions. The return values are the least upper
bound of the returned type from the function and the argument types
are the least upper bound of the types that the function is called
with. In other words, the argument types is not what the function can
accept, but rather a description of how the function is used.

We are working on finding the type signatures of the function, and
this will (hopefully) be included in a future version of Dialyzer.


-----------------------------------------------
--
-- Using the Dialyzer from the command line
--
-----------------------------------------------

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

	    "dialyzer --help"

in a shell. Please refer to the GUI description for more details on
the operation of Dialyzer.

The exit status of the command line version is:

    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.



Usage: dialyzer [--help] [--version] [--shell] [--quiet] [--verbose]
		 [-pa dir]* [--plt plt] [-Ddefine]* [-I include_dir]* 
		 [--old_style] [--output_plt file] [-Wwarn]* [--src] 
		 [-c applications] [-r applications] [-o outfile]
                 [--dataflow] [--succ_typings]

Options: 
   -c applications (or --command-line applications)
       Use Dialyzer from the command line (no GUI) to detect defects in the
       specified applications (directories or .erl or .beam files)
   -r applications
       Same as -c only that directories are searched recursively for 
       subdirectories containing .erl or .beam files (depending on the 
       type of analysis)
   -o outfile (or --output outfile)
       When using Dialyzer from the command line, send the analysis
       results in the specified \"outfile\" rather than in stdout
   --src
       Overwrite the default, which is to analyze BEAM bytecode, and
       analyze starting from Erlang source code instead
   -Dname (or -Dname=value)
       When analyzing from source, pass the define to Dialyzer (**)
   -I include_dir
       When analyzing from source, pass the include_dir to Dialyzer (**)
   --old_style
       Gives the warnings in the old style without line numbers.
       Can also be handy when analyzing byte code compiled without +debug_info.
   --output_plt file
       Store the plt at the specified file after building it
   --no_warn_on_inline
       Suppress warnings when analyzing an inline compiled bytecode file
   --plt plt
       Use the specified plt as the initial plt (if the plt was built 
       during setup the files will be checked for consistency)
   -pa dir
       Include dir in the path for Erlang (useful when analyzing files
       that have '-include_lib()' directives)
   -Wwarn
       A family of options which selectively turn on/off warnings
       (for help on the names of warnings use dialyzer -Whelp)
   --check_init_plt
       Only checks if the initial plt is up to date. For installed systems 
       this also forces the rebuilding of the plt if this is not the case
   --shell
       Do not disable the Erlang shell while running the GUI
   --version (or -v)
       Prints the Dialyzer version and some more information and exits
   --help (or -h)
       Prints this message and exits
   --quiet (or -q)
       Makes Dialyzer a bit more quiet
   --verbose
       Makes Dialyzer a bit more verbose
   --dataflow
       Makes Dialyzer use dataflow analysis to find discrepancies. (Default)
   --succ_typings
       Makes Dialyzer use success typings to find discrepancies.

Note:
  * denotes that multiple occurrences of these options are possible.
 ** options -D and -I work both from command-line and in the Dialyzer GUI;
    the syntax of defines and includes is the same as that used by "erlc".

Warning options:
  -Wno_return
     Suppress warnings for functions of no return.
  -Wno_unused
     Suppress warnings for unused functions.
  -Wno_improper_lists
     Suppress warnings for construction of improper lists.
  -Wno_tuple_as_fun
     Suppress warnings for using tuples instead of funs.
  -Wno_fun_app
     Suppress warnings for fun applications that will fail.
  -Wno_match
     Suppress warnings for pattern matching operations that will never 
     succeed.
  -Wno_comp
     Suppress warnings for term comparisons that will always return false.
  -Wno_guards
     Suppress warnings for guards that will always fail.
  -Wno_unsafe_beam
     Suppress warnings for unsafe BEAM code produced by an old 
     BEAM compiler.
  -Werror_handling ***
     Include warnings for functions that only return by means of an 
     exception.
Note:
   *** This is the only option that turns on warnings rather than 
       turning them off.


-----------------------------------------------
--
-- Using the Dialyzer from Erlang
--
-----------------------------------------------

You can also use Dialyzer directly from Erlang. Both the gui and the
command line version is 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.

Interface:

dialyzer:gui() -> ok
	        | {error, Msg}

dialyzer:gui(OptList) -> ok.
		       | {error, Msg}

dialyzer:run(OptList) -> {ok, Warnings, Errors}
		       | {ok, Warnings}
		       | {error, Message}

Warnings : [{MFA, string()}]
MFA      : {Module : atom(), Function : atom(), Arity : integer()}
Errors   : [string()]
Message  : string()

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
	 | {include_dirs,   [DirName : string()]} 
	 | {old_style,      bool()}               %% Defaults to false
	 | {output_file,    FileName : string()}
	 | {supress_inline, bool()}               %% Defaults to true
	 | {warnings,       [WarnOpts]}
         | {analysis_type,  dataflow | succ_typings | old_style}

WarnOpts : no_return
	 | no_unused
	 | no_improper_lists
	 | no_tuple_as_fun
	 | no_fun_app
	 | no_match
	 | no_comp
	 | no_guards
	 | no_unsafe_beam
	 | no_fail_call
	 | error_handling

-----------------------------------------------
--
-- More on the Persistent Lookup Table (PLT)
--
-----------------------------------------------

During setup, a Persistent Lookup Table will automatically be created
for the Erlang/OTP libraries specified in dialyzer/src/Makefile. This
table will be the starting point for later analyses. At each startup
of Dialyzer the validity of the PLT will be checked, and if something
has changed in the included libraries a new PLT will be constructed.

To build a PLT of your own favorite files use the --output_plt option
to specify where the file containing the PLT should be stored. At
later analyses this PLT can be used as the starting point by using the
--plt option. Note that the new PLT file also includes the information
from the PLT that was used as the starting point

WARNING: You should not analyze files that are already included in the
PLT. This can lead to unexpected results if some file has changed
since the PLT was built. Such dependencies are currently only checked
when the PLT was built using the default libraries in
dialyzer/src/Makefile.

In an Erlang/OTP system which has been installed, the user typically
does not have write permission to the file of the PLT. If Dialyzer
later finds that the PLT is not up-to-date, the analysis is aborted
with a warning. Until the installed PLT has been updated a temporary
PLT can be created and used in the manner described above.


-----------------------------------------------
--
-- Feedback & bug reports
--
-----------------------------------------------

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:

	[e-mail], [e-mail]