From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/dialyzer/doc/about.txt | 5 + lib/dialyzer/doc/html/.gitignore | 0 lib/dialyzer/doc/man3/.gitignore | 0 lib/dialyzer/doc/manual.txt | 358 ++++++++++++++ lib/dialyzer/doc/pdf/.gitignore | 0 lib/dialyzer/doc/src/Makefile | 113 +++++ lib/dialyzer/doc/src/book.xml | 49 ++ lib/dialyzer/doc/src/dialyzer.xml | 267 +++++++++++ lib/dialyzer/doc/src/dialyzer_chapter.xml | 217 +++++++++ lib/dialyzer/doc/src/fascicules.xml | 18 + lib/dialyzer/doc/src/make.dep | 20 + lib/dialyzer/doc/src/note.gif | Bin 0 -> 1539 bytes lib/dialyzer/doc/src/notes.xml | 746 ++++++++++++++++++++++++++++++ lib/dialyzer/doc/src/part.xml | 36 ++ lib/dialyzer/doc/src/part_notes.xml | 36 ++ lib/dialyzer/doc/src/ref_man.xml | 35 ++ lib/dialyzer/doc/src/warning.gif | Bin 0 -> 1498 bytes lib/dialyzer/doc/warnings.txt | 114 +++++ 18 files changed, 2014 insertions(+) create mode 100644 lib/dialyzer/doc/about.txt create mode 100644 lib/dialyzer/doc/html/.gitignore create mode 100644 lib/dialyzer/doc/man3/.gitignore create mode 100644 lib/dialyzer/doc/manual.txt create mode 100644 lib/dialyzer/doc/pdf/.gitignore create mode 100755 lib/dialyzer/doc/src/Makefile create mode 100755 lib/dialyzer/doc/src/book.xml create mode 100644 lib/dialyzer/doc/src/dialyzer.xml create mode 100644 lib/dialyzer/doc/src/dialyzer_chapter.xml create mode 100755 lib/dialyzer/doc/src/fascicules.xml create mode 100755 lib/dialyzer/doc/src/make.dep create mode 100644 lib/dialyzer/doc/src/note.gif create mode 100755 lib/dialyzer/doc/src/notes.xml create mode 100755 lib/dialyzer/doc/src/part.xml create mode 100755 lib/dialyzer/doc/src/part_notes.xml create mode 100755 lib/dialyzer/doc/src/ref_man.xml create mode 100644 lib/dialyzer/doc/src/warning.gif create mode 100644 lib/dialyzer/doc/warnings.txt (limited to 'lib/dialyzer/doc') diff --git a/lib/dialyzer/doc/about.txt b/lib/dialyzer/doc/about.txt new file mode 100644 index 0000000000..7d9d819731 --- /dev/null +++ b/lib/dialyzer/doc/about.txt @@ -0,0 +1,5 @@ + This is DIALYZER version 2.1.0 + DIALYZER is a DIscrepany AnaLYZer for ERlang programs. + + Copyright (C) Tobias Lindahl + Kostis Sagonas diff --git a/lib/dialyzer/doc/html/.gitignore b/lib/dialyzer/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/dialyzer/doc/man3/.gitignore b/lib/dialyzer/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 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 +## Kostis Sagonas +## +## $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 /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: + + tobias.lindahl@it.uu.se, kostis@it.uu.se diff --git a/lib/dialyzer/doc/pdf/.gitignore b/lib/dialyzer/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/dialyzer/doc/src/Makefile b/lib/dialyzer/doc/src/Makefile new file mode 100755 index 0000000000..37bcb49de0 --- /dev/null +++ b/lib/dialyzer/doc/src/Makefile @@ -0,0 +1,113 @@ +# ``The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved via the world wide web at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# The Initial Developer of the Original Code is Ericsson Utvecklings AB. +# Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings +# AB. All Rights Reserved.'' +# +# $Id$ +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(DIALYZER_VSN) +APPLICATION=dialyzer + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF3_FILES = dialyzer.xml + +XML_PART_FILES = part.xml part_notes.xml +XML_CHAPTER_FILES = dialyzer_chapter.xml notes.xml + +BOOK_FILES = book.xml + +XML_FILES = \ + $(BOOK_FILES) $(XML_CHAPTER_FILES) \ + $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_APPLICATION_FILES) + + +# ---------------------------------------------------- + +TEXT_FILES = \ + ../about.txt \ + ../manual.txt \ + ../warnings.txt + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +man: $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + +release_spec: diff --git a/lib/dialyzer/doc/src/book.xml b/lib/dialyzer/doc/src/book.xml new file mode 100755 index 0000000000..0b4e1cb617 --- /dev/null +++ b/lib/dialyzer/doc/src/book.xml @@ -0,0 +1,49 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Dialyzer + + + + + book.xml +
+ + + Dialyzer + + + + + + + + + + + + + + + + diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml new file mode 100644 index 0000000000..7f983a2c0d --- /dev/null +++ b/lib/dialyzer/doc/src/dialyzer.xml @@ -0,0 +1,267 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + dialyzer + + + + +
+ dialyzer + The Dialyzer, a DIscrepancy AnalYZer for ERlang programs + +

