The R13B03 release.OTP_R13B03

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[
+    [email protected], [email protected]
+    ]]></code>
+  </section>
+</chapter>
+