Specify debug messages as special string constants, and control
debugging of packages via environment variables. This package was
largely influenced by the debug
npm
package.
Stable version:
install.packages("debugme")
To install the development version:
::pak("r-lib/debugme") pak
To use debugme
in your package, import it, and then add
the following .onLoad
function to your package:
<- function(libname, pkgname) {
.onLoad ::debugme()
debugme }
You can now add debug messages via character literals. No function calls are necessary. For example:
"!DEBUG Start up phantomjs"
$start_phantomjs(phantom_debug_level)
private
"!DEBUG Start up shiny"
$start_shiny(path)
private
"!DEBUG create new phantomjs session"
$web <- session$new(port = private$phantom_port)
private
"!DEBUG navigate to Shiny app"
$web$go(private$get_shiny_url()) private
The string literals are simply ignored when debugging is turned off.
To turn on debugging for a package, set the environment variable
DEBUGME
to the package name you want to debug. E.g. from a
bash
shell:
export DEBUGME=mypackage
Or from within R:
Sys.setenv(DEBUGME = "mypackage")
Separate multiple package names with commas:
export DEBUGME=mypackage,otherpackage
The debug messages will be prefixed by the package names, and assuming your terminal supports color, will be colored differently for each package.
The debugme
debug strings may contain R code between
backticks. This code is evaluated at runtime, if debugging is turned on.
A single debug string may contain multiple backticked code chunks:
"!DEBUG x = `x`, y = `y`"
if (x != y) {
...
I have always wanted a debugging tool that * is very simple to use, * can be controlled via environment variables, without changing anything it the packages themselves, * has zero impact on performance when debugging is off.
debugme
is such a tool.
Function calls are relatively cheap in R, but they still do have an
impact. If you never want to worry about the log messages making your
code slower, you will like debugme
. debugme
debug strings have practically no performance penalty when debugging is
off.
Here is a simple comparison to evaluate debugging overhead with a
function call, f1()
, debugging with debug strings,
f2()
, and no debugging at all.
<- function(msg) { }
debug <- function() {
f1 for (i in 1:100) {
debug("foobar")
# Avoid optimizing away the loop
<- i + 1
i
} }
<- function() {
f2 for (i in 1:100) {
"!DEBUG foobar"
# Avoid optimizing away the loop
<- i + 1
i
} }
<- function() {
f3 for (i in 1:100) {
# Avoid optimizing away the loop
<- i + 1
i
} }
::microbenchmark(f1(), f2(), f3()) microbenchmark
#> Warning in microbenchmark::microbenchmark(f1(), f2(), f3()): less accurate
#> nanosecond times to avoid potential integer overflows
#> Unit: microseconds
#> expr min lq mean median uq max neval cld
#> f1() 10.332 10.496 103.29499 10.578 10.701 9277.398 100 a
#> f2() 1.394 1.435 8.29676 1.435 1.435 687.406 100 a
#> f3() 1.107 1.189 7.86011 1.189 1.189 667.767 100 a
MIT © Gábor Csárdi