aboutsummaryrefslogtreecommitdiffstats
path: root/lib/dialyzer/doc/manual.txt
diff options
context:
space:
mode:
Diffstat (limited to 'lib/dialyzer/doc/manual.txt')
-rw-r--r--lib/dialyzer/doc/manual.txt358
1 files changed, 358 insertions, 0 deletions
diff --git a/lib/dialyzer/doc/manual.txt b/lib/dialyzer/doc/manual.txt
new file mode 100644
index 0000000000..f1faed3c79
--- /dev/null
+++ b/lib/dialyzer/doc/manual.txt
@@ -0,0 +1,358 @@
+##----------------------------------------------------------------------------
+## File: doc/manual.txt
+## Author(s): Tobias Lindahl <[email protected]>
+## Kostis Sagonas <[email protected]>
+##
+## $Id$
+##----------------------------------------------------------------------------
+
+The DIALYZER, a DIscrepany AnaLYZer for ERlang programs.
+
+
+-----------------------------------------------
+--
+-- Using 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.
+ - Source code:
+ The analysis starts from .erl files.
+
+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).
+
+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 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]*
+ [--output_plt file] [-Wwarn]* [--src]
+ [-c applications] [-r applications] [-o outfile]
+ [--build_plt] [--add_to_plt] [--remove_from_plt] [--check_plt]
+ [--plt_info] [--get_warnings]
+
+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
+ --raw
+ When using Dialyzer from the command line, output the raw analysis
+ results (Erlang terms) instead of the formatted result.
+ The raw format is easier to post-process (for instance, to filter
+ warnings or to output HTML pages)
+ --src
+ Override 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 (**)
+ --output_plt file
+ Store the plt at the specified file after building it
+ --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)
+ --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
+ --build_plt
+ The analysis starts from an empty plt and creates a new one from the
+ files specified with -c and -r. Only works for beam files.
+ Use --plt or --output_plt to override the default plt location.
+ --add_to_plt
+ The plt is extended to also include the files specified with -c and -r.
+ Use --plt to specify wich plt to start from, and --output_plt to
+ specify where to put the plt. Note that the analysis might include
+ files from the plt if they depend on the new files.
+ This option only works with beam files.
+ --remove_from_plt
+ The information from the files specified with -c and -r is removed
+ from the plt. Note that this may cause a re-analysis of the remaining
+ dependent files.
+ --check_plt
+ Checks the plt for consistency and rebuilds it if it is not up-to-date.
+ --no_check_plt
+ Skip the plt check when running Dialyzer. Useful when working with
+ installed plts that never change.
+ --plt_info
+ Makes Dialyzer print information about the plt and then quit. The plt
+ can be specified with --plt.
+ --get_warnings
+ Makes Dialyzer emit warnings even when manipulating the plt. Only
+ emits warnings for files that are actually analyzed.
+
+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 that will never return a value.
+ -Wno_unused
+ Suppress warnings for unused functions.
+ -Wno_improper_lists
+ Suppress warnings for construction of improper lists.
+ -Wno_fun_app
+ Suppress warnings for fun applications that will fail.
+ -Wno_match
+ Suppress warnings for patterns that are unused or cannot match.
+ -Wunmatched_returns ***
+ Include warnings for function calls which ignore the return value(s).
+ -Werror_handling ***
+ Include warnings for functions that only return by means of an exception.
+ -Wunderspecs ***
+ Warn about underspecified functions
+ (the -spec is strictly more allowing than the success typing)
+ -Woverspecs ***
+ Warn about overspecified functions
+ (the -spec is strictly less allowing than the success typing)
+ -Wspecdiffs ***
+ Warn when the -spec is different than the success typing
+
+Note:
+ *** These are options that turn on warnings rather than turning them off.
+
+
+-----------------------------------------------
+--
+-- Using 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'
+
+dialyzer:gui(OptList) -> 'ok'
+
+dialyzer:run(OptList) -> Warnings
+
+Warnings :: [{tag(), id(), msg()}]
+tag() :: 'warn_return_no_exit' | 'warn_return_only_exit' | 'warn_not_called'
+ | 'warn_non_proper_list' | 'warn_fun_app' | 'warn_matching'
+ | 'warn_failing_call' | 'warn_contract_types'
+ | 'warn_contract_syntax' | 'warn_contract_not_equal'
+ | 'warn_contract_subtype' | 'warn_contract_supertype'
+id() :: {File :: string(), Line :: integer()}
+msg() :: Undefined
+
+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()]}
+ | {output_file, FileName :: string()}
+ | {output_plt, FileName :: string()}
+ | {analysis_type, 'success_typings' | 'plt_add' |
+ 'plt_build' | 'plt_check' | 'plt_remove'}
+ | {warnings, [WarnOpts]}
+
+WarnOpts :: no_return
+ | no_unused
+ | no_improper_lists
+ | no_fun_app
+ | no_match
+ | no_fail_call
+ | unmatched_returns
+ | error_handling
+
+dialyzer:format_warning({tag(), id(), msg()}) -> string()
+
+Returns a string representation of the warnings as returned by dialyzer:run/1.
+
+dialyzer:plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}
+
+Returns information about the specified plt.
+
+-----------------------------------------------
+--
+-- More on the Persistent Lookup Table (PLT)
+--
+-----------------------------------------------
+
+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.
+
+The PLT is built using the --build_plt option to dialyzer. The
+following command builds the recommended minimal PLT for OTP.
+
+dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin\
+ $ERL_TOP/lib/kernel/ebin\
+ $ERL_TOP/lib/mnesia/ebin
+
+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.
+
+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
+
+dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt
+
+Then you would like to add your favorite application my_app to the new
+plt.
+
+dialyzer --add_to_plt --plt my.plt -r <path>/my_app/ebin
+
+But you realize that it is unnecessary to have compiler in this one.
+
+dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin
+
+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
+
+dialyzer --check_plt --plt my.plt
+
+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.
+
+-----------------------------------------------
+--
+-- 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:
+