The Dialyzer is a static analysis tool that identifies software + discrepancies such as definite type errors, code which has become + dead or unreachable due to some programming error, unnecessary + tests, etc. in single Erlang modules or entire (sets of) + applications. Dialyzer starts its analysis from either + debug-compiled BEAM bytecode or from Erlang source code. The file + and line number of a discrepancy is reported along with an + indication of what the discrepancy is about. Dialyzer bases its + analysis on the concept of success typings which allows for sound + warnings (no false positives).

+

Read more about Dialyzer and about how to use it from the GUI + in Dialyzer User's + Guide.

+ + +
+ 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

+ +

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:

+ +

Usage:

+ +

Options:

+ + (or ) + use Dialyzer from the command line (no GUI) to detect defects in the + specified applications (directories or or files) + + same as only that directories are searched recursively for + subdirectories containing or files (depending on the + type of analysis) + (or ) + when using Dialyzer from the command line, send the analysis + results in the specified rather than in stdout + + override the default, which is to analyze debug compiled BEAM + bytecode, and analyze starting from Erlang source code instead + + 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). + (or ) + when analyzing from source, pass the define to Dialyzer (**) + + when analyzing from source, pass the to Dialyzer (**) + + Include in the path for Erlang. Useful when analyzing files + that have directives. + + Store the PLT at the specified location after building it. + + Use the specified plt as the initial persistent lookup table. + + a family of option which selectively turn on/off warnings. + (for help on the names of warnings use ) + + do not disable the Erlang shell while running the GUI + + prints the Dialyzer version and some more information and exits + + prints this message and exits + + makes Dialyzer a bit more quiet + + makes Dialyzer a bit more verbose + + Only checks if the initial PLT is up to date and rebuilds it if this is not the case + + Skip the PLT integrity check when running Dialyzer. + Useful when working with installed PLTs that never change. + + 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. + + The PLT is extended to also include the files specified with + -c and -r. Use --plt to specify which 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. + + 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. + + Makes Dialyzer emit warnings even when manipulating the PLT. Only + emits warnings for files that are actually analyzed. The default is to + not emit any warnings when manipulating the PLT. This option has no + effect when performing a normal analysis. + + +

* denotes that multiple occurrences of these options are possible.

+

** options and work both from command-line and in the Dialyzer GUI; + the syntax of defines and includes is the same as that used by .

+ +

Warning options:

+ + + Suppress warnings for functions of no return. + + Suppress warnings for unused functions. + + Suppress warnings for construction of improper lists. + + Suppress warnings for fun applications that will fail. + + Suppress warnings for patterns that are unused or cannot + match. + *** + Include warnings for functions that only return by means of an + exception. + *** + Include warnings for function calls which ignore a structured return + value or do not match against one of many possible return value(s). + *** + Warn about underspecified functions + (the -spec is strictly more allowing than the success typing) + *** + Warn about overspecified functions + (the -spec is strictly less allowing than the success typing) + *** + Warn when the -spec is different than the success typing + + +

*** These are options that turn 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 versions are 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.

