diff options
Diffstat (limited to 'lib/dialyzer/doc')
| -rw-r--r-- | lib/dialyzer/doc/about.txt | 5 | ||||
| -rw-r--r-- | lib/dialyzer/doc/html/.gitignore | 0 | ||||
| -rw-r--r-- | lib/dialyzer/doc/man3/.gitignore | 0 | ||||
| -rw-r--r-- | lib/dialyzer/doc/manual.txt | 358 | ||||
| -rw-r--r-- | lib/dialyzer/doc/pdf/.gitignore | 0 | ||||
| -rwxr-xr-x | lib/dialyzer/doc/src/Makefile | 113 | ||||
| -rwxr-xr-x | lib/dialyzer/doc/src/book.xml | 49 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/dialyzer.xml | 267 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/dialyzer_chapter.xml | 217 | ||||
| -rwxr-xr-x | lib/dialyzer/doc/src/fascicules.xml | 18 | ||||
| -rwxr-xr-x | lib/dialyzer/doc/src/make.dep | 20 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/note.gif | bin | 0 -> 1539 bytes | |||
| -rwxr-xr-x | lib/dialyzer/doc/src/notes.xml | 746 | ||||
| -rwxr-xr-x | lib/dialyzer/doc/src/part.xml | 36 | ||||
| -rwxr-xr-x | lib/dialyzer/doc/src/part_notes.xml | 36 | ||||
| -rwxr-xr-x | lib/dialyzer/doc/src/ref_man.xml | 35 | ||||
| -rw-r--r-- | lib/dialyzer/doc/src/warning.gif | bin | 0 -> 1498 bytes | |||
| -rw-r--r-- | lib/dialyzer/doc/warnings.txt | 114 |
18 files changed, 2014 insertions, 0 deletions
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 <[email protected]> + Kostis Sagonas <[email protected]> diff --git a/lib/dialyzer/doc/html/.gitignore b/lib/dialyzer/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/dialyzer/doc/html/.gitignore diff --git a/lib/dialyzer/doc/man3/.gitignore b/lib/dialyzer/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/dialyzer/doc/man3/.gitignore 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: + diff --git a/lib/dialyzer/doc/pdf/.gitignore b/lib/dialyzer/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/dialyzer/doc/pdf/.gitignore 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Dialyzer</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>book.xml</file> + </header> + <insidecover> + </insidecover> + <pagetext>Dialyzer</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> + <applications> + <xi:include href="ref_man.xml"/> + </applications> + <releasenotes> + <xi:include href="notes.xml"/> + </releasenotes> + <listofterms></listofterms> + <index></index> +</book> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>dialyzer</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>dialyzer</module> + <modulesummary>The Dialyzer, a DIscrepancy AnalYZer for ERlang programs</modulesummary> + <description> + <p>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).</p> + <p>Read more about Dialyzer and about how to use it from the GUI + in <seealso marker="dialyzer_chapter">Dialyzer User's + Guide</seealso>.</p> + </description> + + <section> + <title>Using the Dialyzer from the command line</title> + <p>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</p> + <code type="none"><![CDATA[ + dialyzer --help + ]]></code> + <p>in a shell. Please refer to the GUI description for more details on + the operation of Dialyzer.</p> + <p>The exit status of the command line version is:</p> + <code type="none"><![CDATA[ + 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. + ]]></code> + <p>Usage:</p> + <code type="none"><![CDATA[ + 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] [--no_check_plt] [--plt_info] [--get_warnings] + ]]></code> + <p>Options:</p> + <taglist> + <tag><c><![CDATA[-c applications]]></c>(or <c><![CDATA[--command-line applications]]></c>)</tag> + <item>use Dialyzer from the command line (no GUI) to detect defects in the + specified applications (directories or <c><![CDATA[.erl]]></c> or <c><![CDATA[.beam]]></c> files)</item> + <tag><c><![CDATA[-r applications]]></c></tag> + <item>same as <c><![CDATA[-c]]></c> only that directories are searched recursively for + subdirectories containing <c><![CDATA[.erl]]></c> or <c><![CDATA[.beam]]></c> files (depending on the + type of analysis)</item> + <tag><c><![CDATA[-o outfile]]></c>(or <c><![CDATA[--output outfile]]></c>)</tag> + <item>when using Dialyzer from the command line, send the analysis + results in the specified <c><![CDATA[outfile]]></c> rather than in stdout</item> + <tag><c><![CDATA[--src]]></c></tag> + <item>override the default, which is to analyze debug compiled BEAM + bytecode, and analyze starting from Erlang source code instead</item> + <tag><c><![CDATA[--raw]]></c></tag> + <item>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).</item> + <tag><c><![CDATA[-Dname]]></c>(or <c><![CDATA[-Dname=value]]></c>)</tag> + <item>when analyzing from source, pass the define to Dialyzer (**)</item> + <tag><c><![CDATA[-I include_dir]]></c></tag> + <item>when analyzing from source, pass the <c><![CDATA[include_dir]]></c> to Dialyzer (**)</item> + <tag><c><![CDATA[-pa dir]]></c></tag> + <item>Include <c><![CDATA[dir]]></c> in the path for Erlang. Useful when analyzing files + that have <c><![CDATA[-include_lib()]]></c> directives.</item> + <tag><c><![CDATA[--output_plt file]]></c></tag> + <item>Store the PLT at the specified location after building it.</item> + <tag><c><![CDATA[--plt plt]]></c></tag> + <item>Use the specified plt as the initial persistent lookup table.</item> + <tag><c><![CDATA[-Wwarn]]></c></tag> + <item>a family of option which selectively turn on/off warnings. + (for help on the names of warnings use <c><![CDATA[dialyzer -Whelp]]></c>)</item> + <tag><c><![CDATA[--shell]]></c></tag> + <item>do not disable the Erlang shell while running the GUI</item> + <tag><c><![CDATA[--version (or -v)]]></c></tag> + <item>prints the Dialyzer version and some more information and exits</item> + <tag><c><![CDATA[--help (or -h)]]></c></tag> + <item>prints this message and exits</item> + <tag><c><![CDATA[--quiet (or -q)]]></c></tag> + <item>makes Dialyzer a bit more quiet</item> + <tag><c><![CDATA[--verbose]]></c></tag> + <item>makes Dialyzer a bit more verbose</item> + <tag><c><![CDATA[--check_plt]]></c></tag> + <item>Only checks if the initial PLT is up to date and rebuilds it if this is not the case</item> + <tag><c><![CDATA[--no_check_plt (or -n)]]></c></tag> + <item>Skip the PLT integrity check when running Dialyzer. + Useful when working with installed PLTs that never change.</item> + <tag><c><![CDATA[--build_plt]]></c></tag> + <item>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.</item> + <tag><c><![CDATA[--add_to_plt]]></c></tag> + <item> 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.</item> + <tag><c><![CDATA[--remove_from_plt]]></c></tag> + <item>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.</item> + <tag><c><![CDATA[--get_warnings]]></c></tag> + <item>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.</item> + </taglist> + <note> + <p>* denotes that multiple occurrences of these options are possible.</p> + <p>** options <c><![CDATA[-D]]></c> and <c><![CDATA[-I]]></c> work both from command-line and in the Dialyzer GUI; + the syntax of defines and includes is the same as that used by <c><![CDATA[erlc]]></c>.</p> + </note> + <p>Warning options:</p> + <taglist> + <tag><c><![CDATA[-Wno_return]]></c></tag> + <item>Suppress warnings for functions of no return.</item> + <tag><c><![CDATA[-Wno_unused]]></c></tag> + <item>Suppress warnings for unused functions.</item> + <tag><c><![CDATA[-Wno_improper_lists]]></c></tag> + <item>Suppress warnings for construction of improper lists.</item> + <tag><c><![CDATA[-Wno_fun_app]]></c></tag> + <item>Suppress warnings for fun applications that will fail.</item> + <tag><c><![CDATA[-Wno_match]]></c></tag> + <item>Suppress warnings for patterns that are unused or cannot + match.</item> + <tag><c><![CDATA[-Werror_handling]]></c>***</tag> + <item>Include warnings for functions that only return by means of an + exception.</item> + <tag><c><![CDATA[-Wunmatched_returns]]></c>***</tag> + <item>Include warnings for function calls which ignore a structured return + value or do not match against one of many possible return value(s).</item> + <tag><c><![CDATA[-Wunderspecs]]></c>***</tag> + <item>Warn about underspecified functions + (the -spec is strictly more allowing than the success typing)</item> + <tag><c><![CDATA[-Woverspecs]]></c>***</tag> + <item>Warn about overspecified functions + (the -spec is strictly less allowing than the success typing)</item> + <tag><c><![CDATA[-Wspecdiffs]]></c>***</tag> + <item>Warn when the -spec is different than the success typing</item> + </taglist> + <note> + <p>*** These are options that turn on warnings rather than + turning them off.</p> + </note> + </section> + + <section> + <title>Using the Dialyzer from Erlang</title> + <p>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.</p> + </section> + <funcs> + <func> + <name>gui() -> ok | {error, Msg}</name> + <name>gui(OptList) -> ok | {error, Msg}</name> + <fsummary>Dialyzer GUI version</fsummary> + <type> + <v>OptList -- see below</v> + </type> + <desc> + <p>Dialyzer GUI version.</p> + <code type="none"><![CDATA[ +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]} + | {get_warnings, bool()} + +WarnOpts : no_return + | no_unused + | no_improper_lists + | no_fun_app + | no_match + | no_fail_call + | error_handling + | unmatched_returns + | overspecs + | underspecs + | specdiffs + ]]></code> + </desc> + </func> + <func> + <name>run(OptList) -> Warnings</name> + <fsummary>Dialyzer command line version</fsummary> + <type> + <v>OptList -- see gui/0,1</v> + <v>Warnings -- see below </v> + </type> + <desc> + <p>Dialyzer command line version.</p> + <code type="none"><![CDATA[ +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 = msg() -- Undefined +]]></code> + </desc> + </func> + <func> + <name>format_warning(Msg) -> string()</name> + <fsummary>Get the string version of a warning message.</fsummary> + <type> + <v>Msg = {Tag, Id, msg()} -- See run/1</v> + </type> + <desc> + <p>Get a string from warnings as returned by dialyzer:run/1.</p> + </desc> + </func> + <func> + <name>plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}</name> + <fsummary>Returns information about the specified plt.</fsummary> + <desc> + <p>Returns information about the specified plt.</p> + </desc> + </func> + </funcs> +</erlref> 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Dialyzer</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>dialyzer_chapter.xml</file> + </header> + + <section> + <title>Introduction</title> + <p><em>Dialyzer</em> 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.</p> + </section> + + <section> + <title>Using the Dialyzer from the GUI</title> + + <section> + <title>Choosing the applications or modules</title> + <p>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.</p> + <p>Mark the directories/modules you want to analyze for discrepancies and + click "Add". You can either add the <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-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 + <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-files.</p> + </section> + + <section> + <title>The analysis modes</title> + <p>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".</p> + </section> + + <section> + <title>Controlling the discrepancies reported by the Dialyzer</title> + <p>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).</p> + <p>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. </p> + </section> + + <section> + <title>Running the analysis</title> + <p>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.</p> + <p>The information from the analysis will be displayed in the Log and the + Warnings windows.</p> + </section> + + <section> + <title>Include directories and macro definitions</title> + <p>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 <c><![CDATA[erlc]]></c> flags <c><![CDATA[-I]]></c> and <c><![CDATA[-D]]></c>). This can be done either by starting Dialyzer + with these flags from the command line as in:</p> + <code type="none"> + + dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir + </code> + <p>or by adding these explicitly using the "Manage Macro Definitions" or + "Manage Include Directories" sub-menus in the "Options" menu.</p> + </section> + + <section> + <title>Saving the information on the Log and Warnings windows</title> + <p>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.</p> + <p>There are also buttons to clear the contents of each window.</p> + </section> + + <section> + <title>Inspecting the inferred types of the analyzed functions</title> + <p>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.</p> + </section> + </section> + + <section> + <title>Using the Dialyzer from the command line</title> + <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p> + </section> + + <section> + <title>Using the Dialyzer from Erlang</title> + <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p> + </section> + + <section> + <title>More on the Persistent Lookup Table (PLT)</title> + + <p> 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.</p> + + <p>The PLT is built using the --build_plt option to dialyzer. The + following command builds the recommended minimal PLT for OTP.</p> + + <code type="none"> + + dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin $ERL_TOP/lib/kernel/ebin $ERL_TOP/lib/mnesia/ebin + </code> + + <p>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.</p> + + <p>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</p> + + <code type="none"> + + dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt + </code> + + <p>Then you would like to add your favorite application my_app to + the new plt.</p> + + <code type="none"> + + dialyzer --add_to_plt --plt my.plt -r my_app/ebin + </code> + + <p>But you realize that it is unnecessary to have compiler in this one.</p> + + <code type="none"> + + dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin + </code> + + <p> 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</p> + + <code type="none"> + + dialyzer --check_plt --plt my.plt + </code> + + <p> 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.</p> + + <p> To get some information about a plt use the option</p> + <code type="none"> + + dialyzer --plt_info + </code> + + <p>You can also specify which plt with the --plt option, and get the + output printed to a file with --output_file</p> + + <p>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.</p> + + </section> + + <section> + <title>Feedback and bug reports</title> + <p>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:</p> + <code type="none"><![CDATA[ + ]]></code> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="part" href="part_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> + Release Notes + </fascicule> + <fascicule file="" href="../../../../doc/print.html" entry="no"> + Off-Print + </fascicule> +</fascicules> + 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 Binary files differnew file mode 100644 index 0000000000..6fffe30419 --- /dev/null +++ b/lib/dialyzer/doc/src/note.gif 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Dialyzer Release Notes</title> + <prepared>otp_appnotes</prepared> + <docno>nil</docno> + <date>nil</date> + <rev>nil</rev> + <file>notes.xml</file> + </header> + <p>This document describes the changes made to the Dialyzer + application.</p> + +<section><title>Dialyzer 2.1.0</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + 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.</p> + <p> + Own Id: OTP-8201</p> + </item> + <item> + <p> + 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</p> + <p> + Added support for packages (thanks to Maria Christakis).</p> + <p> + 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: </p><list> <item>dialyzer file1 ... + fileN</item> </list><p> 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: </p><list> <item>dialyzer --gui %% + for the old gs-based GUI</item> <item>dialyzer --wx %% + for the new wx-based GUI (where available)</item> + </list><p></p> + <p> + 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: </p><list> + <item>dialyzer --build_plt --apps erts kernel stdlib + mnesia ...</item> </list><p></p> + <p> + 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.</p> + <p> + Dialyzer has a new wxWidgets based GUI (thanks to Elli + Frangaki) for platforms where the wx application is + available.</p> + <p> + Own Id: OTP-8300</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 2.0.0</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>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.</p> + <p>Fixed minor issue with dialyzer:run/1 crashing (upon + its return) when used for adding type information to an + existing PLT.</p> + <p>Fixed minor but quite annoying issues in dialyzer's + GUI.</p> + <p> + Own Id: OTP-8187</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.9.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>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().</p> + <p>More accurate type information for some BIFs and + library files.</p> + <p>Introduced boolean() as the `official' name for the + type was so far known as bool(). The latter is still + accepted as well as boolean().</p> + <p> + Own Id: OTP-8037</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.9.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Has better handling of opaque types.</p> + <p>The handling of UTF segments of bitstreams has been + significantly strengthened and revised. In all + probability, now it is correct.</p> + <p> + Own Id: OTP-7958</p> + </item> + </list> + </section> + +</section> +<section><title>Dialyzer 1.9.0</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>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.</p> + <p>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.</p> + <p>Strengthened the discrepancy identification when + testing for equality and matching between terms of + different types. This detects more bugs in code.</p> + <p>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.</p> + <p>Added a convenient shorthand for the --no_check_plt + option (-n).</p> + <p>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.)</p> + <p> + Own Id: OTP-7864</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.8.3</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Added the <c>--no_check_plt</c> option that makes the + startup time faster when working with stable PLTs that do + not change.</p> + <p>Changed the phrasing of some warnings so that they do + not cause confusion to some users and correspond better + to reality.</p> + <p> + Own Id: OTP-7632</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.8.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Minor updates.</p> + <p> + Own Id: OTP-7522</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.8.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + There is new <c>--raw</c> option for Dialyzer to output + the result of the analysis in Erlang term, to facilitate + later filtering and/or formatting.</p> + <p> + Own Id: OTP-7386</p> + </item> + <item> + <p>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.</p> + <p>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.</p> + <p> + Own Id: OTP-7389</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.8.0</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Dialyzer's analysis is from now on exclusively based + on success typings. In particular, support for options + <c>--old_style</c> and <c>--dataflow</c> has been + discontinued.</p> + <p>Better and more aggressive handling of type + information in records.</p> + <p>Dialyzer has a new warning option + <c>-Wunmatched_returns</c> which warns for function calls + that ignore the return value. This catches many common + programming errors (e.g. calling <c>file:close/1</c> 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. + <c>io_lib:format/1</c> instead of <c>io:format/1</c>), + and even possible performance defects (e.g. unnecessarily + constructing a list using a list comprehension instead of + using <c>lists:foreach/2</c>). 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 <c>spawn</c>. 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.</p> + <p>Some warning options (<c>-Wno_comp</c>, + <c>-Wno_guards</c>, <c>-Wno_unsafe_beam</c>, etc.) which + could be used when analyzing bytecode produced by an old + BEAM compiler have been removed.</p> + <p> + Own Id: OTP-7241</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.7.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The warnings returned by the Erlang interface now + contains a tag describing the type of warning.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-7134</p> + </item> + </list> + </section> + +</section> + +<section><title>Dialyzer 1.7.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Use of success typings is now default, is robust and + detects significantly more errors than in previous + versions.</p> + <p>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.</p> + <p>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.</p> + <p> + Own Id: OTP-6997</p> + </item> + </list> + </section> + +</section> + + + <section> + <title>Dialyzer 1.7.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Minor Makefile changes.</p> + <p>Own Id: OTP-6689</p> + </item> + <item> + <p>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.</p> + <p>New command-line options:</p> + <p>--succ_typings Use the success typings analysis.</p> + <p>--dataflow (default) Use the previous analysis.</p> + <p>The new type unit() has been introduced to handle the + return type of non-terminating functions such as + servers.</p> + <p>Dialyzer's code server uses a compressed + representation and the analysis requires significantly + less memory than in previous versions.</p> + <p>Own Id: OTP-6736</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.6.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>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.</p> + <p>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.</p> + <p>Own Id: OTP-6546</p> + </item> + <item> + <p>Dialyzer handles term comparison operators more + precisely and is able to identify more discrepancies in + 'if' or 'case' statements with comparisons.</p> + <p></p> + <p>Dialyzer has more precise type information for many + standard OTP functions.</p> + <p>Own Id: OTP-6547</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.5.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>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 <c><![CDATA[dialyzer(3)]]></c>. + Also, the Dialyzer text files used by its GUI are now + included in the Erlang/OTP release.</p> + <p>Own Id: OTP-6361</p> + </item> + <item> + <p>New options <c><![CDATA[--check_init_plt]]></c> and + <c><![CDATA[--verbose]]></c>.</p> + <p>Improvements in the analysis (meaning that this + version can find more discrepancies than the previous + version).</p> + <p>Own Id: OTP-6421</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.5.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>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.</p> + <p>Dialyzer takes into account the BEAM compiler + directive <c><![CDATA[-compile({nowarn_unused_function, {F,A}}).]]></c> and then suppresses the warning that + function F/A will never be called.</p> + <p>Dialyzer's default initial PLT now also includes + "mnesia".</p> + <p>Own Id: OTP-6304</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.4.2</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Improvements in PLT management.</p> + <p>Own Id: OTP-6128</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.4.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Some minor changes.</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Some minor changes.</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.4.0</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Changes for Dialyzer to work with Erlang/OTP R10B-10.</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Dialyzer's analysis is significantly faster as it uses a global function + call-graph for obtaining type signatures for all analyzed functions.</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.3.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Small changes for Dialyzer to work with Erlang/OTP R10B-5.</p> + </item> + <item> + <p>Fixed a small buglet in the analysis; this affected one of HiPE's files.</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Modified setup script for execution under Cygwin (patch by Vlad Dumitrescu).</p> + </item> + <item> + <p>Added command line option --no_warn_on_inline.</p> + </item> + <item> + <p>Dialyzer now explicitly warns when modules with the same name + but from different dirs are being analyzed (contribution by Ulf Wiger).</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.3.0</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Fixed a number of false positives that Dialyzer 1.2.0 was spitting out.</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Requires the presence of an Erlang/OTP R10B-4 system.</p> + </item> + <item> + <p>Dialyzer is significantly (approx 40%) faster since it now uses 'ets' + rather than 'dets' for its PLT.</p> + </item> + <item> + <p>Slightly improved the precision of the analysis.</p> + </item> + <item> + <p>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.</p> + </item> + <item> + <p>Some more information is displayed when calling a function or closure + with arguments of the wrong type.</p> + </item> + <item> + <p>The record guard now allows discrepancies involving tuples that are known + to be records to be displayed as #rec{} rather than {'rec',_,...,_}</p> + </item> + <item> + <p>Added -q option which makes the command-line version of Dialyzer + a bit more silent.</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.2.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>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).</p> + </item> + <item> + <p>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!)</p> + </item> + <item> + <p>Added -pa command line option for easier handling of -include_lib() + directives in source code.</p> + </item> + <item> + <p>Includes all changes added in v1.1.1; see below. The "Add Recursively" + functionality is also available in the command-line mode (-r option).</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.1.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Fixed problems using the shell script on Solaris machines.</p> + </item> + <item> + <p>Fixed small inconsistencies in Dialyzer's documentation and help.</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The command-line mode of Dialyzer spits discrepancies in stdout + by default and returns a numeric value indicating its exit status.</p> + </item> + <item> + <p>Added "Add Recursively" button contributed by Martin Bjorklund (thanks!).</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.1.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>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.</p> + </item> + <item> + <p>Dialyzer comes with an extensive command-line interface, in addition + to an enhanced GUI.</p> + </item> + <item> + <p>Analysis can start from source code (through Core Erlang) as well as + from BEAM bytecode.</p> + </item> + <item> + <p>Dialyzer finds considerably more discrepancies in Erlang code than + previous versions.</p> + </item> + <item> + <p>Added ability to selectively turn on/off different warning categories.</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.0.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>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.</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Performance improvements in the analysis.</p> + </item> + </list> + </section> + </section> + + <section> + <title>Dialyzer 1.0.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>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.</p> + </item> + </list> + </section> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Dialyzer User's Guide</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>part.xml</file> + </header> + <description> + <p><em>Dialyzer</em> 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.</p> + </description> + <xi:include href="dialyzer_chapter.xml"/> +</part> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Dialyzer Release Notes</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>part_notes.xml</file> + </header> + <description> + <p><em>Dialyzer</em> 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.</p> + </description> + <xi:include href="notes.xml"/> +</part> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Dialyzer Reference Manual</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <description> + <p><em>Dialyzer</em> 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.</p> + </description> + <xi:include href="dialyzer.xml"/> +</application> + diff --git a/lib/dialyzer/doc/src/warning.gif b/lib/dialyzer/doc/src/warning.gif Binary files differnew file mode 100644 index 0000000000..96af52360e --- /dev/null +++ b/lib/dialyzer/doc/src/warning.gif 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 <[email protected]> +## Kostis Sagonas <[email protected]> +## +## $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. |
