vendor/cc/README.md

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