thisisnic commented on a change in pull request #11521:
URL: https://github.com/apache/arrow/pull/11521#discussion_r761046643
##########
File path: r/vignettes/developers/install_details.Rmd
##########
@@ -0,0 +1,107 @@
+# How the R package is installed
+
+In order for the arrow R package to work, it needs the Arrow C++ library,
+also known as libarrow. 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).
+
+This documented 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)
+
+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.
+
+* `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.
+
+There are a number of different ways you can install libarrow:
+
+* 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
+
+When you install the R package, it will attempt to detect any existing
+installation of libarrow, and if none are found, it will install a copy. The
+following section explains how this process works.
+
+## How the R package finds libarrow
+
+The diagram below shows how the R package finds a libarrow installation.
+
+```{r, echo=FALSE, out.width="70%"}
+knitr::include_graphics("../img/install_diagram.png")
+```
+
+### 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.
+
+# libarrow dependencies
+
+You'll need to install `libparquet-dev` on Debian and Ubuntu, or
`parquet-devel` on CentOS.
+This will also automatically install libarrow as a dependency.
Review comment:
This doesn't fit here but I'm not sure where it should go.
--
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.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