+
+ + + gui() -> ok | {error, Msg} + gui(OptList) -> ok | {error, Msg} + Dialyzer GUI version + + OptList -- see below + + +

Dialyzer GUI version.

+ + + + + run(OptList) -> Warnings + Dialyzer command line version + + OptList -- see gui/0,1 + Warnings -- see below + + +

Dialyzer command line version.

+ + + + + format_warning(Msg) -> string() + Get the string version of a warning message. + + Msg = {Tag, Id, msg()} -- See run/1 + + +

Get a string from warnings as returned by dialyzer:run/1.

+ + + + plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()} + Returns information about the specified plt. + +

Returns information about the specified plt.

+ + + + diff --git a/lib/dialyzer/doc/src/dialyzer_chapter.xml b/lib/dialyzer/doc/src/dialyzer_chapter.xml new file mode 100644 index 0000000000..d15069991e --- /dev/null +++ b/lib/dialyzer/doc/src/dialyzer_chapter.xml @@ -0,0 +1,217 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Dialyzer + + + + + dialyzer_chapter.xml +
+ +
+ Introduction +

Dialyzer is a static analysis tool that identifies software discrepancies + such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules + or entire (sets of) applications.

+
+ +
+ 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 and -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 + and -files.

+
+ +
+ The analysis modes +

Dialyzer has two modes of analysis, "Byte Code" or "Source Code". + These are controlled by the buttons in the top-middle part of the + main window, under "Analysis Options".

+
+ +
+ 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 flags and ). 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.

+
+
+ +
+ Using the Dialyzer from the command line +

See dialyzer(3).

+
+ +
+ Using the Dialyzer from Erlang +

See dialyzer(3).

+
+ +
+ 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 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.

+ +

To get some information about a plt use the option

+ + + dialyzer --plt_info + + +

You can also specify which plt with the --plt option, and get the + output printed to a file with --output_file

+ +

Note that when manipulating the plt, no warnings are + emitted. To turn on warnings during (re)analysis of the plt, use + the option --get_warnings.

+ +
+ +
+ Feedback and 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:

+ +
+ + diff --git a/lib/dialyzer/doc/src/fascicules.xml b/lib/dialyzer/doc/src/fascicules.xml new file mode 100755 index 0000000000..0678195e07 --- /dev/null +++ b/lib/dialyzer/doc/src/fascicules.xml @@ -0,0 +1,18 @@ + + + + + + User's Guide + + + Reference Manual + + + Release Notes + + + Off-Print + + + diff --git a/lib/dialyzer/doc/src/make.dep b/lib/dialyzer/doc/src/make.dep new file mode 100755 index 0000000000..f8177cd419 --- /dev/null +++ b/lib/dialyzer/doc/src/make.dep @@ -0,0 +1,20 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex dialyzer.tex dialyzer_chapter.tex \ + part.tex ref_man.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + diff --git a/lib/dialyzer/doc/src/note.gif b/lib/dialyzer/doc/src/note.gif new file mode 100644 index 0000000000..6fffe30419 Binary files /dev/null and b/lib/dialyzer/doc/src/note.gif differ diff --git a/lib/dialyzer/doc/src/notes.xml b/lib/dialyzer/doc/src/notes.xml new file mode 100755 index 0000000000..8e8aab60b8 --- /dev/null +++ b/lib/dialyzer/doc/src/notes.xml @@ -0,0 +1,746 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Dialyzer Release Notes + otp_appnotes + nil + nil + nil + notes.xml +
+

This document describes the changes made to the Dialyzer + application.

+ +
Dialyzer 2.1.0 + +
Improvements and New Features + + +

+ The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.

+

+ Own Id: OTP-8201

+ + +

+ Dialyzer can statically detect some kinds of data races + in Erlang programs. Use the new option -Wrace_conditions + to enable the race analysis. The technique is described + in a paper which is available at: + http://www.it.uu.se/research/group/hipe/dialyzer/publications/races.pdf

+

+ Added support for packages (thanks to Maria Christakis).

+

+ There has been a major change in the default mode of + Dialyzer. Previously, the default mode was the GUI, while + now it is the command line. As a result of this change, + it is now possible to analyze a set of files/dirs with + the command:

