作为新颖、先进的编程语言,Rust 的函数库还没有 C/C++ 语言的函数库来得多且完整。在很多时候,我们还是无可避免地必须要去使用现有 C/C++ 编程语言所实作的函数库来完成我们需要的功能。虽然一般来说,我们还是会比较喜欢用纯 Rust 代码来开发程序,确保程序的安全性以及可移植性,但毕竟要把过去每个 C/C++ 编程语言所实作的函数库,都使用 Rust 编程语言来改写,是非常不切实际的事。在开发成本的考量之下,直接让 Rust 程序与 C/C++ 编程语言作链接,就变成是一种很常见的折衷作法。

建置脚本(build.rs)

类似于 C/C++ 编程语言程序项目常使用的「configure」,Rust 的 Cargo 程序项目也提供了「建置脚本」的功能,可以让程序项目在编译之前,先编译与运行某个 Rust 源代码文件来设置程序项目的编译环境。这个「建置脚本」预设会是程序项目根目录底下的 build.rs,如果想要更改路径的话,可以在 Cargo.toml 设置文件中的 [package] 区块,添加 build 设置项目。例如:

[package]
name = "example"
version = "0.1.0"
edition = "2021"
build = "src/build.rs"

[dependencies]

以上设置档将作为建置脚本的 Rust 源代码文件路径设置在程序项目根目录中的 src 目录下,文件名为 build.rs。

建置脚本的撰写方式可以参考 Cargo 的官方手册,网址如下:

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

Rust + C 语言的 Hello World

首先,使用以下指令创建出名叫 c-hello-world 的 Cargo 应用程序项目:

cargo new --bin c-hello-world

在程序项目的根目录中,添加一个 hello-world 目录,并在该目录中添加一个 hello.c 档,文件内容如下:

#include <stdio.h>

void greet() {
    printf("Hello world!\n");
}

在 hello.c 中,我们引入了 stdio.h 标头档,并在 greet 函数中使用 printf 函数来印出 Hello world! 字符串。

接着,编辑程序项目根目录中 src 目录内的 main.rs 档,文件内容如下:

#[link(name = "hello-world")]
extern "C" {
    fn greet();
}

fn main() {
    unsafe {
        greet();
    }
}

在 extern "C" 关键字所组成的程序区块中,以 Rust 编程语言定义函数的语法来对应 C/C++ 语言程序的函数,在程序区块上方使用 #[link(name = "hello-world")] 属性,其中的 hello-world 表示要让这个程序区块定义的函数链接到 libhello-world 这个函数库。当然,我们现在还没有 libhello-world 这个东西,所以此时的程序项目是无法成功建置的(但是可以通过编译检查)。

在 Rust 程序中调用外部函数库的函数,必须要在不安全的模式下进行,因此 main 函数调用 greet 函数时,还另外使用了 unsafe 关键字。

再来,在程序项目的根目录中,添加一个 build.rs 文件,这个文件就是我们的建置脚本啦!文件内容如下:

use std::{env, process::Command};

fn main() {
    let out_dir = env::var("OUT_DIR").unwrap();

    Command::new("cc")
        .args(["hello-world/hello.c", "-O3", "-c", "-fPIC", "-o"])
        .arg(&format!("{out_dir}/hello-world.o"))
        .status()
        .unwrap();

    Command::new("ar")
        .args(["crus", "libhello-world.a", "hello-world.o"])
        .current_dir(out_dir.as_str())
        .status()
        .unwrap();

    println!("cargo:rustc-link-search=native={out_dir}");
    println!("cargo:rustc-link-lib=static=hello-world");
}

以上程序,第 4 行会去取得 OUT_DIR 环境变量的值,这个环境变量是 Cargo 程序项目自带的,而它的值是建构项目时输出文件的保存路径。第 6 行到第 10 行,其实就如同在程序项目根目录下,运行了以下指令:

cc hello-world/hello.c -O3 -c -fPIC -o "$OUT_DIR/hello-world.o"

