CRAN Version Downloads API Docs

安装

最简单的安装方法是,前往“安装 CRAN 包”

如果遇到任何问题,请尝试“使用 CMake 从源码安装”。这可以在带有 Visual Studio 的 Windows 系统上生成更高效的库版本。

要构建启用 GPU 的包版本,请按照“安装 GPU 版本的构建”中的步骤进行操作。

如果以上任何选项都不适合您或无法满足您的需求,请通过提交议题告知维护者。

当您的包安装完成后,可以通过运行以下代码快速检查 LightGBM 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
)

安装 CRAN 包

lightgbm 可在 CRAN 上获取,并可通过以下 R 代码安装。

install.packages("lightgbm", repos = "https://cran.r-project.org.cn")

这是安装 lightgbm 的最简单方法。它不需要 CMakeVisual Studio,并且应该在许多不同的操作系统和编译器上运行良好。

每个 CRAN 包也在 LightGBM 发布页面上提供,名称类似于 lightgbm-{VERSION}-r-cran.tar.gz

自定义安装 (Linux, Mac)

上述步骤应适用于大多数系统,但使用高度定制环境的用户可能希望更改 R 从源构建包的方式。

要更改安装 CRAN 包时使用的编译器,您可以创建文件 ~/.R/Makevars 来覆盖 CC (C 编译器) 和 CXX (C++ 编译器)。

例如,要在 Mac 上使用 gcc 而不是 clang,您可以使用以下内容

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

使用 CMake 从源码安装

您需要先安装 git 和 CMake

注意:此方法仅支持 64 位系统。如果需要在 32 位 Windows (i386) 上运行 LightGBM,请按照“安装 CRAN 包”中的说明进行操作。

Windows 环境准备

注意:Windows 用户可能需要以管理员权限运行(取决于您安装此包的方式,可以是 R 或命令提示符)。

安装 64 位版本的 Rtools 是必须的。

安装 RtoolsCMake 后,请确保将以下路径添加到环境变量 PATH 中。这些路径可能在安装其他软件时已自动添加。

  • Rtools
    • 如果您使用 Rtools 3.x,例如
      • C:\Rtools\mingw_64\bin
    • 如果您使用 Rtools 4.0,例如
      • C:\rtools40\mingw64\bin
      • C:\rtools40\usr\bin
    • 如果您使用 Rtools 4.2+,例如
      • C:\rtools42\x86_64-w64-mingw32.static.posix\bin
      • C:\rtools42\usr\bin
      • 注意:例如,对于 R 4.3,这是 rtools43\
  • CMake
    • 例如:C:\Program Files\CMake\bin
  • R
    • 例如:C:\Program Files\R\R-3.6.1\bin

注意:从 Rtools 4.0 开始需要两个 Rtools 路径,因为 Rtools 4.0 中更改了路径和包含的软件列表。

注意:Rtools42 及更高版本在编译器工具链方面与以前的版本有很大不同,并且您安装它的方式会改变构建包所需的内容。请参阅“如何:在 Windows 上构建 R 4.2 和包”

Windows 工具链选项

“工具链”指的是用于构建库的软件集合。R 包可以使用三种不同的工具链进行构建。

Windows 用户注意:对于多核系统,建议在 Windows 中使用 Visual Studio,因为它具有更好的多线程效率。对于非常简单的系统(双核计算机或更差),建议使用 MinGW64 以获得最大性能。如果您不知道如何选择,建议使用默认编译器 Visual Studio不要在多核系统上的 Windows 中尝试使用 MinGW。它的结果可能会比 Visual Studio 慢 10 倍。

Visual Studio (默认)

默认情况下,该包将使用 Visual Studio Build Tools 构建。

MinGW (R 3.x)

如果您使用的是 R 3.x 并且使用 Visual Studio 安装失败,LightGBM 将回退到使用 Rtools 捆绑的 MinGW

如果要强制 LightGBM 使用 MinGW(适用于任何 R 版本),请将 --use-mingw 参数传递给安装脚本。

Rscript build_r.R --use-mingw

MSYS2 (R 4.x)

