-
Notifications
You must be signed in to change notification settings - Fork 10
/
Copy pathREADME.Rmd
158 lines (120 loc) · 3.72 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
```{r, setup, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
comment = "#>",
tidy = FALSE,
error = FALSE,
fig.width = 8,
fig.height = 8)
```
# debugme
> Debug R Packages
<!-- badges: start -->
[](https://github.com/r-lib/debugme/actions/workflows/R-CMD-check.yaml)
[](https://www.r-pkg.org/pkg/debugme)
[](https://www.r-pkg.org/pkg/debugme)
[](https://app.codecov.io/gh/r-lib/debugme?branch=main)
<!-- badges: end -->
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](https://github.com/debug-js/debug).
## Installation and Usage
Stable version:
```{r eval = FALSE}
install.packages("debugme")
```
To install the development version:
```{r eval = FALSE}
pak::pak("r-lib/debugme")
```
To use `debugme` in your package, import it, and then add the following
`.onLoad` function to your package:
```r
.onLoad <- function(libname, pkgname) {
debugme::debugme()
}
```
You can now add debug messages via character literals. No function calls
are necessary. For example:
```r
"!DEBUG Start up phantomjs"
private$start_phantomjs(phantom_debug_level)
"!DEBUG Start up shiny"
private$start_shiny(path)
"!DEBUG create new phantomjs session"
private$web <- session$new(port = private$phantom_port)
"!DEBUG navigate to Shiny app"
private$web$go(private$get_shiny_url())
```
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:
```sh
export DEBUGME=mypackage
```
Or from within R:
```r
Sys.setenv(DEBUGME = "mypackage")
```
Separate multiple package names with commas:
```sh
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.
## Example
## Dynamic code
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:
```r
"!DEBUG x = `x`, y = `y`"
if (x != y) {
...
```
## Motivation
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.
### Performance
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.
```{r}
debug <- function(msg) { }
f1 <- function() {
for (i in 1:100) {
debug("foobar")
# Avoid optimizing away the loop
i <- i + 1
}
}
```
```{r}
f2 <- function() {
for (i in 1:100) {
"!DEBUG foobar"
# Avoid optimizing away the loop
i <- i + 1
}
}
```
```{r}
f3 <- function() {
for (i in 1:100) {
# Avoid optimizing away the loop
i <- i + 1
}
}
```
```{r}
microbenchmark::microbenchmark(f1(), f2(), f3())
```
## License
MIT © [Gábor Csárdi](https://github.com/gaborcsardi)