1 Dialyzer
1.1 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.
1.2 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 .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 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 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.
1.3 Using the Dialyzer from the command line
See dialyzer(3).
1.4 Using the Dialyzer from Erlang
See dialyzer(3).
1.5 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.
1.6 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:
tobias.lindahl@it.uu.se, kostis@it.uu.se