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