本站先前有介绍过在 Rust 编程语言中使用 C/C++ 的函数库的方式,而在这篇文章中会来谈谈反过来的作法,也就是在 C/C++ 编程语言中使用 Rust 的函数库。

底下先举一个最简单的例子,来说明如何使用 C/C++ 编程语言调用 Rust 的函数库。

C + Rust 语言的 Hello World

首先,使用以下指令创建出名为 hello-world-lib 的 Cargo 函数库项目:

cargo new --lib hello-world-lib

在 src 目录下的 lib.rs 中,撰写以下程序:

pub fn print_hello_world() {
    println!("Hello world!");
}

就这样,我们的 Rust 函数库就设计完成了!接下来就是决定要让哪些函数开放出来,使外部有引用到此 Rust 函数库的 C/C++ 程序可以调用。当然,在这个例子中,我们只有撰写一个 print_hello_world 函数,所以当然要将它公开出去。

虽然我们已经有对 print_hello_world 函数使用 pub 关键字,但 pub 关键字只是定义这个函数能够被外部的 Rust crate 来调用。所以我们必须在 pub 关键字后面再加上 extern 关键字,来让这个函数可以透过函数库来被调用。

程序修改如下:

#[no_mangle]
pub extern fn print_hello_world() {
    println!("Hello world!");
}

替使用 extern 关键字来定义的函数加上 #[no_mangle] 属性是为了要保留函数名称,确保它可以被 C/C++ 程序调用到。

由于 Rust 的函数库预设的格式为 .rlib,并非 C/C++ 使用的 .a、.so、.dll、.dylib 等。为了要编译出 C/C++ 语言能用的函数库,必须要去修改 Cargo 的设置档,在 [lib] 区块中,加上 crate-type 项目,将其的值设置为 ["cdylib"]。如下:

[lib]
crate-type = ["cdylib"]

如果不设置 crate-type,Cargo 会根据 src 目录中有无 lib.rs 文件来决定要不要加入 rlib,也就是 crate-type = ["rlib"]。

在 crate-type 项目加入 cdylib,可以使 Cargo 在编译程序项目时,将能用在 C/C++ 程序的动态函数库也跟着编译出来。

将设置档修改好后,运行 cargo build --release 指令,就可以在 target/release 目录中找到动态函数库文件啦!目标平台如果是 Linux 的话,就会看到 libhello_world_lib.so 文件。

如果想要编译出静态函数库,只要在 crate-type 项目加入 staticlib,就可以使 Cargo 在编译程序项目时,将静态函数库也跟着编译出来。如下:

[lib]
crate-type = ["cdylib", "staticlib"]

目标平台如果是 Linux 的话,在运行 cargo build --release 指令后,在 target/release 目录中就会看到 libhello_world_lib.a 文件。

撰写标头档

我们可以在 src 目录下加上一个 C/C++ 的 hello_world_lib.h 标头档,来对应函数库中可被使用的函数。

写法如下:

void print_hello_world();

撰写 C/C++ 程序

接着撰写 C/C++ 代码,文件名为 hello_world.c,存放在 Cargo 程序项目的根目录中。

#include "src/hello_world_lib.h"

int main() {
    print_hello_world();

    return 0;
}

编译与运行 C/C++ 程序

动态链接

在 Cargo 程序项目的根目录中,运行以下指令:

gcc hello_world.c -L target/release -lhello_world_lib -o hello_world

以上指令会使用 gcc 来编译 hello_world.c,并且会去链接 target/release 中的 hello_world_lib 函数库,如果动态函数库和静态函数库同时存在(.a 和 .so 文件同时存在),就会使用动态函数库。编译完成后,可执行文件会被输出为 hello_world 文件。

在运行使用动态链接的 C/C++ 可执行文件时,动态函数库必须要被登录到系统环境中。在 Linux 环境下可以直接使用 LD_LIBRARY_PATH 来设置要寻找动态函数库文件的目录,如下图:

以 LD_LIBRARY_PATH 运行动态链接的程序

而 Windows 环境下可以直接将 .dll 和可执行文件放置在同一个目录下。

静态链接

在 Cargo 程序项目的根目录中,运行以下指令:

gcc hello_world.c target/release/libhello_world_lib.a -o hello_world -ldl -pthread

以上指令会使用 gcc 来编译 hello_world.c,并且会去链接静态函数库 target/release/libhello_world_lib.a。编译完成后,可执行文件会被输出为 hello_world 文件。静态链接另外还要加上 -ldl 和 -pthread 这两个参数,因为这些是 Rust 应用程序基本会使用到的动态函数库。

以静态链接编译并运行 hello_world

Rust 类型和 C/C++ 类型的转换

如果我们需要在 Rust 程序和 C/C++ 程序间共享内存中的变量数据,就必须要透过 FFI(Foreign Function Interface,外部函数界面)来完成。

稍微改写一下刚才写的 Hello World 程序来举例吧!

use std::ffi::CStr;

#[no_mangle]
pub extern fn greet(s: *const std::os::raw::c_char, a: i32, b: i32) {
    let c_str: &CStr = unsafe { 
        CStr::from_ptr(s)
    };

    println!("Hello {}! {} + {} = {}", c_str.to_str().unwrap(), a, b, a + b);
}
#include <stdint.h>

void greet(char* s, int32_t a, int32_t b);
#include <stdio.h>

#include "src/hello_world_lib.h"

int main() {
    char* name = "Rust";
    int32_t a = 7, b = 11;

    greet(name, a, b);

    return 0;
}

重新编译并运行 C/C++ 程序,程序会输出:

Hello Rust! 7 + 11 = 18