Merge branch 'master' into sverker/hipe-code-loadnpurge

Conflicts:
	erts/emulator/beam/beam_bif_load.c
	erts/emulator/beam/beam_load.c

and added macro DBG_TRACE_MFA_P in beam_load.h

1 files changed, 159 insertions, 144 deletions

diff --git a/lib/dialyzer/doc/src/dialyzer_chapter.xml b/lib/dialyzer/doc/src/dialyzer_chapter.xml
index c445f2633f..b5acf3732e 100644
--- a/lib/dialyzer/doc/src/dialyzer_chapter.xml
+++ b/lib/dialyzer/doc/src/dialyzer_chapter.xml
@@ -25,196 +25,211 @@
     <title>Dialyzer</title>
     <prepared></prepared>
     <docno></docno>
-    <date></date>
+    <date>2016-09-19</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>
+      <title>Scope</title>
+      <p>Dialyzer is a static analysis tool that identifies software
+        discrepancies, such as definite type errors, code that has become dead
+        or unreachable because of programming error, and unnecessary tests,
+        in single Erlang modules or entire (sets of) applications.</p>
+
+      <p>Dialyzer can be called from the command line, from Erlang,
+        and from a GUI.</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>
+      <title>Prerequisites</title>
+      <p>It is assumed that the reader is familiar with the Erlang programming
+        language.</p>
     </section>
+  </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>
+    <marker id="plt"/>
+    <title>The Persistent Lookup Table</title>
+    <p>Dialyzer stores the result of an analysis in a Persistent
+      Lookup Table (PLT). The PLT can then be used as a starting
+      point for later analyses. It is recommended to build a PLT with the
+      Erlang/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 option <c>--build_plt</c> to Dialyzer.
+      The following command builds the recommended minimal PLT for
+      Erlang/OTP:</p>
 
-    <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">
+    <code type="none">
+dialyzer --build_plt --apps erts kernel stdlib mnesia</code>
 
-      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>
+    <p>Dialyzer looks if there is an environment variable called
+      <c>DIALYZER_PLT</c> and places the PLT at this location. If no such
+      variable is set, Dialyzer places the PLT at
+      <c>$HOME/.dialyzer_plt</c>. The placement can also be specified using
+      the options <c>--plt</c> or <c>--output_plt</c>.</p>
 
-    <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>
+    <p>Information can be added to an existing PLT using option
+      <c>--add_to_plt</c>. If you also want to include the Erlang compiler in
+      the PLT and place it in a new PLT, then use the following command:</p>
 
-    <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>
+    <code type="none">
+dialyzer --add_to_plt --apps compiler --output_plt my.plt</code>
 
-  <section>
-    <title>Using the Dialyzer from the command line</title>
-    <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p>
-  </section>
+    <p>Then you can add your favorite application my_app to the new
+      PLT:</p>
 
-  <section>
-    <title>Using the Dialyzer from Erlang</title>
-    <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p>
-  </section>
+    <code type="none">
+dialyzer --add_to_plt --plt my.plt -r my_app/ebin</code>
 
-  <section>
-    <title>More on the Persistent Lookup Table (PLT)</title> 
+    <p>But you realize that it is unnecessary to have the Erlang compiler in this
+      one:</p>
 
-    <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>
+    <code type="none">
+dialyzer --remove_from_plt --plt my.plt --apps compiler</code>
 
-    <p>The PLT is built using the --build_plt option to dialyzer. The
-    following command builds the recommended minimal PLT for OTP.</p>
+    <p>Later, when you have fixed a bug in your application my_app,
+      you want to update the PLT so that it becomes fresh the next time
+      you run Dialyzer. In this case, run the following command:</p>
 
     <code type="none">
+dialyzer --check_plt --plt my.plt</code>
 
-    dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin\
-                            $ERL_TOP/lib/kernel/ebin \
-                            $ERL_TOP/lib/mnesia/ebin
-    </code>
+    <p>Dialyzer then reanalyzes the changed files
+      and the files that depend on these files. Notice that this
+      consistency check is performed automatically the next time you
+      run Dialyzer with this PLT. Option <c>--check_plt</c> is only
+      for doing so without doing any other analysis.</p>
 
-    <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>
+    <p>To get information about a PLT, use the following option:</p>
 
     <code type="none">
+dialyzer --plt_info</code>
 
-    dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt
-    </code>
+    <p>To specify which PLT, use option <c>--plt</c>.</p>
 
-    <p>Then you would like to add your favorite application my_app to
-    the new plt.</p>
+    <p>To get the output printed to a file, use option <c>--output_file</c>.</p>
 