dialyzer file1 ... + fileN

In other words, the -c + (--command-line) option is no longer necessary, though it + will be retained for some time for backwards + compatibility. To start dialyzer's GUI use either of the + following commands:

dialyzer --gui %% + for the old gs-based GUI dialyzer --wx %% + for the new wx-based GUI (where available) +

+

+ There is a new option --apps which allows the user to + easily refer to Erlang/OTP applications and include them + in the analysis or in the building of the PLT. For + example, we recommend building the PLT with:

+ dialyzer --build_plt --apps erts kernel stdlib + mnesia ...

+

+ The new option can also take absolute file names as well + as applications. Note that the application versions that + will be included in the PLT are those that correspond to + the Erlang/OTP system which is used.

+

+ Dialyzer has a new wxWidgets based GUI (thanks to Elli + Frangaki) for platforms where the wx application is + available.

+

+ Own Id: OTP-8300

+ + +
+ +
+ +
Dialyzer 2.0.0 + +
Improvements and New Features + + +

There is a major addition to the capabilities of + dialyzer, worthy of bumping the version number. Starting + with this version, dialyzer not only accepts but also + properly processes remote types (i.e., types of the form + ModuleName:TypeName()). Previous dialyzer versions only + accepted this notation in -type and -spec declarations, + but effectively ignored its information by mapping remote + types to the type any(). In contrast, starting with this + version, remote types are used in the analysis and are + also stored in the PLTs. (This addition changes the + format of PLTs and requires rebuilding any PLTs created + by an older dialyzer version.) Note that dialyzer will + complain and abort the analysis of a set of modules if it + needs to process a remote type without a definition + (either because the module does not include a definition + of the type or the module is not included in the + analysis). We may relax this restriction in a future + version.

+

Fixed minor issue with dialyzer:run/1 crashing (upon + its return) when used for adding type information to an + existing PLT.

+

Fixed minor but quite annoying issues in dialyzer's + GUI.

+

+ Own Id: OTP-8187

+ + +
+ +
+ +
Dialyzer 1.9.2 + +
Improvements and New Features + + +

Fixed problem with type inference going into an + infinite loop when analyzing a strongly connected + component of functions that do not return but also + contain an erroneous call which makes them fail and be + assigned the type none() instead of the type unit().

+

More accurate type information for some BIFs and + library files.

+

