最简单的安装方法是,前往“安装 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
)
lightgbm 可在 CRAN 上获取,并可通过以下 R 代码安装。
install.packages("lightgbm", repos = "https://cran.r-project.org.cn")
这是安装 lightgbm 的最简单方法。它不需要 CMake
或 Visual Studio
,并且应该在许多不同的操作系统和编译器上运行良好。
每个 CRAN 包也在 LightGBM 发布页面上提供,名称类似于 lightgbm-{VERSION}-r-cran.tar.gz
。
您需要先安装 git 和 CMake。
注意:此方法仅支持 64 位系统。如果需要在 32 位 Windows (i386) 上运行 LightGBM,请按照“安装 CRAN 包”中的说明进行操作。
注意:Windows 用户可能需要以管理员权限运行(取决于您安装此包的方式,可以是 R 或命令提示符)。
安装 64 位版本的 Rtools 是必须的。
安装 Rtools
和 CMake
后,请确保将以下路径添加到环境变量 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
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 和包”。
“工具链”指的是用于构建库的软件集合。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
您可以使用 Apple Clang 或 gcc 进行安装。如果您更喜欢 Apple Clang,则应先安装 OpenMP(安装详情可在安装指南中找到)。如果您更喜欢 gcc,则需要安装它(安装详情可在安装指南中找到),并设置一些环境变量来告诉 R 使用 gcc
和 g++
。如果您通过 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
在按照上面针对您的操作系统的“准备”步骤操作后,使用以下命令构建和安装 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。
您需要先安装 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 准备预编译二进制文件,并且截至本文撰写时,本项目也不提供。
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}
生成其文档。生成的 DESCRIPTION
、NAMESPACE
和 man/
文件已检入到源代码控制中。要重新生成这些文件,请运行以下命令。
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')"
本节主要供维护者参考,但也可能帮助用户和贡献者理解 R 包的结构。
LightGBM
的大部分使用 CMake
来处理设置编译器和链接器标志、包含头文件位置以及链接到其他库等任务。由于 CRAN 包通常不假定存在 CMake
,因此 R 包使用 CRAN 支持的工具链中构建包含 C++ 代码的 R 包的替代方法:Autoconf
。
有关此方法的更多信息,请参阅“编写 R 扩展”。
从仓库的根目录运行以下命令。
git submodule update --init --recursive
sh build-cran-package.sh
这将创建一个文件 lightgbm_${VERSION}.tar.gz
,其中 VERSION
是 LightGBM
的版本。
该脚本支持以下命令行选项
--no-build-vignettes
: 跳过构建 vignettes。--r-executable=[可执行文件路径]
: 使用替代的 R 构建。此外,CRAN 包在对任何仓库分支的每次提交时都会生成,并可在相关 Azure Pipelines 运行的“Artifacts”部分找到。
很多细节都由 R CMD build
和 R CMD install
自动处理,因此可能难以理解 R 包中的文件是如何相互关联的。有关这些细节的全面论述可在“编写 R 扩展”中找到。
本节简要说明了构建 CRAN 包的关键文件。要更新包,请编辑与您的更改相关的文件,然后重新运行构建 CRAN 包中的步骤。
Linux 或 Mac
构建时,将运行 configure
并使用 Makevars.in
作为模板创建文件 Makevars
。
编辑 configure.ac
。
使用 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。
编辑 src/Makevars.in
。
或者,GitHub Actions 可以为您重新生成此文件。在拉取请求中(仅限内部拉取请求,不适用于分叉仓库的拉取请求),使用以下短语创建评论
/gha run r-configure
Windows 配置
构建时,将运行 configure.win
并使用 Makevars.win.in
作为模板创建文件 Makevars.win
。
configure.win
。src/Makevars.win.in
。lightgbm 在每次提交时都会自动测试,涵盖了操作系统、R 版本和编译器的多种组合。本节介绍在开发期间如何在本地测试包。
所有上传到 CRAN 的包必须通过使用 gcc
和 clang
构建的测试,并使用两个 sanitizers 进行检测:Address Sanitizer (ASAN) 和 Undefined Behavior Sanitizer (UBSAN)。
更多背景信息,请参阅
您可以使用 Docker 在本地复制这些检查。有关用于测试的镜像的更多信息,请参阅 https://github.com/wch/r-debug。
在下面的代码中,环境变量 R_CUSTOMIZATION
应设置为以下两个值之一。
"san"
= 复制 CRAN 的 gcc-ASAN
和 gcc-UBSAN
检查"csan"
= 复制 CRAN 的 clang-ASAN
和 clang-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
所有上传到 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 包部分。