[R-package] Add docs on building and using precompiled binaries for t…

…he R package (#3285) * add docs on binary packages * added docs on binary packages * [R-package] Add documentation on building and using precompiled binaries for the R package * Apply suggestions from code review Co-authored-by: Nikita Titov <[email protected]> * hyphens * Apply suggestions from code review Co-authored-by: Nikita Titov <[email protected]> * add notes on source package * add --no-multiarch to docs * add cran-comments to Rbuildignore * revert * Apply suggestions from code review Co-authored-by: Nikita Titov <[email protected]> Co-authored-by: Nikita Titov <[email protected]>
microsoft · Aug 12, 2020 · 2b0a09f · 2b0a09f
1 parent 877d58f
commit 2b0a09f
Showing 1 changed file with 116 additions and 0 deletions.
diff --git a/R-package/README.md b/R-package/README.md
@@ -13,6 +13,55 @@ LightGBM R-package
 Installation
 ------------
 
+### Installing the CRAN package
+
+As of this writing, `LightGBM`'s R package is not available on CRAN. However, start with `LightGBM` 3.0.0, you can install a released source distribution. This is the same type of package that you'd install from CRAN. It does not require `CMake`, Visual Studio, or anything else outside the CRAN toolchain.
+
+To install this package on any operating system:
+
+1. Choose a release from [the "Releases" page](https://github.com/microsoft/LightGBM/releases)
+2. Look for the artifact with a name like `lightgbm-{VERSION}-r-cran.tar.gz`. Right-click it and choose "copy link address".
+3. Copy that link into `PKG_URL` in the code below and run it.
+
+```r
+PKG_URL <- "https://github.com/microsoft/LightGBM/releases/download/v3.0.0rc1/lightgbm-3.0.0-1-r-cran.tar.gz"
+
+remotes::install_url(PKG_URL, INSTALL_OPTS = "--no-multiarch")
+```
+
+### Installing Precompiled Binaries
+
+Starting with `LightGBM` 3.0.0, precompiled binaries for the R package are created for each release. These packages do not require compilation, so they will be faster and easier to install than packages that are built from source. These packages are created with R 4.0 and are not guaranteed to work with other R versions.
+
+Binaries are available for Windows, Mac, and Linux systems. They are not guaranteed to work with all variants and versions of these operating systems. Please [open an issue](https://github.com/microsoft/LightGBM/issues) if you encounter any problems.
+
+To install a binary for the R package:
+
+1. Choose a release from [the "Releases" page](https://github.com/microsoft/LightGBM/releases).
+2. Choose a file based on your operating system. Right-click it and choose "copy link address".
+    * Linux: `lightgbm-{VERSION}-r40-linux.tgz`
+    * Mac: `lightgbm-{VERSION}-r40-macos.tgz`
+    * Windows: `lightgbm-{VERSION}-r40-windows.zip`
+3. Copy that link into `PKG_URL` in the code below and run it.
+
+This sample code installs version 3.0.0-1 of the R package on Mac.
+
+```r
+PKG_URL <- "https://github.com/microsoft/LightGBM/releases/download/v3.0.0rc1/lightgbm-3.0.0-1-r40-macos.tgz"
+
+local_file <- paste0("lightgbm.", tools::file_ext(PKG_URL))
+
+download.file(
+    url = PKG_URL
+    , destfile = local_file
+)
+install.packages(
+    pkgs = local_file
+    , type = "binary"
+    , repos = NULL
+)
+```
+
 ### Preparation
 
 You need to install git and [CMake](https://cmake.org/) first.
@@ -221,6 +270,73 @@ At build time, `configure.win` will be run and used to create a file `Makevars.w
 1. Edit `configure.win` directly
 2. Edit `src/Makevars.win.in`
 
+### Build Precompiled Binaries of the CRAN Package
+
+This section is mainly for maintainers. As long as the R package is not available on CRAN (which will build precompiled binaries automatically) you may want to build precompiled versions of the R package manually, since these will be easier for users to install.
+
+For more details, see ["Writing R Extensions"](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Building-binary-packages).
+
+Packages built like this will only work for the minor version of R used to build them. They may or may not work across different versions of operating systems.
+
+**Mac**
+
+Binary produced: `lightgbm-${VERSION}-r40-macos.tgz`.
+
+```shell
+LGB_VERSION="3.0.0-1"
+sh build-cran-package.sh
+R CMD INSTALL --build lightgbm_${LGB_VERSION}.tar.gz
+mv \
+    lightgbm_${LGB_VERSION}.tgz \
+    lightgbm-${LGB_VERSION}-r40-macos.tgz
+```
+
+**Linux**
+
+Binary produced: `lightgbm-${VERSION}-r40-linux.tgz`.
+
+You can access a Linux system that has R and its build toolchain installed with the `rocker` Docker images.
+
+```shell
+R_VERSION=4.0.2
+
+docker run \
+    -v $(pwd):/opt/LightGBM \
+    -it rocker/verse:${R_VERSION} \
+        /bin/bash
+```
+
+From inside that container, the commands to create a precompiled binary are very similar.
+
+```shell
+cd /opt/LightGBM
+LGB_VERSION="3.0.0-1"
+sh build-cran-package.sh
+R CMD INSTALL --build lightgbm_${LGB_VERSION}.tar.gz
+mv \
+    lightgbm_${LGB_VERSION}_R_*-linux-gnu.tar.gz \
+    lightgbm-${LGB_VERSION}-r40-linux.tgz
+```
+
+Exit the container, and the binary package should still be there on the host system.
+
+```shell
+exit
+```
+
+**Windows**
+
+Binary produced: `lightgbm-${VERSION}-r40-windows.zip`.
+
+```shell
+LGB_VERSION="3.0.0-1"
+sh build-cran-package.sh
+R CMD INSTALL --build lightgbm_${LGB_VERSION}.tar.gz
+mv \
+    lightgbm_${LGB_VERSION}.tgz \
+    lightgbm-${LGB_VERSION}-r40-windows.zip
+```
+
 External (Unofficial) Repositories
 ----------------------------------