Add -fno-implicit-import-qualified (#2452)

[ghc-hetmet.git] / docs / users_guide / ghci.xml

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index e0ea3af..1f20df4 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -202,12 +202,12 @@ Ok, modules loaded: Main.
     very often, and use the interpreter for the code being actively
     developed.</para>
 
-    <para>When loading up source files with <literal>:load</literal>,
-    GHCi looks for any corresponding compiled object files, and will
-    use one in preference to interpreting the source if possible.  For
-    example, suppose we have a 4-module program consisting of modules
-    A, B, C, and D.  Modules B and C both import D only,
-    and A imports both B &amp; C:</para>
+    <para>When loading up source modules with <literal>:load</literal>,
+    GHCi normally looks for any corresponding compiled object files,
+    and will use one in preference to interpreting the source if
+    possible.  For example, suppose we have a 4-module program
+    consisting of modules A, B, C, and D.  Modules B and C both import
+    D only, and A imports both B &amp; C:</para>
 <screen>
       A
      / \
@@ -298,6 +298,17 @@ Compiling A                ( A.hs, interpreted )
 Ok, modules loaded: A, B, C, D.
 </screen>
 
+    <para>The automatic loading of object files can sometimes lead to
+    confusion, because non-exported top-level definitions of a module
+    are only available for use in expressions at the prompt when the
+    module is interpreted (see <xref linkend="ghci-scope" />).  For
+    this reason, if you ask GHCi to load a filename rather than a
+    module name (e.g. <literal>:load Main.hs</literal> rather than
+    <literal>:load Main</literal>) then any existing object file will
+    be ignored and the module will be interpreted rather than
+    compiled.  Using <literal>-fobject-code</literal> disables this
+    behaviour (see <xref linkend="ghci-obj" />).</para>
+
     <para>HINT: since GHCi will only use a compiled object file if it
     can be sure that the compiled version is up-to-date, a good technique
     when working on a large program is to occasionally run
@@ -306,7 +317,6 @@ Ok, modules loaded: A, B, C, D.
     interpreter.  As you modify code, the changed modules will be
     interpreted, but the rest of the project will remain
     compiled.</para>
-
   </sect1>
 
   <sect1 id="interactive-evaluation">
@@ -537,10 +547,14 @@ Compiling Main             ( Main.hs, interpreted )
       scopes from multiple modules, in any mixture of
       <literal>*</literal> and non-<literal>*</literal> forms.  GHCi
       combines the scopes from all of these modules to form the scope
-      that is in effect at the prompt.  For technical reasons, GHCi
-      can only support the <literal>*</literal>-form for modules which
-      are interpreted, so compiled modules and package modules can
-      only contribute their exports to the current scope.</para>
+      that is in effect at the prompt.</para>
+
+      <para>NOTE: for technical reasons, GHCi can only support the
+      <literal>*</literal>-form for modules that are interpreted.
+      Compiled modules and package modules can only contribute their
+      exports to the current scope.  This is why GHCi will always
+      interpret, not compile, a module if you specify its filename
+      rather than its module name to <literal>:load</literal>.</para>
 
       <para>The scope is manipulated using the
       <literal>:module</literal> command.  For example, if the current
@@ -602,12 +616,48 @@ Prelude IO>
       </para>
 
       <sect3>
+        <title><literal>:module</literal> and
+        <literal>:load</literal></title>
+
+        <para>It might seem that <literal>:module</literal> and
+        <literal>:load</literal> do similar things: you can use both
+        to bring a module into scope.  However, there is a clear
+        difference.  GHCi is concerned with two sets of modules:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>The set of modules that are
+              currently <emphasis>loaded</emphasis>.  This set is
+              modified
+              by <literal>:load</literal>, <literal>:add</literal>
+              and <literal>:reload</literal>.
+            </para>
+          </listitem>
+          <listitem>
+            <para>The set of modules that are currently <emphasis>in
+                scope</emphasis> at the prompt.  This set is modified
+              by <literal>:module</literal>, and it is also set
+              automatically
+                after <literal>:load</literal>, <literal>:add</literal>,
+              and <literal>:reload</literal>.</para>
+          </listitem>
+        </itemizedlist>
+
+        <para>You cannot add a module to the scope if it is not
+          loaded.  This is why trying to
+          use <literal>:module</literal> to load a new module results
+          in the message &ldquo;<literal>module M is not
+            loaded</literal>&rdquo;.</para>
+      </sect3>
+
+      <sect3 id="ghci-import-qualified">
        <title>Qualified names</title>
 
        <para>To make life slightly easier, the GHCi prompt also
         behaves as if there is an implicit <literal>import
         qualified</literal> declaration for every module in every
-        package, and every module currently loaded into GHCi.</para>
+        package, and every module currently loaded into GHCi.  This
+          behaviour can be disabled with the flag <option>-fno-implicit-import-qualified</option><indexterm><primary><option>-fno-implicit-import-qualified</option></primary></indexterm>.</para>
       </sect3>
 
       <sect3>