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/src/dialyzer_chapter.xml | 217 ++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 lib/dialyzer/doc/src/dialyzer_chapter.xml (limited to 'lib/dialyzer/doc/src/dialyzer_chapter.xml') 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:

+ +
+ + -- cgit v1.2.3