[R-package] [docs] Reorganize installation instructions (fixes micros…

…oft#3320)
jameslamb · Sep 7, 2020 · 334bf54 · 334bf54
1 parent afc76d2
commit 334bf54
Showing 1 changed file with 75 additions and 45 deletions.
diff --git a/R-package/README.md b/R-package/README.md
@@ -5,6 +5,11 @@
 ### Contents
 
 * [Installation](#installation)
+    - [Installing the CRAN package](#installing-the-cran-package)
+    - [Installing from Source with CMake](#installing-from-source-with-cmake)
+    - [Installing a GPU-enabled Build](#installing-a-gpu-enabled-build)
+    - [Installing Precompiled Binaries](#installing-precompiled-binaries)
+    - [Installing from a Pre-compiled lib_lightgbm](#lib_lightgbm)
 * [Examples](#examples)
 * [Testing](#testing)
 * [Preparing a CRAN Package and Installing It](#preparing-a-cran-package-and-installing-it)
@@ -14,63 +19,56 @@
 Installation
 ------------
 
-### Installing the CRAN package
+For the easiest installation, go to ["Installing the CRAN package"](#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.
+If you experience any issues with that, try ["Installing from Source with CMake"](#install). This can produce a more efficient version of the library on Windows systems witth Visual Studio.
 
-To install this package on any operating system:
+To build a GPU-enabled version of the package, follow the steps in ["Installing a GPU-enabled Build"](#installing-a-gpu-enabled-build)
 
-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.
+If any of the above options do not work for you or do not meet your needs, please let the maintainers know by [opening an issue](https://github.com/microsoft/LightGBM/issues).
 
-```r
-PKG_URL <- "https://github.com/microsoft/LightGBM/releases/download/v3.0.0/lightgbm-3.0.0-r-cran.tar.gz"
+When your package installation is done, you can check quickly if your LightGBM R-package is working by running the following:
 
-remotes::install_url(PKG_URL)
+```r
+library(lightgbm)
+data(agaricus.train, package='lightgbm')
+train <- agaricus.train
+dtrain <- lgb.Dataset(train$data, label = train$label)
+model <- lgb.cv(
+    params = list(
+        objective = "regression"
+        , metric = "l2"
+    )
+    , data = dtrain
+)
 ```
 
-### 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.
+### Installing the CRAN package
 
-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.
+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 a binary for the R package:
+To install this package on any operating system:
 
-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`
+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.
 
-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))
+PKG_URL <- "https://github.com/microsoft/LightGBM/releases/download/v3.0.0/lightgbm-3.0.0-r-cran.tar.gz"
 
-download.file(
-    url = PKG_URL
-    , destfile = local_file
-)
-install.packages(
-    pkgs = local_file
-    , type = "binary"
-    , repos = NULL
-)
+remotes::install_url(PKG_URL)
 ```
 
-### Preparation
+### Installing from Source with CMake <a name="install"></a>
 
 You need to install git and [CMake](https://cmake.org/) first.
 
-Note: 32-bit (i386) R/Rtools is currently not supported.
+Note: this method is only supported on 64-bit systems. If you need to run LightGBM on 32-bit Windows (i386), follow the instructions in ["Installing the CRAN Package"](#installing-the-cran-package).
 
 #### Windows Preparation
 
+NOTE: Windows users may need to run with administrator rights (either R or the command prompt, depending on the way you are installing this package).
+
 Installing a 64-bit version of [Rtools](https://cran.r-project.org/bin/windows/Rtools/) is mandatory.
 
 After installing `Rtools` and `CMake`, be sure the following paths are added to the environment variable `PATH`. These may have been automatically added when installing other software.
@@ -127,9 +125,9 @@ You can perform installation either with **Apple Clang** or **gcc**. In case you
 export CXX=/usr/local/bin/g++-8 CC=/usr/local/bin/gcc-8
 ```
 
-### Install
+#### Install with CMake
 
-Build and install R-package with the following commands:
+After following the "preparation" steps above for your operating system, build and install the R-package with the following commands:
 
 ```sh
 git clone --recursive https://github.com/microsoft/LightGBM
@@ -141,23 +139,55 @@ The `build_r.R` script builds the package in a temporary directory called `light
 
 Note: for the build with Visual Studio/VS Build Tools in Windows, you should use the Windows CMD or Powershell.
 
-Windows users may need to run with administrator rights (either R or the command prompt, depending on the way you are installing this package). Linux users might require the appropriate user write permissions for packages.
+### Installing a GPU-enabled Build
 
 Set `use_gpu` to `TRUE` in `R-package/src/install.libs.R` to enable the build with GPU support. You will need to install Boost and OpenCL first: details for installation can be found in [Installation-Guide](https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-gpu-version).
 
+After installing these other libraries, follow the steps in ["Installing from Source with CMake"](#install).
+
 If you are using a precompiled dll/lib locally, you can move the dll/lib into LightGBM root folder, modify `LightGBM/R-package/src/install.libs.R`'s 2nd line (change `use_precompile <- FALSE` to `use_precompile <- TRUE`), and install R-package as usual.
 
-When your package installation is done, you can check quickly if your LightGBM R-package is working by running the following:
+### Installing Precompiled Binaries
+
+**NOTE:** As of this writing, the precompiled binaries of the R package should be considered experimental. If you try them an experience any problems, please [open an issue](https://github.com/microsoft/LightGBM/issues).
+
+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
-library(lightgbm)
-data(agaricus.train, package='lightgbm')
-train <- agaricus.train
-dtrain <- lgb.Dataset(train$data, label=train$label)
-params <- list(objective="regression", metric="l2")
-model <- lgb.cv(params, dtrain, 10, nfold=5, min_data=1, learning_rate=1, early_stopping_rounds=10)
+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
+)
 ```
 
+### Installing from a Pre-compiled lib_lightgbm <a name="lib_lightgbm"></a>
+
+Previous versions of LightGBM offered the ability to first compile the C++ library (`lib_lightgbm.so` or `lib_lightgbm.dll`) and then build an R package that wraps it.
+
+As of version 3.0.0, this is no longer supported. If building from source is difficult for you, please [open an issue](https://github.com/microsoft/LightGBM/issues).
+
 Examples
 --------