jonkeane commented on a change in pull request #9898:
URL: https://github.com/apache/arrow/pull/9898#discussion_r611877094
##########
File path: r/vignettes/dev-docs.Rmd
##########
@@ -0,0 +1,349 @@
+---
+title: "Arrow R Package Developer Documentation"
+output: rmarkdown::html_vignette
+vignette: >
+ %\VignetteIndexEntry{Arrow R Package Developer Documentation}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+```{r setup options, include=FALSE}
+knitr::opts_chunk$set(error = TRUE, eval = FALSE)
+
+# Get environment variables describing what to evaluate
+run <- tolower(Sys.getenv("RUN_DEVDOCS", "false")) == "true"
+macos <- tolower(Sys.getenv("DEVDOCS_MACOS", "false")) == "true"
+ubuntu <- tolower(Sys.getenv("DEVDOCS_UBUNTU", "false")) == "true"
+sys_install <- tolower(Sys.getenv("DEVDOCS_SYSTEM_INSTALL", "false")) == "true"
+
+# Update the source knit_hook to save the chunk (if it is marked to be saved)
+knit_hooks_source <- knitr::knit_hooks$get("source")
+knitr::knit_hooks$set(source = function(lines, options) {
+ # Extra paranoia about when this will write the chunks to the script, we will
+ # only save when:
+ # * CI is true
+ # * RUN_DEVDOCS is true
+ # * options$save is TRUE (and a check that not NULL won't crash it)
+ if (as.logical(Sys.getenv("CI", FALSE)) && run && !is.null(options$save) &&
options$save)
+ cat(lines, file = "script.sh", append = TRUE, sep = "\n")
+ NULL
+})
+```
+
+```{bash, save=run}
+# Stop on failure, echo input as we go
+set -e
+set -x
+```
+
+## R-only development
+
+Windows and macOS users who wish to contribute to the R package and
+don’t need to alter the Arrow C++ library may be able to obtain a
+recent version of the library without building from source. On macOS,
+you may install the C++ library using [Homebrew](https://brew.sh/):
+
+``` shell
+# For the released version:
+brew install apache-arrow
+# Or for a development version, you can try:
+brew install apache-arrow --HEAD
+```
+
+On Windows, you can download a .zip file with the arrow dependencies from the
+[nightly
repository](https://arrow-r-nightly.s3.amazonaws.com/libarrow/bin/windows/),
+and then set the `RWINLIB_LOCAL` environment variable to point to that
+zip file before installing the `arrow` R package. Version numbers in that
+repository correspond to dates, and you will likely want the most recent.
+
+## Developer envorinment setup
+
+If you need to alter both the Arrow C++ library and the R package code, or if
you can’t get a binary version of the latest C++ library elsewhere, you’ll need
to build it from source too.
+
+First, install the C++ library. See the [developer
+guide](https://arrow.apache.org/docs/developers/cpp/building.html) for
details.
+
+### Install dependencies {.tabset}
+
+These dependencies are technically only needed for S3 support(?)
+
+#### macOS
+```{bash, save=run & macos}
+brew install openssl
+```
+
+#### ubuntu
+```{bash, save=run & ubuntu}
+sudo apt install -y libcurl4-openssl-dev libssl-dev
+```
+
+
+### Building Arrow {.tabset}
+
+It’s recommended to make a build directory inside of the cpp directory of the
Arrow git repository (it is git-ignored). Assuming you are inside cpp/build,
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 the C++ library using -D
flags:
+
+#### Installing to another directory
+
+If you would like to use arrow from an alternative directory
+
+```{bash, save=run & !sys_install}
+export ARROW_HOME=$(pwd)/dist
+export LD_LIBRARY_PATH=$(pwd)/dist/lib
+export INCLUDE_DIR=$ARROW_HOME/include
+export LIB_DIR=$ARROW_HOME/lib
+```
+
+TODO: how to add these vars separated by colons if they have other things in
them already (eg LD_LIBRARY_PATH=$(pwd)/dist/lib:$LD_LIBRARY_PATH)
+
+On linux, you will need to set `LD_LIBRARY_PATH` to this same directory before
launching R and using Arrow. One way to do this is to add it to your profile. #
TODO: do we want to recommend this? Is there any other alternative?
Review comment:
I don't think that Makevars will do it, since this is important at
runtime not at build time, but I'll try it and see.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
