ARROW-13398: [R] Update install.Rmd vignette

r/_pkgdown.yml

@@ -80,6 +80,8 @@ navbar:
             href: articles/developers/workflow.html
           - text: Debugging
             href: articles/developers/debugging.html
+          - text: Package Installation Details
+            href: articles/developers/install_details.html
 reference:
   - title: Multi-file datasets
     contents:

r/vignettes/developers/install_details.Rmd

@@ -0,0 +1,124 @@
+---
+title: "How the R package is installed - advanced"
+---
+
+This document is intended specifically for arrow _developers_ who wish to know 
+more about these scripts.  If you are an arrow _user_ looking for help with 
+installing arrow, please see [the installation guide](../install.html)
+
+The arrow R package requires that Arrow C++ library (also known as libarrow) to 
+be installed in order to work properly.  There are a number of different ways 
+in which libarrow could be installed:
+
+* as part of the R package installation process
+* a system package
+* a library you've built yourself outside of the context of installing the R package
+
+Below, we discuss each of these setups in turn.
+
+# Installing libarrow during R package installation
+
+There are a number of scripts that are triggered 
+when `R CMD INSTALL .` is run and for Arrow users, these should all just work 
+without configuration and pull in the most complete pieces (e.g. official 
+binaries that we host).  One of the jobs of these scripts is to work out
+if libarrow is installed, and if not, install it.
+
+An overview of these scripts is shown below:
+
+* `configure` and `configure.win` - these scripts are triggered during
+`R CMD INSTALL .` on non-Windows and Windows platforms, respectively. They
+handle finding the libarrow, setting up the build variables necessary, and
+writing the package Makevars file that is used to compile the C++ code in the R
+package.
+
+* `tools/nixlibs.R` - this script is sometimes called by `configure` on Linux
+(or on any non-windows OS with the environment variable
+`FORCE_BUNDLED_BUILD=true`) if an existing libarrow installation cannot be found.
+This sets up the build process for our bundled builds (which is the default on 
+linux) and checks for binaries or downloads libarrow from source depending on 
+dependency availability and build configuration.
+
+* `tools/winlibs.R` - this script is sometimes called by `configure.win` on Windows
+when environment variable `ARROW_HOME` is not set.  It looks for an existing libarrow
+installation, and if it can't find one downloads an appropriate libarrow binary.
+
+* `inst/build_arrow_static.sh` - called by `tools/nixlibs.R` when libarrow  
+needs to be built.  It builds libarrow for a bundled, static build, and
+mirrors the steps described in the ["Arrow R Developer Guide" vignette](./setup.html)
+This build script is also what is used to generate our prebuilt binaries.
+
+The actions taken by these scripts to resolve dependencies and install the 
+correct components are described below.
+
+## How the R package finds libarrow
+
+### Windows
+
+The diagram below shows how the R package finds a libarrow installation on Windows.
+
+```{r, echo=FALSE, out.width="70%"}
+knitr::include_graphics("./install_diagram_windows.png")
+```
+
+### Linux
+
+The diagram below shows how the R package finds a libarrow installation on non-Windows systems.
+
+```{r, echo=FALSE, out.width="70%"}
+knitr::include_graphics("./install_nix.png")
+```
+
+More information about these steps can be found below.
+
+#### Using pkg-config
+
+When you install the arrow R package on Linux, if no environment variables 
+relating to the location of an existing libarrow installation have already by 
+set, the installation code will attempt to find libarrow on
+your system using the `pkg-config` command.
+
+This will find either installed system packages or libraries you've built yourself.
+In order for `install.packages("arrow")` to work with these system packages,
+you'll need to install them before installing the R package.
+
+#### Prebuilt binaries
+
+If libarrow is not found on the system, the R package installation 
+script will next attempt to download prebuilt libarrow binaries
+that match your both your local operating system and arrow R package version.
+The libarrow binaries will only be retrieved if you have set the environment variable
+`LIBARROW_BINARY` or `NOT_CRAN`.
+
+If found, they will be downloaded and bundled when your R package compiles.
+For a list of supported distributions and versions,
+see the [arrow-r-nightly](https://github.com/ursa-labs/arrow-r-nightly/blob/master/README.md) project.
+
+#### Building from source
+
+If no libarrow binary is found, it will attempt to build it locally.
+First, it will also look to see if you are in a checkout of the `apache/arrow` 
+git repository and thus have the libarrow source files there.
+Otherwise, it builds from the source files included in the package.
+Depending on your system, building libarrow from source may be slow. If 
+libarrow is built from source, `inst/build_arrow_static.sh` is executed.
+
+# Using the R package with libarrow installed as a system package
+
+If you are authorized to install system packages and you're installing a CRAN release,
+you may want to use the official Apache Arrow release packages corresponding to 
+the R package version via software distribution tools such as `apt` or `yum` 
+(though there are some drawbacks: see the 
+["Troubleshooting" section in the main installation docs]("../install.html)).
+See the [Arrow project installation page](https://arrow.apache.org/install/)
+to find pre-compiled binary packages for some common Linux distributions,
+including Debian, Ubuntu, and CentOS.
+
+Generally, we do not recommend this method of working with libarrow with the R 
+package unless you have a specific reason to do so. 
+
+# Using the R package with an existing libarrow build
+
+This setup is much more common for arrow developers, who may be needing to make
+changes to both the R package and libarrow source code.  See 
+the [developer setup docs](./setup.html) for more information.