ispc-rs

一个小型库，旨在用作Cargo的构建依赖项，以便轻松将ISPC代码集成到Rust项目中。ispc-rs分为两个crate：编译时crate ispc_compile 和运行时crate ispc_rt。这种分割允许库作者避免将不必要的依赖项推送到不打算修改ISPC代码的库的最终用户。如果不需要这种分离，还提供了ispc-rs crate，它将编译时和运行时crate打包成一个方便的单个crate。

文档

Rust文档可在此处找到，ISPC文档可在此处找到。

使用ispc-rs

使用ispc-rs，您可以从构建脚本编译ISPC代码以生成包含绑定到导出ISPC函数的原生库和Rust模块。ispc-rs将输出命令到Cargo以链接原生库，您可以使用提供的宏将Rust绑定导入到您的代码中并调用库。使用ispc-rs的此模式要求在编译您的crate时ISPC编译器和clang可用。

当编写一个希望打包并使用ISPC代码的crate或程序，但不一定需要在最终用户系统的依赖项中时，ispc-rs实际上被分成了两个crate：一个编译时crate（ispc_compile）和一个运行时crate（ispc_rt）。ispc_compile crate用于在构建脚本中编译ISPC代码，生成原生库和Rust绑定。ispc_rt crate包含轻量级代码，可在构建脚本中使用，它将查找并链接到之前编译的原生库，并包含一个宏来导入之前生成的Rust绑定。推荐的使用场景是将ispc_compile作为可选依赖项，并通过功能门控来实现。当使用此功能门控构建时，将构建ISPC代码；否则，运行时crate将查找并使用现有库。

报告ispc-rs的问题

请在GitHub问题跟踪器中报告任何问题或功能请求。

编译ISPC代码的要求

必须将ISPC编译器和libclang（用于rust-bindgen）添加到您的路径中，才能编译ISPC代码并生成绑定。如果使用ispc_rt来链接到之前编译的库，则不需要这些。

Windows用户

您需要Visual Studio，并必须使用Rust的MSVC ABI版本，因为ISPC和Clang在Windows上与MSVC链接。为了使bindgen找到libclang，您需要将libclang.lib复制到clang.lib并将它放在您的路径中。您还需要设置环境变量LIBCLANG_PATH=<path to LLVM\bin>，这样bindgen才能成功找到clang。

将ispc-rs作为一个单独的crate使用

要将ispc-rs作为一个单独的crate使用，您需要在crate中添加一个构建脚本（build.rs），告诉Cargo关于它，并将ispc-rs作为构建时和编译时依赖项添加。

# Cargo.toml
[package]
# ...
build = "build.rs"

[dependencies]
ispc = "2.0"

[build-dependencies]
ispc = "2.0"

现在您可以使用ispc将您的代码编译成静态库。

extern crate ispc;

fn main() {
    // Compile our ISPC library, this call will exit with EXIT_FAILURE if
    // compilation fails.
    ispc::compile_library("simple", &["src/simple.ispc"]);
}

运行cargo build现在应将您的ISPC文件编译成库并将您的Rust应用程序与它链接起来。为了方便起见，提供了ispc_module宏，用于将使用rust-bindgen生成的绑定导入到同名模块中。请注意，所有导入的函数都将是不安全的，因为它们是您的lib的原始C绑定。

#[macro_use]
extern crate ispc;

// Functions exported from simple will be callable under simple::*
ispc_module!(simple);

使用独立的编译和运行时crate

使用独立crate的过程与单个crate类似；但是，您将使用单个ispc_compile和ispc_rt crate，其中前者标记为可选依赖项。这将允许最终用户使用crate并利用其ISPC代码，而无需在他们的机器上重新构建代码。因此，还建议为多个矢量ISA编译您的ISPC代码，以允许跨CPU架构的可移植性。您还需要为每个宿主目标三元组打包编译的ISPC库。这可以通过在每个您希望支持您的库用户的目标宿主系统上启用ispc功能来构建您的crate来实现。请注意，您的crate在系统上没有提供二进制文件的用户仍然可以通过使用具有ispc功能的crate来自行编译ISPC代码。

# Cargo.toml
[package]
# ...
build = "build.rs"

[dependencies]
ispc_rt = "2.0"

[build-dependencies]
ispc_rt = "2.0"
ispc_compile = { "2.0", optional = true }

[features]
ispc = ["ispc_compile"]

在构建脚本中，我们现在可以使用 ispc 功能，可选地使用 ispc_compile 编译 ispc 代码，否则我们将使用 ispc_rt 链接之前构建的代码。在这里，我们还将编译好的 ISPC 库和绑定输出到 src 目录。

extern crate ispc_rt;
#[cfg(feature = "ispc")]
extern crate ispc_compile;

#[cfg(feature = "ispc")]
fn link_ispc() {
    use ispc_compile::TargetISA;
    ispc_compile::Config::new()
        .file("src/simple.ispc")
        .target_isas(vec![
            TargetISA::SSE2i32x4,
            TargetISA::SSE4i32x4,
            TargetISA::AVX1i32x8,
            TargetISA::AVX2i32x8,
            TargetISA::AVX512KNLi32x16,
            TargetISA::AVX512SKXi32x16])
        .out_dir("src/")
        .compile("simple");
}

#[cfg(not(feature = "ispc"))]
fn link_ispc() {
    ispc_rt::PackagedModule::new("simple")
        .lib_path("src/")
        .link();
}

fn main() {
    link_ispc();
}

运行 cargo build --features ispc 现在将构建您的 ISPC 文件到库中，并为您的导出 ISPC 函数生成绑定。编译好的库和生成的绑定文件将被保存在 src/ 目录下，以便与 crate 中的其他部分一起打包。当使用 cargo build 构建时，将链接之前为主机系统编译的库。

无论是否使用 ispc 功能构建，您都可以像之前一样使用 ispc_module! 宏将生成的绑定导入到您的 Rust 代码中。

#[macro_use]
extern crate ispc;

// Functions exported from simple will be callable under simple::*
ispc_module!(simple);

更多完整的示例可以在 examples/ 文件夹中找到。独立的 crate 示例在这里 here