[commit: ghc] master: Docs for stack traces in GHCi (2bd05b8)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/2bd05b889f39e5ddf43a723b817b92fc6f4fc6d4/ghc

>---------------------------------------------------------------

commit 2bd05b889f39e5ddf43a723b817b92fc6f4fc6d4
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Fri Jan 8 16:15:46 2016 +0000

    Docs for stack traces in GHCi


>---------------------------------------------------------------

2bd05b889f39e5ddf43a723b817b92fc6f4fc6d4
 docs/users_guide/8.0.1-notes.rst |  3 ++
 docs/users_guide/ghci.rst        | 61 ++++++++++++++++++++++++++++++++++++----
 2 files changed, 58 insertions(+), 6 deletions(-)

diff --git a/docs/users_guide/8.0.1-notes.rst b/docs/users_guide/8.0.1-notes.rst
index b4957ab..1d7fcd7 100644
--- a/docs/users_guide/8.0.1-notes.rst
+++ b/docs/users_guide/8.0.1-notes.rst
@@ -45,6 +45,9 @@ The highlights, since the 7.10 branch, are:
   :ref:`external-interpreter`), and the interpreter can now run profiled
   code.
 
+- GHCi now provides access to stack traces when used with
+  ``-fexternal-interpreter`` and ``-prof`` (see :ref:`ghci-stack-traces`).
+
 - The reworked users guide you are now reading
 
 - Support for Windows XP and earlier has been dropped.
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index d4136ab..c299fb2 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -1102,6 +1102,53 @@ The ``-interactive-print`` flag can also be used when running GHC in
     % ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter
     [1,2,3]!
 
+.. _ghci-stack-traces:
+
+Stack Traces in GHCi
+~~~~~~~~~~~~~~~~~~~~
+
+.. index::
+  simple: stack trace; in GHCi
+
+[ This is an experimental feature enabled by the new
+``-fexternal-interpreter`` flag that was introduced in GHC 8.0.1.  It
+is currently not supported on Windows.]
+
+GHCi can use the profiling system to collect stack trace information
+when running interpreted code.  To gain access to stack traces, start
+GHCi like this:
+
+.. code-block:: none
+
+    ghci -fexternal-interpreter -prof
+
+This runs the interpreted code in a separate process (see
+:ref:`external-interpreter`) and runs it in profiling mode to collect
+call stack information.  Note that because we're running the
+interpreted code in profiling mode, all packages that you use must be
+compiled for profiling.  The ``-prof`` flag to GHCi only works in
+conjunction with ``-fexternal-interpreter``.
+
+There are three ways to get access to the current call stack.
+
+- ``error`` and ``undefined`` automatically attach the current stack
+  to the error message.  This often complements the implicit stack
+  stack (see :ref:`implicit-callstacks`), so both call stacks are
+  shown.
+
+- ``Debug.Trace.traceStack`` is a version of ``Debug.Trace.trace``
+  that also prints the current call stack.
+
+- Functions in the module ``GHC.Stack`` can be used to get the current
+  stack and render it.
+
+You don't need to use ``-fprof-auto`` for interpreted modules,
+annotations are automatically added at a granularity fine enough to
+distinguish individual call sites.  However, you won't see any call
+stack information for compiled code unless it was compiled with
+``-fprof-auto`` or has explicit ``SCC`` annotations (see
+:ref:`scc-pragma`).
+
 .. _ghci-debugger:
 
 The GHCi Debugger
@@ -2942,12 +2989,14 @@ using messages over a pipe.
 
 Why might we want to do this?  The main reason is that the RTS running
 the interpreted code can be a different flavour (profiling or
-dynamically-linked) from GHC itself.  So for example, when compiling
-Template Haskell code with ``-prof``, we don't need to compile the
-modules without ``-prof`` first (see :ref:`th-profiling`) because we
-can run the profiled object code in the interpreter.  GHCi can also
-load and run profiled object code when run with
-``-fexternal-interpreter`` and ``-prof``.
+dynamically-linked) from GHC itself.  So for example:
+
+- We can use the profiler to collect stack traces when using GHCi (see
+  :ref:`ghci-stack-traces`).
+
+- When compiling Template Haskell code with ``-prof`` we don't need to
+  compile the modules without ``-prof`` first (see :ref:`th-profiling`)
+  because we can run the profiled object code in the interpreter.
 
 This feature is experimental in GHC 8.0.x, but it may become the
 default in future releases.