Rationalise GhcMode, HscTarget and GhcLink

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

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 06eb348..03f4a3e 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -1952,6 +1952,32 @@ Main.hs:15> x'
 
   </sect1>
 
+  <sect1 id="ghci-obj">
+    <title>Compiling to object code inside GHCi</title>
+
+    <para>By default, GHCi compiles Haskell source code into byte-code
+    that is interpreted by the runtime system.  GHCi can also compile
+    Haskell code to object code: to turn on this feature, use the
+    <option>-fobject-code</option> flag either on the command line or
+    with <literal>:set</literal> (the option
+    <option>-fbyte-code</option> restores byte-code compilation
+    again).  Compiling to object code takes longer, but typically the
+    code will execute 10-20 times faster than byte-code.</para>
+
+    <para>Compiling to object code inside GHCi is particularly useful
+    if you are developing a compiled application, because the
+    <literal>:reload</literal> command typically runs much faster than
+    restarting GHC with <option>--make</option> from the command-line,
+    because all the interface files are already cached in
+    memory.</para>
+
+    <para>There are disadvantages to compiling to object-code: you
+    can't set breakpoints in object-code modules, for example.  Only
+    the exports of an object-code module will be visible in GHCi,
+    rather than all top-level bindings as in interpreted
+    modules.</para>
+  </sect1>
+
   <sect1 id="ghci-faq">
     <title>FAQ and Things To Watch Out For</title>