libR-sys

R 库的底层绑定

安装

构建此库的推荐方法是使用预编译的绑定，这些绑定适用于 Linux、macOS 和 Windows。

另一种方法是从源代码构建库，在这种情况下，它会调用 bindgen crate，该 crate 有额外的平台特定依赖项（包括 msys2 用于 Windows）。

配置

libR-sys 识别以下环境变量

• LIBRSYS_R_VERSION 如果设置，则用于确定应为其生成绑定的 R 版本。 LIBRSYS_R_VERSION 应设置为支持的值之一，例如 4.2.0 或 4.3.0-devel（模式为 major.minor.patch[-devel]）。格式不正确的 LIBRSYS_R_VERSION 会导致编译错误。如果未设置 LIBRSYS_R_VERSION，则调用 R 并使用其 R.version。

使用预编译绑定（推荐）

构建库需要两个组件

1. R：它需要安装并在搜索路径中可用。
2. Rust：建议使用 rustup 安装 Rust；搜索路径应包括 Rust 可执行文件。

注意：在 Windows 上，仅支持 R >= 4.2

一旦 R 和 Rust 配置完成，库可以轻松构建

# macOS & Linux
cargo build

# Windows
cargo build --target x86_64-pc-windows-gnu

要测试构建，请运行 cargo test。

# macOS & Linux
cargo test

# Windows
cargo test --target x86_64-pc-windows-gnu

从源代码构建绑定（高级）

注意：在 Windows 上，仅支持 R >= 4.2

可以使用 bindgen，特殊的 Rust 包来生成绑定。通过 use-bindgen 功能标志启用 bindgen 的使用。

bindgen 需要 libclang，应首先安装。此库依赖于 LIBCLANG_PATH 环境变量来确定 libclang 的正确版本路径。

可以使用 LIBRSYS_BINDINGS_OUTPUT_PATH 环境变量配置绑定输出文件夹，因此请确保将其设置为例如 bindings。

• Linux

  将 LIBCLANG_PATH 设置为您的 llvm 安装的 lib 目录，例如，LIBCLANG_PATH=/usr/lib/llvm-3.9/lib。使用以下命令进行构建和测试

  cargo build --features use-bindgen
  cargo test  --features use-bindgen 
  

• macOS

  使用 homebrew 安装 llvm-config

  brew install llvm
  

  通过以下方式将其添加到您的搜索路径

  echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> ~/.bash_profile
  

  如果您想从 RStudio 内部编译 libR-sys，您还可能需要将以下行添加到您的 .Renviron 文件中

  PATH=/usr/local/opt/llvm/bin:$PATH
  

  使用以下命令进行构建和测试

  cargo build --features use-bindgen
  cargo test  --features use-bindgen 
  

• Windows 在 Windows 上，可以使用本机 LLVM 安装和 Rtools 发行版生成绑定

  安装 LLVM

  choco install llvm -y
  

  LLVM 还可以使用 winget、scoop 或手动安装。

  为了确保成功安装和配置了 LLVM，请运行 clang --version。如果 clang 不在 PATH 上，请手动将 clang 安装路径添加到 PATH 环境变量中。

  如果缺少 Rtools，请安装

  choco install rtools -y
  

  以这种方式安装 Rtools 会自动设置 RTOOLS42_HOME（或 RTOOLS43_HOME）环境变量。

  确保 R_HOME 环境变量设置为 R 安装目录。

  最后，将 libR-sys 指向 Rtools 的 include 目录

  $env:LIBRSYS_LIBCLANG_INCLUDE_PATH="$env:RTOOLS42_HOME\x86_64-w64-mingw32.static.posix\include"
  

  现在，可以使用以下命令构建绑定

  cargo build --target x86_64-pc-windows-gnu --features use-bindgen
  

在 Windows 上运行 bindgen 测试

在 Windows 上运行 bindgen 测试需要更多的设置。

首先，将 Rtools bin 目录添加到 PATH（如果您使用的是 Rtools 4.3，请将 RTOOLS42_HOME 替换为 RTOOLS43_HOME）

$env:PATH += ";$env:RTOOLS42_HOME\x86_64-w64-mingw32.static.posix\bin"

其次，由于存在 gcc 静态链接问题，请将 Rtools 版本 4.2 及更高版本打上补丁。因为 rustc 会向编译器添加 -lgcc_eh 标志，但 Rtools 的 GCC 由于编译设置而没有 libgcc_eh。因此，为了满足编译器的要求，应该模拟并添加 libgcc_eh 到库搜索路径中。有关更多详细信息，请参阅 r-windows/rtools-packages。

为缺失的库文件创建一个目录并在其中创建一个空文件

# create a directory in an arbitrary location (e.g. libgcc_mock)
New-Item -Path libgcc_mock -Type Directory

# create empty libgcc_eh.a and libgcc_s.a
New-Item -Path libgcc_mock\libgcc_eh.a -Type File

最后，配置 Rust 编译器并选择合适的链接器（见 The Cargo Book）

$env:CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER="x86_64-w64-mingw32.static.posix-gcc.exe"
$env:LIBRARY_PATH="libgcc_mock" # Replace it with the path to the directory created above

或者，可以在 .cargo/config.toml 中配置链接器

[target.x86_64-pc-windows-gnu]
linker = "x86_64-w64-mingw32.static.posix-gcc.exe"

现在，可以运行测试了

cargo test --target x86_64-pc-windows-gnu --features use-bindgen

编辑器设置

{
    // The target needs to be GNU
    "rust-analyzer.cargo.target": "x86_64-pc-windows-gnu",
    // Specify "use-bindgen" for developing R-devel.
    "rust-analyzer.cargo.features": [],
    "terminal.integrated.env.windows": {
        "R_HOME": "C:/Program Files/R/R-4.2.2",
        "PATH": "${env:R_HOME}/bin/x64;C:/rtools42/x86_64-w64-mingw32.static.posix/bin;C:/rtools42/usr/bin;${env:PATH}"
    }
}