This is an automated email from the ASF dual-hosted git repository.
thisisnic pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 8f0a560 ARROW-14654: [R][Docs] Add article on how to run R with C++
debugger to dev docs
8f0a560 is described below
commit 8f0a5602a1457f9563bbb5e4c45a361a51e72d70
Author: Nic Crane <[email protected]>
AuthorDate: Mon Nov 15 10:12:57 2021 +0000
ARROW-14654: [R][Docs] Add article on how to run R with C++ debugger to dev
docs
This PR adds an article about how to run R with the C++ debugger to the dev
docs. It also adds a submenu for articles to be published on the `pkgdown`
site but not distributed with the package as vignettes. Note that the current
R developer guide remains as it's own menu option so we don't break links to it
in other packages.
Closes #11658 from thisisnic/ARROW-14654_debugger_docs
Authored-by: Nic Crane <[email protected]>
Signed-off-by: Nic Crane <[email protected]>
---
r/_pkgdown.yml | 4 ++
r/vignettes/developers/debugging.Rmd | 98 ++++++++++++++++++++++++++++++++++++
2 files changed, 102 insertions(+)
diff --git a/r/_pkgdown.yml b/r/_pkgdown.yml
index b3db0e0..988717a 100644
--- a/r/_pkgdown.yml
+++ b/r/_pkgdown.yml
@@ -72,6 +72,10 @@ navbar:
href: articles/flight.html
- text: Arrow R Developer Guide
href: articles/developing.html
+ - text: Developers
+ menu:
+ - text: Debugging
+ href: articles/developers/debugging.html
reference:
- title: Multi-file datasets
contents:
diff --git a/r/vignettes/developers/debugging.Rmd
b/r/vignettes/developers/debugging.Rmd
new file mode 100644
index 0000000..a18178d
--- /dev/null
+++ b/r/vignettes/developers/debugging.Rmd
@@ -0,0 +1,98 @@
+# Debugging Arrow
+
+If you are a developer working with Arrow code, the package's use of tidy eval
+and C++ necessitates a solid debugging strategy. In this article, we recommend
+a few approaches.
+
+## Debugging R code
+
+In general, we have found that using interactive debugging (e.g. calls to
+`browser()`), where you can inspect objects in a particular environment, is
+more efficient than simpler techniques such as `print()` statements.
+
+## Getting more descriptive C++ error messages after a segfault
+
+If you are working in the RStudio IDE, your R session will be aborted if there
is
+a segfault. If you re-run your code in a command-line R session, the session
+isn't automatically aborted and so it will be possible to copy the error
+message accompanying the segfault. Here is an example from a bug which
+existed at time of writing.
+
+```shell
+> S3FileSystem$create()
+
+ *** caught segfault ***
+address 0x1a0, cause 'memory not mapped'
+
+Traceback:
+ 1: (function (anonymous, access_key, secret_key, session_token, role_arn,
session_name, external_id, load_frequency, region, endpoint_override,
scheme, background_writes) { .Call(`_arrow_fs___S3FileSystem__create`,
anonymous, access_key, secret_key, session_token, role_arn,
session_name, external_id, load_frequency, region, endpoint_override,
scheme, background_writes)})(access_key = "", secret_key = "", session_token =
"", role_arn = "", session_name = "" [...]
+ 2: exec(fs___S3FileSystem__create, !!!args)
+ 3: S3FileSystem$create()
+```
+
+This output provides the R traceback; however, it doesn't provide any
+information about the exact line of C++ code from which the segfault
originated.
+For this, you will need to run R with the C++ debugger attached.
+
+### Running R code with the C++ debugger attached
+
+As Arrow has C++ code at its core, debugging code can sometimes be tricky when
+errors originate in the C++ rather than the R layer. If you are adding new
code
+which triggers a C++ bug (or find one in existing code), this can result in a
+segfault. If you are working in RStudio, the session is aborted, and you may
+not be able to retrieve the error messaging needed to diagnose and/or report
+the bug. One way around this is to find the code that causes the error, and
+run R with a C++ debugger.
+
+If you are using macOS and have installed R using the Apple installer, you
will
+not be able to run R with a debugger attached; please see [the instructions
here for details on causes of this and
workarounds.](https://mac.r-project.org/bin/macosx/RMacOSX-FAQ.html#I-cannot-attach-debugger-to-R)
+
+Firstly, load R with your debugger. The most common debuggers are `gdb`
+(typically found on Linux, sometimes on macOS, or Windows via MinGW or Cygwin)
+and `lldb` (the default macOS debugger).
+
+In my case it's `gdb`, but if you're using the `lldb` debugger (for example,
+if you're on a Mac), just swap in that command here.
+
+```shell
+R -d gdb
+```
+
+Next, run R.
+
+```shell
+run
+```
+
+You should now be in an R session with the C++ debugger attached. This will
+look similar to a normal R session, but with extra output.
+
+Now, run your code - either directly in the session or by sourcing it from a
+file. If the code results in a segfault, you will have extra output that you
+can use to diagnose the problem or attach to an issue as extra information.
+
+Here is debugger output from the segfault shown in the previous example. You
+can see here that the exact line which triggers the segfault is included in
the
+output.
+
+```
+> S3FileSystem$create()
+
+Thread 1 "R" received signal SIGSEGV, Segmentation fault.
+0x00007ffff0128369 in std::__atomic_base<long>::operator++ (this=0x178) at
/usr/include/c++/9/bits/atomic_base.h:318
+318 operator++() noexcept
+```
+
+## Resources
+
+The following resources provide detailed guides to debugging R code:
+
+* [The chapter on debugging in 'Advanced R' by Hadley
Wickham](https://adv-r.hadley.nz/debugging.html)
+* [The RStudio debugging
documentation](https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio)
+
+For an excellent in-depth guide to using the C++ debugger in R, see [this blog
+post by David
Vaughan.](https://blog.davisvaughan.com/2019/04/05/debug-r-package-with-cpp/)
+
+You can find a list of equivalent [gdb and lldb commands on the LLDB
website.](https://lldb.llvm.org/use/map.html)
+
+