如果您使用的是 R 4.x 并且使用 Visual Studio 安装失败,LightGBM 将回退到使用 MSYS2。这应该适用于 Rtools 4.0 中已经捆绑的工具。

如果要强制 LightGBM 使用 MSYS2(适用于任何 R 版本),请将 --use-msys2 参数传递给安装脚本。

Rscript build_r.R --use-msys2

Mac OS 环境准备

您可以使用 Apple Clanggcc 进行安装。如果您更喜欢 Apple Clang,则应先安装 OpenMP(安装详情可在安装指南中找到)。如果您更喜欢 gcc,则需要安装它(安装详情可在安装指南中找到),并设置一些环境变量来告诉 R 使用 gccg++。如果您通过 Homebrew 安装这些,您的 g++gcc 版本很可能位于 /usr/local/bin 中,如下所示。

# replace 8 with version of gcc installed on your machine
export CXX=/usr/local/bin/g++-8 CC=/usr/local/bin/gcc-8

使用 CMake 安装

在按照上面针对您的操作系统的“准备”步骤操作后,使用以下命令构建和安装 R 包

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
Rscript build_r.R

build_r.R 脚本在名为 lightgbm_r 的临时目录中构建包。每次运行脚本时,它都会销毁并重新创建该目录。该脚本支持以下命令行选项

  • --no-build-vignettes: 跳过构建 vignettes。
  • -j[jobs]: 编译 LightGBM 时使用的线程数。例如,-j4 将尝试同时编译 4 个对象。
    • 默认情况下,此脚本使用单线程编译
    • 为获得最佳结果,请将 -j 设置为物理 CPU 的数量
  • --skip-install: 构建包的 tarball,但不安装它。
  • --use-gpu: 构建库的 GPU 版本。
  • --use-mingw: 强制使用 MinGW 工具链,无论 R 版本如何。
  • --use-msys2: 强制使用 MSYS2 工具链,无论 R 版本如何。

注意:在 Windows 中使用 Visual Studio/VS Build Tools 进行构建时,您应该使用 Windows CMD 或 PowerShell。

安装 GPU 版本的构建

您需要先安装 Boost 和 OpenCL:安装详情可在安装指南中找到。

安装这些其他库后,请按照“使用 CMake 从源码安装”中的步骤进行操作。当您执行到提到 build_r.R 的步骤时,传递 --use-gpu 标志。

Rscript build_r.R --use-gpu

根据您的设置,您可能还需要或想要提供额外的配置。例如,您可能需要提供 Boost 和 OpenCL 的位置。

Rscript build_r.R \
    --use-gpu \
    --opencl-library=/usr/lib/x86_64-linux-gnu/libOpenCL.so \
    --boost-librarydir=/usr/lib/x86_64-linux-gnu

以下选项对应于同名的 CMake FindBoost 选项

  • --boost-root
  • --boost-dir
  • --boost-include-dir
  • --boost-librarydir

以下选项对应于同名的 CMake FindOpenCL 选项

  • --opencl-include-dir
  • --opencl-library

安装预编译二进制文件

CRAN 在每次发布到 CRAN 后几天,会为 Mac 和 Windows 准备预编译二进制文件。可以使用以下 R 代码安装它们。

install.packages(
    "lightgbm"
    , type = "both"
    , repos = "https://cran.r-project.org.cn"
)

这些包不需要编译,因此安装速度更快、更容易,比从源码构建的包要方便。

CRAN 不为 Linux 准备预编译二进制文件,并且截至本文撰写时,本项目也不提供。

从预编译的 lib_lightgbm 安装

LightGBM 的早期版本提供了先编译 C++ 库 (lib_lightgbm.{dll,dylib,so}) 然后构建一个包装它的 R 包的能力。

从版本 3.0.0 开始,这不再受支持。如果您从源构建有困难,请提交议题

测试

R 包的单元测试会在每次提交时通过 GitHub Actions 等集成自动运行。在 R-package/tests/testthat 中添加新测试是提高 R 包可靠性的重要途径。

运行测试

在开发 R 包时,运行以下代码来运行单元测试。

sh build-cran-package.sh \
    --no-build-vignettes