-    <code type="none">
+    <p>Notice that when manipulating the PLT, no warnings are
+      emitted. To turn on warnings during (re)analysis of the PLT, use
+      option <c>--get_warnings</c>.</p>
+  </section>
 
-    dialyzer --add_to_plt --plt my.plt -r my_app/ebin
-    </code>
+  <section>
+    <title>Using Dialyzer from the Command Line</title>
+    <p>Dialyzer has a command-line version for automated use.
+      See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p>
+  </section>
 
-    <p>But you realize that it is unnecessary to have compiler in this one.</p>
+  <section>
+    <title>Using Dialyzer from Erlang</title>
+    <p>Dialyzer can also be used directly from Erlang.
+      See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p>
+  </section>
 
-    <code type="none">
+  <section>
+   <marker id="dialyzer_gui"/>
+    <title>Using Dialyzer from the GUI</title>
+    <section>
+      <title>Choosing the Applications or Modules</title>
+      <p>The <em>File</em> window displays 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>
 
-    dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin
-    </code>
+      <p>Mark the directories/modules you want to analyze for discrepancies and
+        click <em>Add</em>. You can either add the <c>.beam</c> and
+        <c>.erl</c> files directly, or add directories that contain
+        these kind of files. Notice 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>.beam</c> and <c>.erl</c> files.</p>
+    </section>
 
-    <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>
+    <section>
+      <title>Analysis Modes</title>
+      <p>Dialyzer has two analysis modes: "Byte Code" and "Source Code".
+         They are controlled by the buttons in the top-middle part of the
+         main window, under <em>Analysis Options</em>.</p>
+    </section>
 
-    <code type="none">
+    <section>
+      <title>Controlling the Discrepancies Reported by Dialyzer</title>
+      <p>Under the <em>Warnings</em> pull-down menu, there are buttons that
+        control which discrepancies are reported to the user in the
+        <em>Warnings</em> window. By clicking these buttons, you can
+        enable/disable a whole class of warnings. Information about the classes
+        of warnings is found on the "Warnings" item under the <em>Help</em>
+        menu (in the rightmost top corner).</p>
+
+      <p>If modules are compiled with inlining, spurious warnings can be
+        emitted. In the <em>Options</em> menu you can choose to ignore
+        inline-compiled modules when analyzing byte code.
+        When starting from source code, this is not a problem because
+        inlining is explicitly turned off by Dialyzer. The option causes
+        Dialyzer to suppress all warnings from inline-compiled
+        modules, as there is currently no way for Dialyzer to find what
+        parts of the code have been produced by inlining.</p>
+    </section>
 
-    dialyzer --check_plt --plt my.plt
-    </code>
+    <section>
+      <title>Running the Analysis</title>
+      <p>Once you have chosen the modules or directories you want to analyze,
+        click the <em>Run</em> button to start the analysis. If you for some
+        reason want to stop the analysis while it is running, click the
+        <em>Stop</em> button.</p>
 
-    <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>The information from the analysis is displayed in the <em>Log</em>
+        window and the <em>Warnings</em> window.</p>
+    </section>
 
-    <p> To get some information about a plt use the option</p>
-    <code type="none">
+    <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 <seealso marker="erts:erlc"><c>erlc</c></seealso> flags
+        <c>-I</c> and <c>-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>
 
-    dialyzer --plt_info
-    </code>
+      <p>or by adding these explicitly using submenu
+        <em>Manage Macro Definitions</em> or
+        <em>Manage Include Directories</em> in the <em>Options</em> menu.</p>
+    </section>
 
-    <p>You can also specify which plt with the --plt option, and get the 
-    output printed to a file with --output_file</p>
+    <section>
+      <title>Saving the Information on the Log and Warnings Windows</title>
+      <p>The <em>File</em> menu includes options to save the contents of the
+        <em>Log</em> window and the <em>Warnings</em> window. Simply choose the
+        options and enter the file to save the contents in.</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>
+      <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), see section
+        <seealso marker="#plt">The Persistent Lookup Table</seealso>.</p>
+
+      <p>After an analysis, you can inspect this information.
+        In the <em>PLT</em> menu you can choose to either search the PLT
+        or inspect the contents of the whole PLT. The information is presented
+        in <seealso marker="edoc:edoc"><c>EDoc</c></seealso> format.</p>
+    </section>
   </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>
+    <title>Feedback and Bug Reports</title>
+    <p>We very much welcome user feedback - even wishlists!
+      If you notice anything weird, especially if Dialyzer reports
+      any discrepancy that is a false positive, please send an error report
+      describing the symptoms and how to reproduce them.</p>
   </section>
 </chapter>