参数 -O3 表示要进行优化。参数 -c 表示让 C/C++ 编译器不要进行「link」的动作,因为我们要让它作为函数库来使用。参数 -fPIC 是要打开「Position-Independent Code」功能,也是为了要让程序能够作为函数库来使用。参数 -o 则是设置目的档(object file)要输出的位置。

程序第 12 行到第 16 行,其实就如同在 OUT_DIR 目录下,运行了以下指令:

ar crus libhello-world.a hello-world.o

ar crus 指令可以将多个目的档封装成单一个 .a 静态函数库文件。在此会把 hello-world.o 封装成 libhello-world.a。

程序第 18 行,设置程序项目在编译时会去 OUT_DIR 目录寻找原生函数库,有点类似 C/C++ 编译器的 -L 参数。

程序第 19 行,设置程序项目以静态的方式来引用 hello-world 这个函数库(会去寻找 libhello-world.a 文件),有点类似在 C/C++ 编译器加上 -lhello-world 参数。引用了 hello-world 函数库之后,在 Rust 程序中就可以使用 #[link(name = "hello-world")] 属性和 extern 关键字来对应 C/C++ 的函数。

此时使用 cargo run 来运行程序项目的话,Cargo 在编译程序项目前,会先去编译并运行项目根目录下的 build.rs,所以 C 语言的 libhello-world.a 静态函数库文件会先被产生出来,然后在编译程序项目时会引用这个 libhello-world.a 静态函数库文件,将 greet 函数的功能带进 Rust 程序中。程序运行的时候就可以看到屏幕印出 Hello world! 字符串啦!

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

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

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

#include <stdint.h>
#include <stdio.h>

void greet(char* s, int32_t a, int32_t b) {
    printf("Hello %s! %d + %d = %d\n", s, a, b, a + b);
}
use std::ffi::CString;

#[link(name = "hello-world")]
extern {
    fn greet(s: *const std::os::raw::c_char, a: i32, b: i32);
}

fn main() {
    let prompt = CString::new("Rust").unwrap();

    unsafe {
        greet(prompt.as_ptr(), 7, 11);
    }
}

使用 cargo run 来运行程序项目,程序会输出:

Hello Rust! 7 + 11 = 18

Rust 的联合体(union)

Rust 编程语言其实是有提供联合体的,只是在纯 Rust 程序中并不会去用到这个。但是在 C/C++ 上还蛮常看到联合体的。Rust 的联合体可以用 union 关键字来定义,例如:

union MyUnion {
    f1: u32,
    f2: f32,
}

这个 MyUnion 联合的大小为 32 比特,它可以保存一个 32 比特的无号整数或是一个 32 比特的浮点数。

Rust 的联合体也可以实作函数、方法和特性。此外,联合体的字段类型,一定要有实作 Copy 特性。

我们可以用以下方式来创建出 MyUnion 联合的实体:

let u1 = MyUnion {
    f1: 1
};

let u2 = MyUnion {
    f2: 2.5
};

修改 MyUnion 联合实体的值的方式如下:

let mut u = MyUnion {
    f1: 1
};

u.f2 = 2.5;

取得 MyUnion 联合实体的值时必须要使用 unsafe 关键字来进入不安全模式。如下:

let u = MyUnion {
    f1: 1
};

println!("{}", unsafe { u.f1 });

联合也可以拿来做型样匹配,当然,这也是要在不安全模式下进行。如下:

let u = MyUnion {
    f1: 10
};

unsafe {
    match u {
        MyUnion {
            f1: 10,
        } => {
            println!("ten");
        },
        MyUnion {
            f2,
        } => {
            println!("{f2}");
        },
    }
}

在做联合的型样匹配时,要注意到样本中的字段名称,只是给编译器对应类型用的,在程序运行阶段,并无法得知当前的联合到底是用哪个字段的类型,因此如果第一个 match 关键字里的 arm 没有做任何的条件限定的话,就会永远被匹配成功。