]>
Commit | Line | Data |
---|---|---|
ea8adc8c | 1 | # cc-rs |
476ff2be | 2 | |
ea8adc8c | 3 | A library to compile C/C++/assembly into a Rust library/application. |
476ff2be | 4 | |
ea8adc8c XL |
5 | [![Build Status](https://travis-ci.org/alexcrichton/cc-rs.svg?branch=master)](https://travis-ci.org/alexcrichton/cc-rs) |
6 | [![Build status](https://ci.appveyor.com/api/projects/status/onu270iw98h81nwv?svg=true)](https://ci.appveyor.com/project/alexcrichton/cc-rs) | |
476ff2be | 7 | |
ea8adc8c | 8 | [Documentation](https://docs.rs/cc) |
476ff2be SL |
9 | |
10 | A simple library meant to be used as a build dependency with Cargo packages in | |
ea8adc8c XL |
11 | order to build a set of C/C++ files into a static archive. This crate calls out |
12 | to the most relevant compiler for a platform, for example using `cl` on MSVC. | |
476ff2be | 13 | |
abe05a73 XL |
14 | > **Note**: this crate was recently renamed from the `gcc` crate, so if you're |
15 | > looking for the `gcc` crate you're in the right spot! | |
16 | ||
ea8adc8c | 17 | ## Using cc-rs |
476ff2be SL |
18 | |
19 | First, you'll want to both add a build script for your crate (`build.rs`) and | |
20 | also add this crate to your `Cargo.toml` via: | |
21 | ||
22 | ```toml | |
476ff2be | 23 | [build-dependencies] |
ea8adc8c | 24 | cc = "1.0" |
476ff2be SL |
25 | ``` |
26 | ||
27 | Next up, you'll want to write a build script like so: | |
28 | ||
29 | ```rust,no_run | |
30 | // build.rs | |
31 | ||
ea8adc8c | 32 | extern crate cc; |
476ff2be SL |
33 | |
34 | fn main() { | |
ea8adc8c XL |
35 | cc::Build::new() |
36 | .file("foo.c") | |
37 | .file("bar.c") | |
38 | .compile("foo"); | |
476ff2be SL |
39 | } |
40 | ``` | |
41 | ||
42 | And that's it! Running `cargo build` should take care of the rest and your Rust | |
ea8adc8c XL |
43 | application will now have the C files `foo.c` and `bar.c` compiled into a file |
44 | named libfoo.a. You can call the functions in Rust by declaring functions in | |
45 | your Rust code like so: | |
476ff2be SL |
46 | |
47 | ``` | |
48 | extern { | |
49 | fn foo_function(); | |
50 | fn bar_function(); | |
51 | } | |
52 | ||
53 | pub fn call() { | |
54 | unsafe { | |
55 | foo_function(); | |
56 | bar_function(); | |
57 | } | |
58 | } | |
59 | ||
60 | fn main() { | |
61 | // ... | |
62 | } | |
63 | ``` | |
64 | ||
65 | ## External configuration via environment variables | |
66 | ||
67 | To control the programs and flags used for building, the builder can set a | |
68 | number of different environment variables. | |
69 | ||
ea8adc8c | 70 | * `CFLAGS` - a series of space separated flags passed to compilers. Note that |
476ff2be SL |
71 | individual flags cannot currently contain spaces, so doing |
72 | something like: "-L=foo\ bar" is not possible. | |
73 | * `CC` - the actual C compiler used. Note that this is used as an exact | |
74 | executable name, so (for example) no extra flags can be passed inside | |
75 | this variable, and the builder must ensure that there aren't any | |
76 | trailing spaces. This compiler must understand the `-c` flag. For | |
77 | certain `TARGET`s, it also is assumed to know about other flags (most | |
78 | common is `-fPIC`). | |
79 | * `AR` - the `ar` (archiver) executable to use to build the static library. | |
80 | ||
81 | Each of these variables can also be supplied with certain prefixes and suffixes, | |
82 | in the following prioritized order: | |
83 | ||
84 | 1. `<var>_<target>` - for example, `CC_x86_64-unknown-linux-gnu` | |
85 | 2. `<var>_<target_with_underscores>` - for example, `CC_x86_64_unknown_linux_gnu` | |
86 | 3. `<build-kind>_<var>` - for example, `HOST_CC` or `TARGET_CFLAGS` | |
87 | 4. `<var>` - a plain `CC`, `AR` as above. | |
88 | ||
ea8adc8c | 89 | If none of these variables exist, cc-rs uses built-in defaults |
476ff2be | 90 | |
ea8adc8c | 91 | In addition to the the above optional environment variables, `cc-rs` has some |
476ff2be SL |
92 | functions with hard requirements on some variables supplied by [cargo's |
93 | build-script driver][cargo] that it has the `TARGET`, `OUT_DIR`, `OPT_LEVEL`, | |
94 | and `HOST` variables. | |
95 | ||
96 | [cargo]: http://doc.crates.io/build-script.html#inputs-to-the-build-script | |
97 | ||
98 | ## Optional features | |
99 | ||
abe05a73 XL |
100 | ### Parallel |
101 | ||
ea8adc8c XL |
102 | Currently cc-rs supports parallel compilation (think `make -jN`) but this |
103 | feature is turned off by default. To enable cc-rs to compile C/C++ in parallel, | |
476ff2be SL |
104 | you can change your dependency to: |
105 | ||
106 | ```toml | |
107 | [build-dependencies] | |
ea8adc8c | 108 | cc = { version = "1.0", features = ["parallel"] } |
476ff2be SL |
109 | ``` |
110 | ||
ea8adc8c | 111 | By default cc-rs will limit parallelism to `$NUM_JOBS`, or if not present it |
8bb4bdeb XL |
112 | will limit it to the number of cpus on the machine. If you are using cargo, |
113 | use `-jN` option of `build`, `test` and `run` commands as `$NUM_JOBS` | |
114 | is supplied by cargo. | |
476ff2be SL |
115 | |
116 | ## Compile-time Requirements | |
117 | ||
118 | To work properly this crate needs access to a C compiler when the build script | |
119 | is being run. This crate does not ship a C compiler with it. The compiler | |
120 | required varies per platform, but there are three broad categories: | |
121 | ||
122 | * Unix platforms require `cc` to be the C compiler. This can be found by | |
ea8adc8c | 123 | installing cc/clang on Linux distributions and Xcode on OSX, for example. |
476ff2be SL |
124 | * Windows platforms targeting MSVC (e.g. your target triple ends in `-msvc`) |
125 | require `cl.exe` to be available and in `PATH`. This is typically found in | |
126 | standard Visual Studio installations and the `PATH` can be set up by running | |
127 | the appropriate developer tools shell. | |
128 | * Windows platforms targeting MinGW (e.g. your target triple ends in `-gnu`) | |
ea8adc8c | 129 | require `cc` to be available in `PATH`. We recommend the |
476ff2be SL |
130 | [MinGW-w64](http://mingw-w64.org) distribution, which is using the |
131 | [Win-builds](http://win-builds.org) installation system. | |
132 | You may also acquire it via | |
133 | [MSYS2](http://msys2.github.io), as explained [here][msys2-help]. Make sure | |
134 | to install the appropriate architecture corresponding to your installation of | |
135 | rustc. GCC from older [MinGW](http://www.mingw.org) project is compatible | |
136 | only with 32-bit rust compiler. | |
137 | ||
138 | [msys2-help]: http://github.com/rust-lang/rust#building-on-windows | |
139 | ||
140 | ## C++ support | |
141 | ||
ea8adc8c XL |
142 | `cc-rs` supports C++ libraries compilation by using the `cpp` method on |
143 | `Build`: | |
476ff2be SL |
144 | |
145 | ```rust,no_run | |
ea8adc8c | 146 | extern crate cc; |
476ff2be SL |
147 | |
148 | fn main() { | |
ea8adc8c | 149 | cc::Build::new() |
476ff2be SL |
150 | .cpp(true) // Switch to C++ library compilation. |
151 | .file("foo.cpp") | |
152 | .compile("libfoo.a"); | |
153 | } | |
154 | ``` | |
155 | ||
156 | When using C++ library compilation switch, the `CXX` and `CXXFLAGS` env | |
157 | variables are used instead of `CC` and `CFLAGS` and the C++ standard library is | |
158 | linked to the crate target. | |
159 | ||
2c00a5a8 XL |
160 | ## CUDA C++ support |
161 | ||
162 | `cc-rs` also supports compiling CUDA C++ libraries by using the `cuda` method | |
163 | on `Build` (currently for GNU/Clang toolchains only): | |
164 | ||
165 | ```rust,no_run | |
166 | extern crate cc; | |
167 | ||
168 | fn main() { | |
169 | cc::Build::new() | |
170 | // Switch to CUDA C++ library compilation using NVCC. | |
171 | .cuda(true) | |
172 | // Generate code for Maxwell (GTX 970, 980, 980 Ti, Titan X). | |
173 | .flag("-gencode").flag("arch=compute_52,code=sm_52") | |
174 | // Generate code for Maxwell (Jetson TX1). | |
175 | .flag("-gencode").flag("arch=compute_53,code=sm_53") | |
176 | // Generate code for Pascal (GTX 1070, 1080, 1080 Ti, Titan Xp). | |
177 | .flag("-gencode").flag("arch=compute_61,code=sm_61") | |
178 | // Generate code for Pascal (Tesla P100). | |
179 | .flag("-gencode").flag("arch=compute_60,code=sm_60") | |
180 | // Generate code for Pascal (Jetson TX2). | |
181 | .flag("-gencode").flag("arch=compute_62,code=sm_62") | |
182 | .file("bar.cu") | |
183 | .compile("libbar.a"); | |
184 | } | |
185 | ``` | |
186 | ||
476ff2be SL |
187 | ## License |
188 | ||
2c00a5a8 XL |
189 | This project is licensed under either of |
190 | ||
191 | * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or | |
192 | http://www.apache.org/licenses/LICENSE-2.0) | |
193 | * MIT license ([LICENSE-MIT](LICENSE-MIT) or | |
194 | http://opensource.org/licenses/MIT) | |
195 | ||
196 | at your option. | |
197 | ||
198 | ### Contribution | |
476ff2be | 199 | |
2c00a5a8 XL |
200 | Unless you explicitly state otherwise, any contribution intentionally submitted |
201 | for inclusion in Serde by you, as defined in the Apache-2.0 license, shall be | |
202 | dual licensed as above, without any additional terms or conditions. |