R CMD INSTALL --with-keep.source lightgbm*.tar.gz
cd R-package/tests
Rscript testthat.R

要使用更详细的日志运行测试,请将环境变量 LIGHTGBM_TEST_VERBOSITY 设置为参数 verbosity 的有效值。

export LIGHTGBM_TEST_VERBOSITY=1
cd R-package/tests
Rscript testthat.R

代码覆盖率

添加测试时,您可能希望使用测试覆盖率来识别未测试的区域,并检查您添加的测试是否覆盖了预期代码的所有分支。

以下示例显示了如何在 macOS 或 Linux 设置上为 R 包生成代码覆盖率。要根据您的环境进行调整,请参阅上面描述的自定义步骤

# Install
sh build-cran-package.sh \
    --no-build-vignettes

# Get coverage
Rscript -e " \
    library(covr);
    coverage <- covr::package_coverage('./lightgbm_r', type = 'tests', quiet = FALSE);
    print(coverage);
    covr::report(coverage, file = file.path(getwd(), 'coverage.html'), browse = TRUE);
    "

更新文档

R 包使用 {roxygen2} 生成其文档。生成的 DESCRIPTIONNAMESPACEman/ 文件已检入到源代码控制中。要重新生成这些文件,请运行以下命令。

Rscript \
    --vanilla \
    -e "install.packages('roxygen2', repos = 'https://cran.rstudio.com')"

sh build-cran-package.sh --no-build-vignettes
R CMD INSTALL \
  --with-keep.source \
  ./lightgbm_*.tar.gz

cd R-package
Rscript \
    --vanilla \
    -e "roxygen2::roxygenize(load = 'installed')"

准备 CRAN 包

本节主要供维护者参考,但也可能帮助用户和贡献者理解 R 包的结构。

LightGBM 的大部分使用 CMake 来处理设置编译器和链接器标志、包含头文件位置以及链接到其他库等任务。由于 CRAN 包通常不假定存在 CMake,因此 R 包使用 CRAN 支持的工具链中构建包含 C++ 代码的 R 包的替代方法:Autoconf

有关此方法的更多信息,请参阅“编写 R 扩展”

构建 CRAN 包

从仓库的根目录运行以下命令。

git submodule update --init --recursive
sh build-cran-package.sh

这将创建一个文件 lightgbm_${VERSION}.tar.gz,其中 VERSIONLightGBM 的版本。

该脚本支持以下命令行选项

  • --no-build-vignettes: 跳过构建 vignettes。
  • --r-executable=[可执行文件路径]: 使用替代的 R 构建。

此外,CRAN 包在对任何仓库分支的每次提交时都会生成,并可在相关 Azure Pipelines 运行的“Artifacts”部分找到。

从 CRAN 包进行标准安装

构建包后,使用以下命令进行安装

R CMD install lightgbm_*.tar.gz

修改 CRAN 包

很多细节都由 R CMD buildR CMD install 自动处理,因此可能难以理解 R 包中的文件是如何相互关联的。有关这些细节的全面论述可在“编写 R 扩展”中找到。

本节简要说明了构建 CRAN 包的关键文件。要更新包,请编辑与您的更改相关的文件,然后重新运行构建 CRAN 包中的步骤。

Linux 或 Mac

构建时,将运行 configure 并使用 Makevars.in 作为模板创建文件 Makevars

  1. 编辑 configure.ac

  2. 使用 autoconf 创建 configure。不要手动编辑。此文件必须在 Ubuntu 22.04 上生成。

    如果您有可用的 Ubuntu 22.04 环境,请从 LightGBM 仓库的根目录运行提供的脚本。

    ./R-package/recreate-configure.sh

    如果您无法轻松访问 Ubuntu 22.04 环境,可以通过从本仓库根目录运行以下代码,使用 Docker 生成 configure 脚本。

    docker run \
        --rm \
        -v $(pwd):/opt/LightGBM \
        -w /opt/LightGBM \
        ubuntu:22.04 \
        ./R-package/recreate-configure.sh

    本项目使用的 autoconf 版本存储在 R-package/AUTOCONF_UBUNTU_VERSION 中。要更新该版本,请更新该文件并运行上述命令。要查看可用版本,请参阅 https://packages.ubuntu.com/search?keywords=autoconf

  3. 编辑 src/Makevars.in

