2 title: "Arrow R Developer Guide"
3 output: rmarkdown::html_vignette
5 %\VignetteIndexEntry{Arrow R Developer Guide}
6 %\VignetteEngine{knitr::rmarkdown}
7 %\VignetteEncoding{UTF-8}
10 ```{r setup-options, include=FALSE}
11 knitr::opts_chunk$set(error = TRUE, eval = FALSE)
12 # Get environment variables describing what to evaluate
13 run <- tolower(Sys.getenv("RUN_DEVDOCS", "false")) == "true"
14 macos <- tolower(Sys.getenv("DEVDOCS_MACOS", "false")) == "true"
15 ubuntu <- tolower(Sys.getenv("DEVDOCS_UBUNTU", "false")) == "true"
16 sys_install <- tolower(Sys.getenv("DEVDOCS_SYSTEM_INSTALL", "false")) == "true"
17 # Update the source knit_hook to save the chunk (if it is marked to be saved)
18 knit_hooks_source <- knitr::knit_hooks$get("source")
19 knitr::knit_hooks$set(source = function(x, options) {
20 # Extra paranoia about when this will write the chunks to the script, we will
23 # * RUN_DEVDOCS is true
24 # * options$save is TRUE (and a check that not NULL won't crash it)
25 if (as.logical(Sys.getenv("CI", FALSE)) && run && !is.null(options$save) && options$save)
26 cat(x, file = "script.sh", append = TRUE, sep = "\n")
27 # but hide the blocks we want hidden:
28 if (!is.null(options$hide) && options$hide) {
31 knit_hooks_source(x, options)
35 ```{bash, save=run, hide=TRUE}
36 # Stop on failure, echo input as we go
41 If you're looking to contribute to arrow, this vignette can help you set up a development environment that will enable you to write code and run tests locally. It outlines:
43 * how to build the components that make up the Arrow project and R package
44 * workflows that developers use
45 * some common troubleshooting steps and solutions
47 This document is intended only for **developers** of Apache Arrow or the Arrow R package. R package users do not need to do any of this setup. If you're looking for how to install Arrow, see [the instructions in the readme](https://arrow.apache.org/docs/r/#installation).
49 This document is a work in progress and will grow and change as the Apache Arrow project grows and changes. We have tried to make these steps as robust as possible (in fact, we even test exactly these instructions on our nightly CI to ensure they don't become stale!), but custom configurations might conflict with these instructions and there are differences of opinion across developers about how to set up development environments like this.
51 We welcome any feedback you have about things that are confusing or additions you would like to see here - please [report an issue](https://issues.apache.org/jira/projects/ARROW/issues) if you have any suggestions or requests.
53 # Developer environment setup
57 Windows and macOS users who wish to contribute to the R package and
58 don't need to alter libarrow (Arrow's C++ library) may be able to obtain a
59 recent version of the library without building from source.
63 On Linux, you can download a .zip file containing libarrow from the
66 To see what nightlies are available, you can use arrow's (or any other S3 client's) S3 listing functionality to see what is in the bucket `s3://arrow-r-nightly/libarrow/bin`:
69 nightly <- s3_bucket("arrow-r-nightly")
70 nightly$ls("libarrow/bin")
72 Version numbers in that repository correspond to dates.
74 You'll need to create a `libarrow` directory inside the R package directory and unzip the zip file containing the compiled libarrow binary files into it.
77 On macOS, you can install libarrow using [Homebrew](https://brew.sh/):
80 # For the released version:
81 brew install apache-arrow
82 # Or for a development version, you can try:
83 brew install apache-arrow --HEAD
88 On Windows, you can download a .zip file containing libarrow from the nightly repository.
90 To see what nightlies are available, you can use arrow's (or any other S3 client's) S3 listing functionality to see what is in the bucket `s3://arrow-r-nightly/libarrow/bin`:
93 nightly <- s3_bucket("arrow-r-nightly")
94 nightly$ls("libarrow/bin")
96 Version numbers in that repository correspond to dates.
98 You can set the `RWINLIB_LOCAL` environment variable to point to the zip file containing libarrow before installing the arrow R package.
103 If you need to alter both libarrow and the R package code, or if you can't get a binary version of the latest libarrow elsewhere, you'll need to build it from source. This section discusses how to set up a C++ libarrow build configured to work with the R package. For more general resources, see the [Arrow C++ developer guide](https://arrow.apache.org/docs/developers/cpp/building.html).
105 There are five major steps to the process.
107 ### Step 1 - Install dependencies {.tabset}
109 When building libarrow, by default, system dependencies will be used if suitable versions are found. If system dependencies are not present, libarrow will build them during its own build process. The only dependencies that you need to install _outside_ of the build process are [cmake](https://cmake.org/) (for configuring the build) and [openssl](https://www.openssl.org/) if you are building with S3 support.
111 For a faster build, you may choose to pre-install more C++ library dependencies (such as [lz4](http://lz4.github.io/lz4/), [zstd](https://facebook.github.io/zstd/), etc.) on the system so that they don't need to be built from source in the libarrow build.
114 ```{bash, save=run & ubuntu}
115 sudo apt install -y cmake libcurl4-openssl-dev libssl-dev
119 ```{bash, save=run & macos}
120 brew install cmake openssl
125 Currently, the R package cannot be made to work with a local libarrow build. This will be resolved in a future release.
127 ### Step 2 - Configure the libarrow build
129 We recommend that you configure libarrow to be built to a user-level directory rather than a system directory for your development work. This is so that the development version you are using doesn't overwrite a released version of libarrow you may already have installed, and so that you are also able work with more than one version of libarrow (by using different `ARROW_HOME` directories for the different versions).
131 In the example below, libarrow is installed to a directory called `dist` that has the same parent directory as the `arrow` checkout. Your installation of the Arrow R package can point to any directory with any name, though we recommend *not* placing it inside of the `arrow` git checkout directory as unwanted changes could stop it working properly.
133 ```{bash, save=run & !sys_install}
134 export ARROW_HOME=$(pwd)/dist
138 _Special instructions on Linux:_ You will need to set `LD_LIBRARY_PATH` to the `lib` directory that is under where you set `$ARROW_HOME`, before launching R and using arrow. One way to do this is to add it to your profile (we use `~/.bash_profile` here, but you might need to put this in a different file depending on your setup, e.g. if you use a shell other than `bash`). On macOS you do not need to do this because the macOS shared library paths are hardcoded to their locations during build time.
140 ```{bash, save=run & ubuntu & !sys_install}
141 export LD_LIBRARY_PATH=$ARROW_HOME/lib:$LD_LIBRARY_PATH
142 echo "export LD_LIBRARY_PATH=$ARROW_HOME/lib:$LD_LIBRARY_PATH" >> ~/.bash_profile
145 Start by navigating in a terminal to the `arrow` repository. You will need to create a directory into which the C++ build will put its contents. We recommend that you make a `build` directory inside of the `cpp` directory of the Arrow git repository (it is git-ignored, so you won't accidentally check it in). Next, change directories to be inside `cpp/build`:
147 ```{bash, save=run & !sys_install}
153 You'll first call `cmake` to configure the build and then `make install`. For the R package, you'll need to enable several features in libarrow using `-D` flags:
155 ```{bash, save=run & !sys_install}
157 -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \
158 -DCMAKE_INSTALL_LIBDIR=lib \
162 -DARROW_EXTRA_ERROR_CONTEXT=ON \
163 -DARROW_FILESYSTEM=ON \
164 -DARROW_INSTALL_NAME_RPATH=OFF \
165 -DARROW_JEMALLOC=ON \
168 -DARROW_WITH_SNAPPY=ON \
169 -DARROW_WITH_ZLIB=ON \
173 `..` refers to the C++ source directory: you're in `cpp/build` and the source is in `cpp`.
175 #### Enabling more Arrow features
177 To enable optional features including: S3 support, an alternative memory allocator, and additional compression libraries, add some or all of these flags to your call to `cmake` (the trailing `\` makes them easier to paste into a bash shell on a new line):
180 -DARROW_MIMALLOC=ON \
182 -DARROW_WITH_BROTLI=ON \
183 -DARROW_WITH_BZ2=ON \
184 -DARROW_WITH_LZ4=ON \
185 -DARROW_WITH_SNAPPY=ON \
186 -DARROW_WITH_ZSTD=ON \
189 Other flags that may be useful:
191 * `-DBoost_SOURCE=BUNDLED` and `-DThrift_SOURCE=BUNDLED`, for example, or any other dependency `*_SOURCE`, if you have a system version of a C++ dependency that doesn't work correctly with Arrow. This tells the build to compile its own version of the dependency from source.
193 * `-DCMAKE_BUILD_TYPE=debug` or `-DCMAKE_BUILD_TYPE=relwithdebinfo` can be useful for debugging. You probably don't want to do this generally because a debug build is much slower at runtime than the default `release` build.
195 _Note_ `cmake` is particularly sensitive to whitespacing, if you see errors, check that you don't have any errant whitespace.
197 ### Step 3 - Building libarrow
199 You can add `-j#` between `make` and `install` here too to speed up compilation by running in parallel (where `#` is the number of cores you have available).
201 ```{bash, save=run & !(sys_install & ubuntu)}
205 ### Step 4 - Build the Arrow R package
207 Once you've built libarrow, you can install the R package and its
208 dependencies, along with additional dev dependencies, from the git
212 popd # To go back to the root directory of the project, from cpp/build
214 R -e 'install.packages("remotes"); remotes::install_deps(dependencies = TRUE)'
218 #### Compilation flags
220 If you need to set any compilation flags while building the C++
221 extensions, you can use the `ARROW_R_CXXFLAGS` environment variable. For
222 example, if you are using `perf` to profile the R extensions, you may
226 export ARROW_R_CXXFLAGS=-fno-omit-frame-pointer
229 #### Recompiling the C++ code
231 With the setup described here, you should not need to rebuild the Arrow library or even the C++ source in the R package as you iterate and work on the R package. The only time those should need to be rebuilt is if you have changed the C++ in the R package (and even then, `R CMD INSTALL .` should only need to recompile the files that have changed) _or_ if the libarrow C++ has changed and there is a mismatch between libarrow and the R package. If you find yourself rebuilding either or both each time you install the package or run tests, something is probably wrong with your set up.
234 <summary>For a full build: a `cmake` command with all of the R-relevant optional dependencies turned on. Development with other languages might require different flags as well. For example, to develop Python, you would need to also add `-DARROW_PYTHON=ON` (though all of the other flags used for Python are already included here).</summary>
239 -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \
240 -DCMAKE_INSTALL_LIBDIR=lib \
244 -DARROW_EXTRA_ERROR_CONTEXT=ON \
245 -DARROW_FILESYSTEM=ON \
246 -DARROW_INSTALL_NAME_RPATH=OFF \
247 -DARROW_JEMALLOC=ON \
249 -DARROW_MIMALLOC=ON \
252 -DARROW_WITH_BROTLI=ON \
253 -DARROW_WITH_BZ2=ON \
254 -DARROW_WITH_LZ4=ON \
255 -DARROW_WITH_SNAPPY=ON \
256 -DARROW_WITH_ZLIB=ON \
257 -DARROW_WITH_ZSTD=ON \
263 ## Installing a version of the R package with a specific git reference
265 If you need an arrow installation from a specific repository or git reference, on most platforms except Windows, you can run:
268 remotes::install_github("apache/arrow/r", build = FALSE)
271 The `build = FALSE` argument is important so that the installation can access the
272 C++ source in the `cpp/` directory in `apache/arrow`.
274 As with other installation methods, setting the environment variables `LIBARROW_MINIMAL=false` and `ARROW_R_DEV=true` will provide a more full-featured version of Arrow and provide more verbose output, respectively.
276 For example, to install from the (fictional) branch `bugfix` from `apache/arrow` you could run:
279 Sys.setenv(LIBARROW_MINIMAL="false")
280 remotes::install_github("apache/arrow/r@bugfix", build = FALSE)
283 Developers may wish to use this method of installing a specific commit
284 separate from another Arrow development environment or system installation
285 (e.g. we use this in [arrowbench](https://github.com/ursacomputing/arrowbench)
286 to install development versions of libarrow isolated from the system install). If
287 you already have libarrow installed system-wide, you may need to set
288 some additional variables in order to isolate this build from your system libraries:
290 * Setting the environment variable `FORCE_BUNDLED_BUILD` to `true` will skip the `pkg-config` search for libarrow and attempt to build from the same source at the repository+ref given.
292 * You may also need to set the Makevars `CPPFLAGS` and `LDFLAGS` to `""` in order to prevent the installation process from attempting to link to already installed system versions of libarrow. One way to do this temporarily is wrapping your `remotes::install_github()` call like so:
294 withr::with_makevars(list(CPPFLAGS = "", LDFLAGS = ""), remotes::install_github(...))
297 # Common developer workflow tasks
299 The `arrow/r` directory contains a `Makefile` to help with some common tasks from the command line (e.g. `make test`, `make doc`, `make clean`, etc.).
303 You can load the R package via `devtools::load_all()`.
305 ## Rebuilding the documentation
307 The R documentation uses the [`@examplesIf`](https://roxygen2.r-lib.org/articles/rd.html#functions) tag introduced in `roxygen2` version 7.1.1.9001, which hasn't yet been released on CRAN at the time of writing. If you are making changes which require updating the documentation, please install the development version of `roxygen2` from GitHub.
310 remotes::install_github("r-lib/roxygen2")
313 You can use `devtools::document()` and `pkgdown::build_site()` to rebuild the documentation and preview the results.
316 # Update roxygen documentation
319 # To preview the documentation website
320 pkgdown::build_site(preview=TRUE)
323 ## Styling and linting
327 The R code in the package follows [the tidyverse style](https://style.tidyverse.org/). On PR submission (and on pushes) our CI will run linting and will flag possible errors on the pull request with annotations.
329 To run the [lintr](https://github.com/jimhester/lintr) locally, install the lintr package (note, we currently use a fork that includes fixes not yet accepted upstream, see how lintr is being installed in the file `ci/docker/linux-apt-lint.dockerfile` for the current status) and then run
332 lintr::lint_package("arrow/r")
335 You can automatically change the formatting of the code in the package using the [styler](https://styler.r-lib.org/) package. There are two ways to do this:
337 1. Use the comment bot to do this automatically with the command `@github-actions autotune` on a PR, and commit it back to the branch.
339 2. Run the styler locally either via Makefile commands:
342 make style # (for only the files changed)
343 make style-all # (for all files)
349 # note the two excluded files which should not be styled
350 styler::style_pkg(exclude_files = c("tests/testthat/latin1.R", "data-raw/codegen.R"))
353 The styler package will fix many styling errors, thought not all lintr errors are automatically fixable with styler. The list of files we intentionally do not style is in `r/.styler_excludes.R`.
357 The arrow package uses some customized tools on top of [cpp11](https://cpp11.r-lib.org/) to prepare its
358 C++ code in `src/`. This is because there are some features that are only enabled
359 and built conditionally during build time. If you change C++ code in the R
360 package, you will need to set the `ARROW_R_DEV` environment variable to `true`
361 (optionally, add it to your `~/.Renviron` file to persist across sessions) so
362 that the `data-raw/codegen.R` file is used for code generation. The `Makefile`
363 commands also handles this automatically.
365 We use Google C++ style in our C++ code. The easiest way to accomplish this is
366 use an editors/IDE that formats your code for you. Many popular editors/IDEs
367 have support for running `clang-format` on C++ files when you save them.
368 Installing/enabling the appropriate plugin may save you much frustration.
370 Check for style errors with
376 Fix any style issues before committing with
382 The lint script requires Python 3 and `clang-format-8`. If the command
383 isn't found, you can explicitly provide the path to it like:
386 CLANG_FORMAT=$(which clang-format-8) ./lint.sh
389 On macOS, you can get this by installing LLVM via Homebrew and running the script as:
391 CLANG_FORMAT=$(brew --prefix llvm@8)/bin/clang-format ./lint.sh
394 _Note_ that the lint script requires Python 3 and the Python dependencies
395 (note that `cmake_format is pinned to a specific version):
399 * cmake_format==0.5.2
403 Tests can be run either using `devtools::test()` or the Makefile alternative.
406 # Run the test suite, optionally filtering file names
407 devtools::test(filter="^regexp$")
409 # or the Makefile alternative from the arrow/r directory in a shell:
410 make test file=regexp
413 Some tests are conditionally enabled based on the availability of certain
414 features in the package build (S3 support, compression libraries, etc.).
415 Others are generally skipped by default but can be enabled with environment
416 variables or other settings:
418 * All tests are skipped on Linux if the package builds without the C++ libarrow.
419 To make the build fail if libarrow is not available (as in, to test that
420 the C++ build was successful), set `TEST_R_WITH_ARROW=true`
422 * Some tests are disabled unless `ARROW_R_DEV=true`
424 * Tests that require allocating >2GB of memory to test Large types are disabled
425 unless `ARROW_LARGE_MEMORY_TESTS=true`
427 * Integration tests against a real S3 bucket are disabled unless credentials
428 are set in `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`; these are available
431 * S3 tests using [MinIO](https://min.io/) locally are enabled if the
432 `minio server` process is found running. If you're running MinIO with custom
433 settings, you can set `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, and
434 `MINIO_PORT` to override the defaults.
438 You can run package checks by using `devtools::check()` and check test coverage
439 with `covr::package_coverage()`.
445 # See test coverage statistics
447 covr::package_coverage()
450 For full package validation, you can run the following commands from a terminal.
454 R CMD check arrow_*.tar.gz --as-cran
458 ## Running additional CI checks
460 On a pull request, there are some actions you can trigger by commenting on the
461 PR. We have additional CI checks that run nightly and can be requested on demand
462 using an internal tool called
463 [crossbow](https://arrow.apache.org/docs/developers/crossbow.html).
464 A few important GitHub comment commands are shown below.
466 #### Run all extended R CI tasks
468 @github-actions crossbow submit -g r
471 This runs each of the R-related CI tasks.
473 #### Run a specific task
475 @github-actions crossbow submit {task-name}
478 See the `r:` group definition near the beginning of the [crossbow configuration](https://github.com/apache/arrow/blob/master/dev/tasks/tasks.yml)
479 for a list of glob expression patterns that match names of items in the `tasks:`
482 #### Run linting and documentation building tasks
485 @github-actions autotune
488 This will run and fix lint C++ linting errors, run R documentation (among other
489 cleanup tasks), run styler on any changed R code, and commit the resulting
490 updates to the branch.
492 # Summary of environment variables
494 * See the user-facing [Install vignette](install.html) for a large number of
495 environment variables that determine how the build works and what features
497 * `TEST_OFFLINE_BUILD`: When set to `true`, the build script will not download
498 prebuilt the C++ library binary.
499 It will turn off any features that require a download, unless they're available
500 in the `tools/cpp/thirdparty/download/` subfolder of the tar.gz file.
501 `create_package_with_all_dependencies()` creates that subfolder.
502 Regardless of this flag's value, `cmake` will be downloaded if it's unavailable.
503 * `TEST_R_WITHOUT_LIBARROW`: When set to `true`, skip tests that would require
504 the C++ Arrow library (that is, almost everything).
508 Note that after any change to libarrow, you must reinstall it and
509 run `make clean` or `git clean -fdx .` to remove any cached object code
510 in the `r/src/` directory before reinstalling the R package. This is
511 only necessary if you make changes to libarrow source; you do not
512 need to manually purge object files if you are only editing R or C++
515 ## Arrow library - R package mismatches
517 If libarrow and the R package have diverged, you will see errors like:
520 Error: package or namespace load failed for ‘arrow' in dyn.load(file, DLLpath = DLLpath, ...):
521 unable to load shared object '/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so':
522 dlopen(/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so, 6): Symbol not found: __ZN5arrow2io16RandomAccessFile9ReadAsyncERKNS0_9IOContextExx
523 Referenced from: /Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so
524 Expected in: flat namespace
525 in /Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so
526 Error: loading failed
528 ERROR: loading failed
531 To resolve this, try [rebuilding the Arrow library](#step-3-building-arrow).
533 ## Multiple versions of libarrow
535 If you are installing from a user-level directory, and you already have a
536 previous installation of libarrow in a system directory, you get you may get
537 errors like the following when you install the R package:
540 Error: package or namespace load failed for ‘arrow' in dyn.load(file, DLLpath = DLLpath, ...):
541 unable to load shared object '/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so':
542 dlopen(/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so, 6): Library not loaded: /usr/local/lib/libarrow.400.dylib
543 Referenced from: /usr/local/lib/libparquet.400.dylib
544 Reason: image not found
547 If this happens, you need to make sure that you don't let R link to your system
548 library when building arrow. You can do this a number of different ways:
550 * Setting the `MAKEFLAGS` environment variable to `"LDFLAGS="` (see below for an example) this is the recommended way to accomplish this
551 * Using {withr}'s `with_makevars(list(LDFLAGS = ""), ...)`
552 * adding `LDFLAGS=` to your `~/.R/Makevars` file (the least recommended way, though it is a common debugging approach suggested online)
554 ```{bash, save=run & !sys_install & macos, hide=TRUE}
555 # Setup troubleshooting section
556 # install a system-level arrow on macOS
557 brew install apache-arrow
561 ```{bash, save=run & !sys_install & ubuntu, hide=TRUE}
562 # Setup troubleshooting section
563 # install a system-level arrow on Ubuntu
565 sudo apt install -y -V ca-certificates lsb-release wget
566 wget https://apache.jfrog.io/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
567 sudo apt install -y -V ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
569 sudo apt install -y -V libarrow-dev
572 ```{bash, save=run & !sys_install & macos}
573 MAKEFLAGS="LDFLAGS=" R CMD INSTALL .
579 If the package fails to install/load with an error like this:
582 ** testing if installed package can be loaded from temporary location
583 Error: package or namespace load failed for 'arrow' in dyn.load(file, DLLpath = DLLpath, ...):
584 unable to load shared object '/Users/you/R/00LOCK-r/00new/arrow/libs/arrow.so':
585 dlopen(/Users/you/R/00LOCK-r/00new/arrow/libs/arrow.so, 6): Library not loaded: @rpath/libarrow.14.dylib
588 ensure that `-DARROW_INSTALL_NAME_RPATH=OFF` was passed (this is important on
589 macOS to prevent problems at link time and is a no-op on other platforms).
590 Alternatively, try setting the environment variable `R_LD_LIBRARY_PATH` to
591 wherever Arrow C++ was put in `make install`, e.g. `export
592 R_LD_LIBRARY_PATH=/usr/local/lib`, and retry installing the R package.
594 When installing from source, if the R and C++ library versions do not
595 match, installation may fail. If you've previously installed the
596 libraries and want to upgrade the R package, you'll need to update the
597 Arrow C++ library first.
599 For any other build/configuration challenges, see the [C++ developer
600 guide](https://arrow.apache.org/docs/developers/cpp/building.html).
602 ## Other installation issues
604 There are a number of scripts that are triggered when the arrow R package is installed. For package users who are not interacting with the underlying code, these should all just work without configuration and pull in the most complete pieces (e.g. official binaries that we host). However, knowing about these scripts can help package developers troubleshoot if things go wrong in them or things go wrong in an install. See [the installation vignette](./install.html#how-dependencies-are-resolved) for more information.