|
| 1 | +# Build Tools |
| 2 | + |
| 3 | +This section covers "build-time" tooling, or code that is run prior to compiling a crate's source code. |
| 4 | +Conventionally, build-time code lives in a `build.rs` file and is commonly referred to as a "build script". |
| 5 | +Common use cases include `rust` code generation and compilation of bundled `C` code. |
| 6 | +See `crates.io`'s [documentation on the matter][build-script-docs] for more information. |
| 7 | + |
| 8 | +Notes: |
| 9 | +- Examples in this section will likely show content for several files. |
| 10 | +- Since [`play.rust-lang.org`][playground] doesn't support specifying/running build scripts, most of |
| 11 | + the following examples will fail when trying to run them directly in the browser with the |
| 12 | + "play" (<i class="fa fa-play"></i>) button. Running will require setting up a local project |
| 13 | + and making the modifications shown. |
| 14 | + |
| 15 | +| Recipe | Crates | Categories | |
| 16 | +|--------|--------|------------| |
| 17 | +| [Compile and link statically to a bundled C library][ex-cc-static-bundled] | [![cc-badge]][cc] | [![cat-development-tools-badge]][cat-development-tools] [![cat-rust-patterns-badge]][cat-rust-patterns] [![cat-external-ffi-bindings-badge]][cat-external-ffi-bindings] | |
| 18 | + |
| 19 | + |
| 20 | +[ex-cc-static-bundled]: #ex-cc-static-bundled |
| 21 | +<a name="ex-cc-static-bundled"></a> |
| 22 | +## Compile and link statically to a bundled C library |
| 23 | + |
| 24 | +[![cat-development-tools-badge]][cat-development-tools] [![cc-badge]][cc] [![cat-rust-patterns-badge]][cat-rust-patterns] [![cat-external-ffi-bindings-badge]][cat-external-ffi-bindings] |
| 25 | + |
| 26 | +To accommodate scenarios where additional `C`, `C++`, or `assembly` is required in a project, the [`cc`][cc] crate |
| 27 | +offers a simple api for compiling bundled `c/c++/asm` code into static libraries (`.a`) that can be statically linked to by `rustc`. |
| 28 | + |
| 29 | +### `Cargo.toml` |
| 30 | + |
| 31 | +```toml |
| 32 | +[package] |
| 33 | +... |
| 34 | +build = "build.rs" |
| 35 | + |
| 36 | +[build-dependencies] |
| 37 | +cc = "1" |
| 38 | + |
| 39 | +[dependencies] |
| 40 | +error-chain = "0.11" |
| 41 | +``` |
| 42 | + |
| 43 | +### `build.rs` |
| 44 | + |
| 45 | +```rust,no_run |
| 46 | +extern crate cc; |
| 47 | +
|
| 48 | +fn main() { |
| 49 | + // builds a static lib: `libhello.a` |
| 50 | + cc::Build::new() |
| 51 | + .file("src/hello.c") |
| 52 | + .compile("hello"); |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +### `src/hello.c` |
| 57 | + |
| 58 | +```c |
| 59 | +#include <stdio.h> |
| 60 | + |
| 61 | + |
| 62 | +void hello() { |
| 63 | + printf("Hello from C!\n"); |
| 64 | +} |
| 65 | + |
| 66 | +void greet(const char* name) { |
| 67 | + printf("Hello, %s!\n", name); |
| 68 | +} |
| 69 | +``` |
| 70 | +
|
| 71 | +### `src/main.rs` |
| 72 | +
|
| 73 | +```rust,no_run |
| 74 | +# #[macro_use] extern crate error_chain; |
| 75 | +use std::ffi::CString; |
| 76 | +use std::os::raw::c_char; |
| 77 | +
|
| 78 | +# |
| 79 | +# error_chain! { |
| 80 | +# foreign_links { |
| 81 | +# NulError(::std::ffi::NulError); |
| 82 | +# Io(::std::io::Error); |
| 83 | +# } |
| 84 | +# } |
| 85 | +# |
| 86 | +# |
| 87 | +# fn prompt(s: &str) -> Result<String> { |
| 88 | +# use std::io::Write; |
| 89 | +# print!("{}", s); |
| 90 | +# std::io::stdout().flush()?; |
| 91 | +# let mut input = String::new(); |
| 92 | +# std::io::stdin().read_line(&mut input)?; |
| 93 | +# Ok(input.trim().to_string()) |
| 94 | +# } |
| 95 | +# |
| 96 | +
|
| 97 | +extern { |
| 98 | + fn hello(); |
| 99 | + fn greet(name: *const c_char); |
| 100 | +} |
| 101 | +
|
| 102 | +
|
| 103 | +fn run() -> Result<()> { |
| 104 | + unsafe { hello() } |
| 105 | + let name = prompt("What's your name? ")?; |
| 106 | + let c_name = CString::new(name)?; |
| 107 | + unsafe { greet(c_name.as_ptr()) } |
| 108 | + Ok(()) |
| 109 | +} |
| 110 | +
|
| 111 | +# |
| 112 | +# quick_main!(run); |
| 113 | +``` |
| 114 | + |
| 115 | + |
| 116 | +{{#include links.md}} |
| 117 | + |
| 118 | +<!-- Other Reference --> |
| 119 | + |
| 120 | +[build-script-docs]: http://doc.crates.io/build-script.html |
| 121 | +[playground]: https://play.rust-lang.org |
| 122 | + |
0 commit comments