Introduced boolean() as the `official' name for the + type was so far known as bool(). The latter is still + accepted as well as boolean().

+

+ Own Id: OTP-8037

+ + +
+ +
+ +
Dialyzer 1.9.1 + +
Improvements and New Features + + +

Has better handling of opaque types.

+

The handling of UTF segments of bitstreams has been + significantly strengthened and revised. In all + probability, now it is correct.

+

+ Own Id: OTP-7958

+ + +
+ +
+
Dialyzer 1.9.0 + +
Improvements and New Features + + +

The analysis accepts opaque type declarations and + detects violations of opaqueness of terms of such types. + Starting with R13, many Erlang/OTP standard libraries + (array, dict, digraph, ets, gb_sets, gb_trees, queue, and + sets) contain opaque type declarations of their main data + types. Dialyzer will spit out warnings in code that + explicitly depends on the structure of these terms.

+

Added support for handling UTF segments in bitstreams + and for detecting obvious type errors in these segments. + Warning: This code is not terribly tested though since + there are very few Erlang programs which use + Unicode-based binaries - not surprising since this is a + new language feature of R13.

+

Strengthened the discrepancy identification when + testing for equality and matching between terms of + different types. This detects more bugs in code.

+

Added warning for M:F(...) calls where M is not a + module term and F is not an atom. Previously, such calls + where found to fail but the reason for the failure was + not reported.

+

Added a convenient shorthand for the --no_check_plt + option (-n).

+

Added the --dump_callgraph option for dumping the + callgraph of all files that are analyzed into a specified + file. The callgraph either be dumped in raw format, in + .dot format, or converted to a .ps (postscript) file. + Note that in large callgraphs the generated postscript + file might not be interpretable by Ghostview. (Thanks to + Ilya Khlopotov for the initial version of this + functionality.)

+

+ Own Id: OTP-7864

+ + +
+ +
+ +
Dialyzer 1.8.3 + +
Improvements and New Features + + +

Added the --no_check_plt option that makes the + startup time faster when working with stable PLTs that do + not change.

+

Changed the phrasing of some warnings so that they do + not cause confusion to some users and correspond better + to reality.

+

+ Own Id: OTP-7632

+ + +
+ +
+ +
Dialyzer 1.8.2 + +
Improvements and New Features + + +

+ Minor updates.

+

+ Own Id: OTP-7522

+ + +
+ +
+ +
Dialyzer 1.8.1 + +
Improvements and New Features + + +

+ There is new --raw option for Dialyzer to output + the result of the analysis in Erlang term, to facilitate + later filtering and/or formatting.

+

+ Own Id: OTP-7386

+ + +

The return type of the Erlang interface dialyzer:run/1 + has changed to only return a list of warnings. If + something goes wrong dialyzer dies with an exception.

+

The handling of the PLT is now more flexible. There is + no longer any default PLT included with OTP. Please + consult the manual for the changes.

+

+ Own Id: OTP-7389

+ + +
+ +
+ +
Dialyzer 1.8.0 + +
Improvements and New Features + + +

Dialyzer's analysis is from now on exclusively based + on success typings. In particular, support for options + --old_style and --dataflow has been + discontinued.

+

Better and more aggressive handling of type + information in records.

+

Dialyzer has a new warning option + -Wunmatched_returns which warns for function calls + that ignore the return value. This catches many common + programming errors (e.g. calling file:close/1 and + not checking for the absence of errors), interface + discrepancies (e.g. a function returning multiple values + when in reality the function is void and only called for + its side-effects), calling the wrong function (e.g. + io_lib:format/1 instead of io:format/1), + and even possible performance defects (e.g. unnecessarily + constructing a list using a list comprehension instead of + using lists:foreach/2). Whenever a function + returns a single atomic value (e.g. 'ok' or pid()), the + warning is suppressed. This allows for "void" functions + (returning a single atom like 'ok') or for calls to + certain builtins like spawn. Because not all calls + which ignore the return value are discrepancies, the + option is off by default and has to be explicitly + requested by the user. But we recommend it + nevertheless.

+

Some warning options (-Wno_comp, + -Wno_guards, -Wno_unsafe_beam, etc.) which + could be used when analyzing bytecode produced by an old + BEAM compiler have been removed.

+

+ Own Id: OTP-7241

+ + +
+ +
+ +
Dialyzer 1.7.2 + +
Improvements and New Features + + +

+ The warnings returned by the Erlang interface now + contains a tag describing the type of warning.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7134

+ + +
+ +
+ +
Dialyzer 1.7.1 + +
Improvements and New Features + + +

Use of success typings is now default, is robust and + detects significantly more errors than in previous + versions.

+

Dialyzer now accepts and takes into account type + information in record declarations and in contracts -- + see related paper in Erlang'07 workshop. Various OTP + applications (e.g. stdlib and kernel) are partially + annotated with appropriate contracts specifying types + information for their functions.

+

The type previously known as unit() has been renamed + to no_return(). Its use in a contract as the return type + of a function now silences off the "function has no local + return" dialyzer warning without use of the corresponding + option.

+

+ Own Id: OTP-6997

+ + +
+ +
+ + +
+ Dialyzer 1.7.0 + +
+ Improvements and New Features + + +

Minor Makefile changes.

+

Own Id: OTP-6689

+ + +

Dialyzer can now use success typings to find + discrepancies. As a consequence significantly more + discrepancies are detected. The downside is that the + analysis takes about 2 to 2.5 times longer than in + previous versions, and may also result in some warnings + that might be harder to interpret even though they are + correct. This has been a major change, worth of + increasing the version number.

+

New command-line options:

+

--succ_typings Use the success typings analysis.

+

--dataflow (default) Use the previous analysis.

+

The new type unit() has been introduced to handle the + return type of non-terminating functions such as + servers.

+

Dialyzer's code server uses a compressed + representation and the analysis requires significantly + less memory than in previous versions.

+

Own Id: OTP-6736

+ + +
+
+ +
+ Dialyzer 1.6.0 + +
+ Improvements and New Features + + +

Dialyzer (in the modes where either source or BEAM + code which contains debug_info is analyzed) spits out + line information for all discrepancies. This has been a + major change, worth of increasing the version number.

+

We warn users that *considerably* more discrepancies + are identified by this version of Dialyzer compared with + previous ones and applications. If, for some reason, + warnings generated by previous versions of Dialyzer are + preferable, the command line option --old_style can be + employed.

+

Own Id: OTP-6546

+ + +

Dialyzer handles term comparison operators more + precisely and is able to identify more discrepancies in + 'if' or 'case' statements with comparisons.

+

+

Dialyzer has more precise type information for many + standard OTP functions.

+

Own Id: OTP-6547

+ + +
+
+ +
+ Dialyzer 1.5.1 + +
+ Improvements and New Features + + +

Updated the chapter "More on the Persistent Lookup Table + (PLT)" in Dialyzer User's Guide and added information on + how to use Dialyzer from Erlang to . + Also, the Dialyzer text files used by its GUI are now + included in the Erlang/OTP release.

+

Own Id: OTP-6361

+ + +

New options and + .

+

Improvements in the analysis (meaning that this + version can find more discrepancies than the previous + version).

+

Own Id: OTP-6421

+ + +
+
+ +
+ Dialyzer 1.5.0 + +
+ Improvements and New Features + + +

Dialyzer's building of PLT is based on a different + type inference algorithm. More specifically, Dialyzer + uses inference of refined success typings to infer + function prototypes. As a result, Dialyzer bases its + analysis on a significantly more powerful basis and thus + is able to detect more discrepancies. The downside is + that building the PLT is a considerably slower process. + We will work on improving that.

+

Dialyzer takes into account the BEAM compiler + directive and then suppresses the warning that + function F/A will never be called.

+

Dialyzer's default initial PLT now also includes + "mnesia".

+

Own Id: OTP-6304

+ + +
+
+ +
+ Dialyzer 1.4.2 + +
+ Improvements and New Features + + +

Improvements in PLT management.

+

Own Id: OTP-6128

+ + +
+
+ +
+ Dialyzer 1.4.1 + +
+ Fixed Bugs and Malfunctions + + +

Some minor changes.

+ + +
+ +
+ Improvements and New Features + + +

Some minor changes.

+ + +
+
+ +
+ Dialyzer 1.4.0 + +
+ Fixed Bugs and Malfunctions + + +

Changes for Dialyzer to work with Erlang/OTP R10B-10.

+ + +
+ +
+ Improvements and New Features + + +

Dialyzer's analysis is significantly faster as it uses a global function + call-graph for obtaining type signatures for all analyzed functions.

+ + +
+
+ +
+ Dialyzer 1.3.1 + +
+ Fixed Bugs and Malfunctions + + +

Small changes for Dialyzer to work with Erlang/OTP R10B-5.

+ + +

Fixed a small buglet in the analysis; this affected one of HiPE's files.

+ + +
+ +
+ Improvements and New Features + + +

Modified setup script for execution under Cygwin (patch by Vlad Dumitrescu).

+ + +

Added command line option --no_warn_on_inline.

+ + +

Dialyzer now explicitly warns when modules with the same name + but from different dirs are being analyzed (contribution by Ulf Wiger).

+ + +
+
+ +
+ Dialyzer 1.3.0 + +
+ Fixed Bugs and Malfunctions + + +

Fixed a number of false positives that Dialyzer 1.2.0 was spitting out.

+ + +
+ +
+ Improvements and New Features + + +

Requires the presence of an Erlang/OTP R10B-4 system.

+ + +

Dialyzer is significantly (approx 40%) faster since it now uses 'ets' + rather than 'dets' for its PLT.

+ + +

Slightly improved the precision of the analysis.

+ + +

In the GUI version, Dialyzer now reports the list of modules that should + be included in the modules to analyze in order to possibly improve + the accuracy of the reported results.

+ + +

Some more information is displayed when calling a function or closure + with arguments of the wrong type.

+ + +

The record guard now allows discrepancies involving tuples that are known + to be records to be displayed as #rec{} rather than {'rec',_,...,_}

+ + +

Added -q option which makes the command-line version of Dialyzer + a bit more silent.

+ + +
+
+ +
+ Dialyzer 1.2.0 + +
+ Improvements and New Features + + +

Dialyzer works with the open source and commercial versions of Erlang/OTP + R10B-2 on all platforms (i.e., HiPE support is not a prerequisite anymore).

+ + +

Whenever a .beam file contains abstract code (i.e., has been compiled + with the +debug_info option), the analysis starts from this code rather + than from BEAM bytecode -- this makes the results identical to those + obtained by analysis starting from source code. + (This is a contribution from Bjorn Gustavsson - Thanks!)

+ + +

Added -pa command line option for easier handling of -include_lib() + directives in source code.

+ + +

Includes all changes added in v1.1.1; see below. The "Add Recursively" + functionality is also available in the command-line mode (-r option).

+ + +
+
+ +
+ Dialyzer 1.1.1 + +
+ Fixed Bugs and Malfunctions + + +

Fixed problems using the shell script on Solaris machines.

+ + +

Fixed small inconsistencies in Dialyzer's documentation and help.

+ + +
+ +
+ Improvements and New Features + + +

The command-line mode of Dialyzer spits discrepancies in stdout + by default and returns a numeric value indicating its exit status.

+ + +

Added "Add Recursively" button contributed by Martin Bjorklund (thanks!).

+ + +
+
+ +
+ Dialyzer 1.1.0 + +
+ Improvements and New Features + + +

Dialyzer works with the open source version of Erlang/OTP R10B-1 (on + platforms where HiPE support is available) and it does not require + installation of a customized Erlang/OTP system anymore.

+ + +

Dialyzer comes with an extensive command-line interface, in addition + to an enhanced GUI.

+ + +

Analysis can start from source code (through Core Erlang) as well as + from BEAM bytecode.

+ + +

Dialyzer finds considerably more discrepancies in Erlang code than + previous versions.

+ + +

Added ability to selectively turn on/off different warning categories.

+ + +
+
+ +
+ Dialyzer 1.0.1 + +
+ Fixed Bugs and Malfunctions + + +

Fixed major bug of v1.0.0 which caused the analysis to stop prematurely + (i.e., without properly reaching fixpoint) when analyzing more than one + module. This did not affect correctness of the results, but lost many + opportunities to detect discrepancies.

+ + +
+ +
+ Improvements and New Features + + +

Performance improvements in the analysis.

+ + +
+
+ +
+ Dialyzer 1.0.0 + +
+ Improvements and New Features + + +

Initial Dialyzer version: Analysis starts from BEAM bytecode only and + only a GUI version is available. Dialyzer reports discrepancies in the + use of the "sequential" part of Erlang. To be used, Dialyzer requires + the presence of a specific snapshot of Erlang/OTP which can be obtained + from Dialyzer's homepage.

+ + +
+
+ + diff --git a/lib/dialyzer/doc/src/part.xml b/lib/dialyzer/doc/src/part.xml new file mode 100755 index 0000000000..4410840660 --- /dev/null +++ b/lib/dialyzer/doc/src/part.xml @@ -0,0 +1,36 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Dialyzer User's Guide + + + + + part.xml +
+ +

Dialyzer is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.

+ + + + diff --git a/lib/dialyzer/doc/src/part_notes.xml b/lib/dialyzer/doc/src/part_notes.xml new file mode 100755 index 0000000000..cb048d55dd --- /dev/null +++ b/lib/dialyzer/doc/src/part_notes.xml @@ -0,0 +1,36 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Dialyzer Release Notes + + + + + part_notes.xml +
+ +

Dialyzer is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.

+ + + + diff --git a/lib/dialyzer/doc/src/ref_man.xml b/lib/dialyzer/doc/src/ref_man.xml new file mode 100755 index 0000000000..ca5410f6b8 --- /dev/null +++ b/lib/dialyzer/doc/src/ref_man.xml @@ -0,0 +1,35 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Dialyzer Reference Manual + + + + +
+ +

Dialyzer is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.

+ + + + diff --git a/lib/dialyzer/doc/src/warning.gif b/lib/dialyzer/doc/src/warning.gif new file mode 100644 index 0000000000..96af52360e Binary files /dev/null and b/lib/dialyzer/doc/src/warning.gif differ diff --git a/lib/dialyzer/doc/warnings.txt b/lib/dialyzer/doc/warnings.txt new file mode 100644 index 0000000000..fd8cc0dc60 --- /dev/null +++ b/lib/dialyzer/doc/warnings.txt @@ -0,0 +1,114 @@ +##---------------------------------------------------------------------------- +## File: doc/warnings.txt +## Author(s): Tobias Lindahl +## Kostis Sagonas +## +## $Id$ +##---------------------------------------------------------------------------- + + +The discrepancies currently identified by Dialyzer can be classified +in the following categories: + +TYPE ERRORS +=========== + +* Match failure + - Warnings: + "The clause matching on X will never match; argument is of type T" + "The clause matching on tuple with arity N will never match; " + " argument is of type T!" + - Description: + The function or case clause will never match since the calling + argument has a different type than the expected one. + Note that due to pattern-matching compilation the X above may be + an argument enclosed in some structured term (tuple or list). + +* Function call with wrong arguments + - Warning: + "Call to function X with signature S will fail since the arguments are of type T!" + - Description: + The arguments which the function is called with are + not what the function implicitly expects. + +* Closure of wrong type + - Warnings: + "Fun application using type T instead of a fun!" + "Trying to use fun with type T with arguments AT" + - Description: + The variable that is used in the fun application is either not + a closure (fun entry) or a closure with the wrong domain. + +* Improper list construction + - Warnings: + "Cons will produce a non-proper list since its 2nd arg is of type T!" + "Call to '++'/2 will produce a non-proper list since its 2nd arg is of type T!" + - Description: + This is a place where an improper list (i.e., a list whose last + element is not the empty list []) is constructed. Strictly, these + are not discrepancies in Erlang, but we strongly recommend that + you fix these; there is ABSOLUTELY NO reason to create improper lists. + +* Function of no return + - Warning: + "Function will never return a proper value!" + - Description: + This is a function that never returns. Strictly speaking, this + is not a function and the code is OK only if this is used as a + point where an exception is thrown when handling an error. + +REDUNDANT OR UNREACHABLE CODE +============================= + +* Unreachable case clause + - Warning: + "Type guard X will always fail since variable is of type T!" + - Description: + The case clause is redundant since the input argument is of a + different type. + +* Unreachable function clause + - Warning: + "The guard X will always fail since the arguments are of type T!" + - Description: + The clause is made redundant due to one of its guards always failing. + +* Term comparison failure + - Warnings: + "=:= between T1 and T2 will always fail!" + "=/= between T1 and T2 will always fail!" + - Description: + The term comparison will always fail making the test always return + 'false' or, in a guard context, making the clause redundant. + +* Unused function + - Warning: + "Function will never be called!" + - Description: + The function is unused; no need to have it uncommented in the code. + + +CODE RELICS +=========== + +* Tuple used as fun + - Warnings: + "Unsafe use of tuple as a fun in call to X" + "Tuple used as fun will fail in native compiled code" + - Description: + A 2-tuple is used as a function closure. The modern way of + calling higher-order code in Erlang is by using proper funs. + The code should be rewritten using a proper 'fun' rather than + a 2-tuple since among other things makes the code cleaner and + is safer for execution in native code. + +* Unsafe BEAM code + - Warning: + "Unsafe BEAM code! Please recompile with a newer BEAM compiler." + - Description: + The analysis has encountered BEAM bytecode which will fail in a + really bad way (even with a seg-fault) if used in an impoper way. + Such code was produced by the BEAM compiler of R9C-0 (and prior) + for some record expressions. The recommended action is to + generate a new .beam file using a newer version of the BEAM + compiler. -- cgit v1.2.3