% File src/library/utils/man/debugger.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later

\name{debugger}
\alias{debugger}
\alias{dump.frames}
\title{Post-Mortem Debugging}
\description{
  Functions to dump the evaluation environments (frames) and to examine
  dumped frames.
}
\usage{
dump.frames(dumpto = "last.dump", to.file = FALSE,
            include.GlobalEnv = FALSE)
debugger(dump = last.dump)
}
\arguments{
  \item{dumpto}{a character string. The name of the object or file to
    dump to.}
  \item{to.file}{logical.  Should the dump be to an \R object or to a
    file?}
  \item{include.GlobalEnv}{logical indicating if a \emph{copy} of the
    \code{\link{.GlobalEnv}} environment should be included in addition
    to the \code{\link{sys.frames}()}.  Will be particularly useful when
    used in a batch job.}
  \item{dump}{an \R dump object created by \code{dump.frames}.}
}
\details{
  To use post-mortem debugging, set the option \code{error} to be a call
  to \code{dump.frames}.  By default this dumps to an \R object
  \code{last.dump} in the workspace, but it can be set to dump to a
  file (a dump of the object produced by a call to \code{\link{save}}).
  The dumped object contain the call stack, the active environments and
  the last error message as returned by \code{\link{geterrmessage}}.

  When dumping to file, \code{dumpto} gives the name of the dumped
  object and the file name has \file{.rda} appended.

  A dump object of class \code{"dump.frames"} can be examined by calling
  \code{debugger}.  This will give the error message and a list of
  environments from which to select repeatedly.  When an environment is
  selected, it is copied and the \code{\link{browser}} called from
  within the copy.  Note that not all the information in the original
  frame will be available, e.g.\sspace{}promises which have not yet been
  evaluated and the contents of any \code{\dots} argument.

  If \code{dump.frames} is installed as the error handler, execution
  will continue even in non-interactive sessions.  See the examples for
  how to dump and then quit.
}
\value{
  Invisible \code{NULL}.
}
\note{
  Functions such as \code{\link{sys.parent}} and
  \code{\link{environment}} applied to closures will not work correctly
  inside \code{debugger}.

  If the error occurred when computing the default value of a formal
  argument the debugger will report \dQuote{recursive default argument
  reference} when trying to examine that environment.

  Of course post-mortem debugging will not work if \R is too damaged to
  produce and save the dump, for example if it has run out of workspace.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{browser}} for the actions available at the \code{Browse}
  prompt.

  \code{\link{options}} for setting \code{error} options;
  \code{\link{recover}} is an interactive debugger working similarly to
  \code{debugger} but directly after the error occurs.
}
\examples{
\dontrun{
options(error = quote(dump.frames("testdump", TRUE)))

f <- function() {
    g <- function() stop("test dump.frames")
    g()
}
f()   # will generate a dump on file "testdump.rda"
options(error = NULL)

## possibly in another R session
load("testdump.rda")
debugger(testdump)
Available environments had calls:
1: f()
2: g()
3: stop("test dump.frames")

Enter an environment number, or 0 to exit
Selection: 1
Browsing in the environment with call:
f()
Called from: debugger.look(ind)
Browse[1]> ls()
[1] "g"
Browse[1]> g
function() stop("test dump.frames")
<environment: 759818>
Browse[1]>
Available environments had calls:
1: f()
2: g()
3: stop("test dump.frames")

Enter an environment number, or 0 to exit
Selection: 0

## A possible setting for non-interactive sessions
options(error = quote({dump.frames(to.file = TRUE); q(status = 1)}))
}}
\keyword{utilities}
\keyword{error}