diff options
Diffstat (limited to 'lib/dialyzer/doc/src/dialyzer_chapter.xml')
| -rw-r--r-- | lib/dialyzer/doc/src/dialyzer_chapter.xml | 217 |
1 files changed, 217 insertions, 0 deletions
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> + |