debugme (version 1.1.0)

debugme: Debug R Packages

Description

Specify debug messages as special string constants, and control debugging of packages via environment variables.

Usage

debugme(env = topenv(parent.frame()), pkg = environmentName(env))

Arguments

env

Environment to instument debugging in. Defaults to the package environment of the calling package.

pkg

Name of the calling package. The default should be fine for almost all cases.

Dynamic debug messsages

It is often desired that the debug messages contain values of R expressions evaluated at runtime. For example, when starting a Shiny app, it is useful to also print out the path to the app. Similarly, when debugging an HTTP response, it is desired to log the HTTP status code.

debugme allows embedding R code into the debug messages, within backticks. The code will be evaluated at runtime. Here are some examples:

"!DEBUG Start Shiny app at `path`"
"!DEBUG Got HTTP response `httr::status_code(reponse)`"

Note that parsing the debug strings for code is not very sophisticated currently, and you cannot embed backticks into the code itself.

Log levels

To organize the log messages into log levels, you can start the !DEBUG token with multiple ! characters. You can then select the desired level of logging via ! characters before the package name in the DEBUGME environment variable. E.g. DEBUGME=!!mypackage means that only debug messages with two or less ! marks will be printed.

Debug stack

By default debugme prints the debug stack at the beginning of the debug messages. The debug stack contains the functions in the call stack that have (and emit) debug messages. To suppress printing the call stack set the DEBUGME_SHOW_STACK environment variable to no.

Redirecting the output

If the DEBUGME_OUTPUT_FILE environment variable is set to a filename, then the output is written there instead of the standard output stream of the R process.

If DEBUGME_OUTPUT_FILE is not set, but DEBUGME_OUTPUT_DIR is, then a log file is created there, and the name of the file will contain the process id. This is is useful for logging from several parallel R processes.

Details

To add debugging to your package, you need to

  1. Import the debugme package.

  2. Define an .onLoad function in your package, that calls debugme. An example:

    .onLoad <- function(libname, pkgname) { debugme::debugme() }
    

By default debugging is off. To turn on debugging, set the DEBUGME environment variable to the names of the packages you want to debug. Package names can be separated by commas.

Note that debugme checks for environment variables when it is starting up. Environment variables set after the package is loaded do not have any effect.

Example debugme entries:

"!DEBUG Start Shiny app"