或者,GitHub Actions 可以为您重新生成此文件。在拉取请求中(仅限内部拉取请求,不适用于分叉仓库的拉取请求),使用以下短语创建评论

/gha run r-configure

Windows 配置

构建时,将运行 configure.win 并使用 Makevars.win.in 作为模板创建文件 Makevars.win

  1. 直接编辑 configure.win
  2. 编辑 src/Makevars.win.in

测试 CRAN 包

lightgbm 在每次提交时都会自动测试,涵盖了操作系统、R 版本和编译器的多种组合。本节介绍在开发期间如何在本地测试包。

Windows, Mac 和 Linux

sh build-cran-package.sh
R CMD check --as-cran lightgbm_*.tar.gz

ASAN 和 UBSAN

所有上传到 CRAN 的包必须通过使用 gccclang 构建的测试,并使用两个 sanitizers 进行检测:Address Sanitizer (ASAN) 和 Undefined Behavior Sanitizer (UBSAN)。

更多背景信息,请参阅

您可以使用 Docker 在本地复制这些检查。有关用于测试的镜像的更多信息,请参阅 https://github.com/wch/r-debug

在下面的代码中,环境变量 R_CUSTOMIZATION 应设置为以下两个值之一。

  • "san" = 复制 CRAN 的 gcc-ASANgcc-UBSAN 检查
  • "csan" = 复制 CRAN 的 clang-ASANclang-UBSAN 检查
docker run \
  --rm \
  -it \
  -v $(pwd):/opt/LightGBM \
  -w /opt/LightGBM \
  --env R_CUSTOMIZATION=san \
  wch1/r-debug:latest \
  /bin/bash

# install dependencies
RDscript${R_CUSTOMIZATION} \
  -e "install.packages(c('R6', 'data.table', 'jsonlite', 'knitr', 'markdown', 'Matrix', 'RhpcBLASctl', 'testthat'), repos = 'https://cran.r-project.org.cn', Ncpus = parallel::detectCores())"

# install lightgbm
sh build-cran-package.sh --r-executable=RD${R_CUSTOMIZATION}
RD${R_CUSTOMIZATION} \
  CMD INSTALL lightgbm_*.tar.gz

# run tests
cd R-package/tests
rm -f ./tests.log
RDscript${R_CUSTOMIZATION} testthat.R >> tests.log 2>&1

# check that tests passed
echo "test exit code: $?"
tail -300 ./tests.log

Valgrind

所有上传到 CRAN 的包必须在构建和测试时,不产生任何 valgrind 报告的问题。valgrind 是一个性能分析工具,可以捕获内存泄漏和非法写入等严重问题。更多信息请参阅这篇博客文章

您可以使用 Docker 在本地复制这些检查。请注意,为使用 valgrind 而构建的经过检测的 R 版本运行速度慢很多,这些测试可能需要长达 20 分钟才能运行完成。

docker run \
    --rm \
    -v $(pwd):/opt/LightGBM \
    -w /opt/LightGBM \
    -it \
        wch1/r-debug

RDscriptvalgrind -e "install.packages(c('R6', 'data.table', 'jsonlite', 'knitr', 'markdown', 'Matrix', 'RhpcBLASctl', 'testthat'), repos = 'https://cran.rstudio.com', Ncpus = parallel::detectCores())"

sh build-cran-package.sh \
    --r-executable=RDvalgrind

RDvalgrind CMD INSTALL \
    --preclean \
    --install-tests \
        lightgbm_*.tar.gz

cd R-package/tests

RDvalgrind \
    --no-readline \
    --vanilla \
    -d "valgrind --tool=memcheck --leak-check=full --track-origins=yes" \
        -f testthat.R \
2>&1 \
| tee out.log \
| cat

这些测试也可以通过在拉取请求中留下评论来触发

/gha run r-valgrind

已知问题

有关 R 包的已知问题信息,请参阅 LightGBM 主要 FAQ 页面的 R 包部分