Skip to content

Commit

Permalink
[R-package] Remove ability to install precompiled lib_lightgbm (fixes #…
Browse files Browse the repository at this point in the history 
…3320) (#3360)

* [R-package] [docs] Reorganize installation instructions (fixes #3320)

* more changes

* remove ability to use precompiled lib_lightgbm

* remove language about installing from the CRAN section

* move installation stuff

* Apply suggestions from code review

Co-authored-by: Nikita Titov <[email protected]>

* fix anchor

Co-authored-by: Nikita Titov <[email protected]>
  • Loading branch information
@jameslamb @StrikerRUS
jameslamb and StrikerRUS authored Oct 10, 2020
1 parent 3f71d75 commit 785eb60
Show file tree
Hide file tree
Showing 2 changed files with 196 additions and 197 deletions.
144 changes: 88 additions & 56 deletions R-package/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,51 @@
### Contents

* [Installation](#installation)
- [Installing the CRAN Package](#installing-the-cran-package)
- [Installing from Source with CMake](#install)
- [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)
* [Preparing a CRAN Package](#preparing-a-cran-package)
* [External Repositories](#external-unofficial-repositories)
* [Known Issues](#known-issues)

Installation
------------

For the easiest installation, go to ["Installing the CRAN package"](#installing-the-cran-package).

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 with Visual Studio.

To build a GPU-enabled version of the package, follow the steps in ["Installing a GPU-enabled Build"](#installing-a-gpu-enabled-build).

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).

When your package installation is done, you can check quickly if your LightGBM R-package is working by running the following:

```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 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.
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)
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.

Expand All @@ -30,47 +59,31 @@ PKG_URL <- "https://github.com/microsoft/LightGBM/releases/download/v3.0.0/light
remotes::install_url(PKG_URL)
```

### 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.
#### Custom Installation (Linux, Mac)

This sample code installs version 3.0.0-1 of the R package on Mac.
The steps above should work on most systems, but users with highly-customized environments might want to change how R builds packages from source.

```r
PKG_URL <- "https://github.com/microsoft/LightGBM/releases/download/v3.0.0rc1/lightgbm-3.0.0-1-r40-macos.tgz"
To change the compiler used when installing the CRAN package, you can create a file `~/.R/Makevars` which overrides `CC` (`C` compiler) and `CXX` (`C++` compiler).

local_file <- paste0("lightgbm.", tools::file_ext(PKG_URL))
For example, to use `gcc` instead of `clang` on Mac, you could use something like the following:

download.file(
url = PKG_URL
, destfile = local_file
)
install.packages(
pkgs = local_file
, type = "binary"
, repos = NULL
)
```make
# ~/.R/Makevars
CC=gcc-8
CXX=g++-8
CXX11=g++-8
```

### 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.
Expand Down Expand Up @@ -127,9 +140,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
Expand All @@ -141,23 +154,53 @@ 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).

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.
After installing these other libraries, follow the steps in ["Installing from Source with CMake"](#install).

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
--------

Expand Down Expand Up @@ -194,8 +237,8 @@ Rscript -e " \
"
```

Preparing a CRAN Package and Installing It
------------------------------------------
Preparing a CRAN Package
------------------------

This section is primarily for maintainers, but may help users and contributors to understand the structure of the R package.

Expand All @@ -221,17 +264,6 @@ After building the package, install it with a command like the following:
R CMD install lightgbm_*.tar.gz
```

#### Custom Installation (Linux, Mac)

To change the compiler used when installing the package, you can create a file `~/.R/Makevars` which overrides `CC` (`C` compiler) and `CXX` (`C++` compiler). For example, to use `gcc` instead of `clang` on Mac, you could use something like the following:

```make
# ~/.R/Makevars
CC=gcc-8
CXX=g++-8
CXX11=g++-8
```

### Changing the CRAN Package

A lot of details are handled automatically by `R CMD build` and `R CMD install`, so it can be difficult to understand how the files in the R package are related to each other. An extensive treatment of those details is available in ["Writing R Extensions"](https://cran.r-project.org/doc/manuals/r-release/R-exts.html).
Expand Down
Loading

0 comments on commit 785eb60

Please sign in to comment.