diff options
Diffstat (limited to 'lib/dialyzer/doc/manual.txt')
| -rw-r--r-- | lib/dialyzer/doc/manual.txt | 358 |
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: + |