构建工具

本节介绍在编译 crate 源代码之前运行的“构建时”工具或代码。按照惯例，构建时代码存放在 build.rs 文件，通常称为“构建脚本”。常见的用例包括：Rust 代码生成、绑定的 C/C++/asm 代码的编译。要获取更多信息，请阅读 Cargo（中文文档）的构建脚本文档。

编译并静态链接到绑定的 C 语言库

为了适应项目中需要混合 C、C++，或 asm 等语言的场景，cc crate 提供了一个简单的 API，用于将绑定的 C/C++/asm 代码编译成静态库（.a），静态库可以通过 rustc 静态链接。

下面的实例有一些绑定的 C 语言代码（src/hello.c），将从 rust 中调用它们。在编译 rust 源代码之前，Cargo.toml 中指定的“构建”文件（build.rs）预先运行。使用 cc crate，将生成一个静态库文件（本实例中为 libhello.a，请参阅 compile 文档），通过在 extern 代码块中声明外部函数签名，然后就可以从 rust 中调用该静态库。

本实例中绑定的 C 语言文件非常简单，只需要将一个源文件传递给 cc::Build。对于更复杂的构建需求，cc::Build 提供了一整套构建器方法，用于指定（包含）include路径和扩展编译器标志（flag）。

`Cargo.toml`

[package]
...
build = "build.rs"

[build-dependencies]
cc = "1"

[dependencies]
error-chain = "0.11"

`build.rs`

fn main() {
    cc::Build::new()
        .file("src/hello.c")
        .compile("hello");   // 输出 `libhello.a`
}

`src/hello.c`

#include <stdio.h>


void hello() {
    printf("Hello from C!\n");
}

void greet(const char* name) {
    printf("Hello, %s!\n", name);
}

`src/main.rs`

use error_chain::error_chain;
use std::ffi::CString;
use std::os::raw::c_char;

error_chain! {
    foreign_links {
        NulError(::std::ffi::NulError);
        Io(::std::io::Error);
    }
}
fn prompt(s: &str) -> Result<String> {
    use std::io::Write;
    print!("{}", s);
    std::io::stdout().flush()?;
    let mut input = String::new();
    std::io::stdin().read_line(&mut input)?;
    Ok(input.trim().to_string())
}

extern {
    fn hello();
    fn greet(name: *const c_char);
}

fn main() -> Result<()> {
    unsafe { hello() }
    let name = prompt("What's your name? ")?;
    let c_name = CString::new(name)?;
    unsafe { greet(c_name.as_ptr()) }
    Ok(())
}

编译并静态链接到绑定的 C++ 语言库

链接绑定的 C++ 语言库非常类似于链接绑定的 C 语言库。编译并静态链接绑定的 C++ 库时，与链接绑定的 C 语言库相比有两个核心区别：一是通过构造器方法 cpp(true) 指定 C++ 编译器；二是通过在 C++ 源文件顶部添加 extern "C" 代码段，以防止 C++ 编译器的名称篡改。

`Cargo.toml`

[package]
...
build = "build.rs"

[build-dependencies]
cc = "1"

`build.rs`

fn main() {
    cc::Build::new()
        .cpp(true)
        .file("src/foo.cpp")
        .compile("foo");   
}

`src/foo.cpp`

extern "C" {
    int multiply(int x, int y);
}

int multiply(int x, int y) {
    return x*y;
}

`src/main.rs`

extern {
    fn multiply(x : i32, y : i32) -> i32;
}

fn main(){
    unsafe {
        println!("{}", multiply(5,7));
    }   
}

编译 C 语言库时自定义设置

使用 cc::Build::define 自定义构建绑定的 C 语言代码非常简单。该方法接受 Option 值，因此可以创建这样的定义：#define APP_NAME "foo"、#define WELCOME（将 None 作为不确定值传递）。如下实例构建了一个绑定的 C 语言文件，其在 build.rs 中设置了动态定义，并在运行时打印 “Welcome to foo - version 1.0.2”。Cargo 设定了一些环境变量，这些变量可能对某些自定义设置有用。

`Cargo.toml`

[package]
...
version = "1.0.2"
build = "build.rs"

[build-dependencies]
cc = "1"

`build.rs`

fn main() {
    cc::Build::new()
        .define("APP_NAME", "\"foo\"")
        .define("VERSION", format!("\"{}\"", env!("CARGO_PKG_VERSION")).as_str())
        .define("WELCOME", None)
        .file("src/foo.c")
        .compile("foo");
}

`src/foo.c`

#include <stdio.h>

void print_app_info() {
#ifdef WELCOME
    printf("Welcome to ");
#endif
    printf("%s - version %s\n", APP_NAME, VERSION);
}

`src/main.rs`

extern {
    fn print_app_info();
}

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

Rust Cookbook 中文版 - A Rust Cookbook