Struct cc::Build [−][src]
pub struct Build { /* fields omitted */ }
A builder for compilation of a native static library.
A Build
is the main type of the cc
crate and is used to control all the
various configuration options and such of a compile. You'll find more
documentation on each method itself.
Methods
impl Build
[src]
impl Build
pub fn new() -> Build
[src]
pub fn new() -> Build
Construct a new instance of a blank set of configuration.
This builder is finished with the compile
function.
pub fn include<P: AsRef<Path>>(&mut self, dir: P) -> &mut Build
[src]
pub fn include<P: AsRef<Path>>(&mut self, dir: P) -> &mut Build
Add a directory to the -I
or include path for headers
Example
use std::path::Path; let library_path = Path::new("/path/to/library"); cc::Build::new() .file("src/foo.c") .include(library_path) .include("src") .compile("foo");
pub fn define<'a, V: Into<Option<&'a str>>>(
&mut self,
var: &str,
val: V
) -> &mut Build
[src]
pub fn define<'a, V: Into<Option<&'a str>>>(
&mut self,
var: &str,
val: V
) -> &mut Build
Specify a -D
variable with an optional value.
Example
cc::Build::new() .file("src/foo.c") .define("FOO", "BAR") .define("BAZ", None) .compile("foo");
pub fn object<P: AsRef<Path>>(&mut self, obj: P) -> &mut Build
[src]
pub fn object<P: AsRef<Path>>(&mut self, obj: P) -> &mut Build
Add an arbitrary object file to link in
pub fn flag(&mut self, flag: &str) -> &mut Build
[src]
pub fn flag(&mut self, flag: &str) -> &mut Build
Add an arbitrary flag to the invocation of the compiler
Example
cc::Build::new() .file("src/foo.c") .flag("-ffunction-sections") .compile("foo");
pub fn is_flag_supported(&self, flag: &str) -> Result<bool, Error>
[src]
pub fn is_flag_supported(&self, flag: &str) -> Result<bool, Error>
Run the compiler to test if it accepts the given flag.
For a convenience method for setting flags conditionally,
see flag_if_supported()
.
It may return error if it's unable to run the compilier with a test file
(e.g. the compiler is missing or a write to the out_dir
failed).
Note: Once computed, the result of this call is stored in the
known_flag_support
field. If is_flag_supported(flag)
is called again, the result will be read from the hash table.
pub fn flag_if_supported(&mut self, flag: &str) -> &mut Build
[src]
pub fn flag_if_supported(&mut self, flag: &str) -> &mut Build
Add an arbitrary flag to the invocation of the compiler if it supports it
Example
cc::Build::new() .file("src/foo.c") .flag_if_supported("-Wlogical-op") // only supported by GCC .flag_if_supported("-Wunreachable-code") // only supported by clang .compile("foo");
Set the -shared
flag.
When enabled, the compiler will produce a shared object which can then be linked with other objects to form an executable.
Example
cc::Build::new() .file("src/foo.c") .shared_flag(true) .compile("libfoo.so");
pub fn static_flag(&mut self, static_flag: bool) -> &mut Build
[src]
pub fn static_flag(&mut self, static_flag: bool) -> &mut Build
Set the -static
flag.
When enabled on systems that support dynamic linking, this prevents linking with the shared libraries.
Example
cc::Build::new() .file("src/foo.c") .shared_flag(true) .static_flag(true) .compile("foo");
pub fn file<P: AsRef<Path>>(&mut self, p: P) -> &mut Build
[src]
pub fn file<P: AsRef<Path>>(&mut self, p: P) -> &mut Build
Add a file which will be compiled
pub fn files<P>(&mut self, p: P) -> &mut Build where
P: IntoIterator,
P::Item: AsRef<Path>,
[src]
pub fn files<P>(&mut self, p: P) -> &mut Build where
P: IntoIterator,
P::Item: AsRef<Path>,
Add files which will be compiled
pub fn cpp(&mut self, cpp: bool) -> &mut Build
[src]
pub fn cpp(&mut self, cpp: bool) -> &mut Build
Set C++ support.
The other cpp_*
options will only become active if this is set to
true
.
pub fn cuda(&mut self, cuda: bool) -> &mut Build
[src]
pub fn cuda(&mut self, cuda: bool) -> &mut Build
Set CUDA C++ support.
Enabling CUDA will pass the detected C/C++ toolchain as an argument to the CUDA compiler, NVCC. NVCC itself accepts some limited GNU-like args; any other arguments for the C/C++ toolchain will be redirected using "-Xcompiler" flags.
If enabled, this also implicitly enables C++ support.
pub fn warnings_into_errors(&mut self, warnings_into_errors: bool) -> &mut Build
[src]
pub fn warnings_into_errors(&mut self, warnings_into_errors: bool) -> &mut Build
Set warnings into errors flag.
Disabled by default.
Warning: turning warnings into errors only make sense if you are a developer of the crate using cc-rs. Some warnings only appear on some architecture or specific version of the compiler. Any user of this crate, or any other crate depending on it, could fail during compile time.
Example
cc::Build::new() .file("src/foo.c") .warnings_into_errors(true) .compile("libfoo.a");
pub fn warnings(&mut self, warnings: bool) -> &mut Build
[src]
pub fn warnings(&mut self, warnings: bool) -> &mut Build
Set warnings flags.
Adds some flags:
- "/Wall" for MSVC.
- "-Wall", "-Wextra" for GNU and Clang.
Enabled by default.
Example
cc::Build::new() .file("src/foo.c") .warnings(false) .compile("libfoo.a");
pub fn extra_warnings(&mut self, warnings: bool) -> &mut Build
[src]
pub fn extra_warnings(&mut self, warnings: bool) -> &mut Build
Set extra warnings flags.
Adds some flags:
- nothing for MSVC.
- "-Wextra" for GNU and Clang.
Enabled by default.
Example
// Disables -Wextra, -Wall remains enabled: cc::Build::new() .file("src/foo.c") .extra_warnings(false) .compile("libfoo.a");
pub fn cpp_link_stdlib<'a, V: Into<Option<&'a str>>>(
&mut self,
cpp_link_stdlib: V
) -> &mut Build
[src]
pub fn cpp_link_stdlib<'a, V: Into<Option<&'a str>>>(
&mut self,
cpp_link_stdlib: V
) -> &mut Build
Set the standard library to link against when compiling with C++ support.
The default value of this property depends on the current target: On
OS X Some("c++")
is used, when compiling for a Visual Studio based
target None
is used and for other targets Some("stdc++")
is used.
If the CXXSTDLIB
environment variable is set, its value will
override the default value.
A value of None
indicates that no automatic linking should happen,
otherwise cargo will link against the specified library.
The given library name must not contain the lib
prefix.
Common values:
stdc++
for GNUc++
for Clang
Example
cc::Build::new() .file("src/foo.c") .shared_flag(true) .cpp_link_stdlib("stdc++") .compile("libfoo.so");
pub fn cpp_set_stdlib<'a, V: Into<Option<&'a str>>>(
&mut self,
cpp_set_stdlib: V
) -> &mut Build
[src]
pub fn cpp_set_stdlib<'a, V: Into<Option<&'a str>>>(
&mut self,
cpp_set_stdlib: V
) -> &mut Build
Force the C++ compiler to use the specified standard library.
Setting this option will automatically set cpp_link_stdlib
to the same
value.
The default value of this option is always None
.
This option has no effect when compiling for a Visual Studio based target.
This option sets the -stdlib
flag, which is only supported by some
compilers (clang, icc) but not by others (gcc). The library will not
detect which compiler is used, as such it is the responsibility of the
caller to ensure that this option is only used in conjuction with a
compiler which supports the -stdlib
flag.
A value of None
indicates that no specific C++ standard library should
be used, otherwise -stdlib
is added to the compile invocation.
The given library name must not contain the lib
prefix.
Common values:
stdc++
for GNUc++
for Clang
Example
cc::Build::new() .file("src/foo.c") .cpp_set_stdlib("c++") .compile("libfoo.a");
pub fn target(&mut self, target: &str) -> &mut Build
[src]
pub fn target(&mut self, target: &str) -> &mut Build
Configures the target this configuration will be compiling for.
This option is automatically scraped from the TARGET
environment
variable by build scripts, so it's not required to call this function.
Example
cc::Build::new() .file("src/foo.c") .target("aarch64-linux-android") .compile("foo");
pub fn host(&mut self, host: &str) -> &mut Build
[src]
pub fn host(&mut self, host: &str) -> &mut Build
Configures the host assumed by this configuration.
This option is automatically scraped from the HOST
environment
variable by build scripts, so it's not required to call this function.
Example
cc::Build::new() .file("src/foo.c") .host("arm-linux-gnueabihf") .compile("foo");
pub fn opt_level(&mut self, opt_level: u32) -> &mut Build
[src]
pub fn opt_level(&mut self, opt_level: u32) -> &mut Build
Configures the optimization level of the generated object files.
This option is automatically scraped from the OPT_LEVEL
environment
variable by build scripts, so it's not required to call this function.
pub fn opt_level_str(&mut self, opt_level: &str) -> &mut Build
[src]
pub fn opt_level_str(&mut self, opt_level: &str) -> &mut Build
Configures the optimization level of the generated object files.
This option is automatically scraped from the OPT_LEVEL
environment
variable by build scripts, so it's not required to call this function.
pub fn debug(&mut self, debug: bool) -> &mut Build
[src]
pub fn debug(&mut self, debug: bool) -> &mut Build
Configures whether the compiler will emit debug information when generating object files.
This option is automatically scraped from the PROFILE
environment
variable by build scripts (only enabled when the profile is "debug"), so
it's not required to call this function.
pub fn out_dir<P: AsRef<Path>>(&mut self, out_dir: P) -> &mut Build
[src]
pub fn out_dir<P: AsRef<Path>>(&mut self, out_dir: P) -> &mut Build
Configures the output directory where all object files and static libraries will be located.
This option is automatically scraped from the OUT_DIR
environment
variable by build scripts, so it's not required to call this function.
pub fn compiler<P: AsRef<Path>>(&mut self, compiler: P) -> &mut Build
[src]
pub fn compiler<P: AsRef<Path>>(&mut self, compiler: P) -> &mut Build
Configures the compiler to be used to produce output.
This option is automatically determined from the target platform or a number of environment variables, so it's not required to call this function.
pub fn archiver<P: AsRef<Path>>(&mut self, archiver: P) -> &mut Build
[src]
pub fn archiver<P: AsRef<Path>>(&mut self, archiver: P) -> &mut Build
Configures the tool used to assemble archives.
This option is automatically determined from the target platform or a number of environment variables, so it's not required to call this function.
pub fn cargo_metadata(&mut self, cargo_metadata: bool) -> &mut Build
[src]
pub fn cargo_metadata(&mut self, cargo_metadata: bool) -> &mut Build
Define whether metadata should be emitted for cargo allowing it to
automatically link the binary. Defaults to true
.
The emitted metadata is:
rustc-link-lib=static=
compiled librustc-link-search=native=
target folder- When target is MSVC, the ATL-MFC libs are added via
rustc-link-search=native=
- When C++ is enabled, the C++ stdlib is added via
rustc-link-lib
pub fn pic(&mut self, pic: bool) -> &mut Build
[src]
pub fn pic(&mut self, pic: bool) -> &mut Build
Configures whether the compiler will emit position independent code.
This option defaults to false
for windows-gnu
targets and
to true
for all other targets.
pub fn static_crt(&mut self, static_crt: bool) -> &mut Build
[src]
pub fn static_crt(&mut self, static_crt: bool) -> &mut Build
Configures whether the /MT flag or the /MD flag will be passed to msvc build tools.
This option defaults to false
, and affect only msvc targets.
pub fn try_compile(&self, output: &str) -> Result<(), Error>
[src]
pub fn try_compile(&self, output: &str) -> Result<(), Error>
Run the compiler, generating the file output
This will return a result instead of panicing; see compile() for the complete description.
pub fn compile(&self, output: &str)
[src]
pub fn compile(&self, output: &str)
Run the compiler, generating the file output
The name output
should be the name of the library. For backwards compatibility,
the output
may start with lib
and end with .a
. The Rust compilier will create
the assembly with the lib prefix and .a extension. MSVC will create a file without prefix,
ending with .lib
.
Panics
Panics if output
is not formatted correctly or if one of the underlying
compiler commands fails. It can also panic if it fails reading file names
or creating directories.
pub fn try_expand(&self) -> Result<Vec<u8>, Error>
[src]
pub fn try_expand(&self) -> Result<Vec<u8>, Error>
This will return a result instead of panicing; see expand() for the complete description.
pub fn expand(&self) -> Vec<u8>
[src]
pub fn expand(&self) -> Vec<u8>
Run the compiler, returning the macro-expanded version of the input files.
This is only relevant for C and C++ files.
Panics
Panics if more than one file is present in the config, or if compiler path has an invalid file name.
Example
let out = cc::Build::new().file("src/foo.c").expand();
pub fn get_compiler(&self) -> Tool
[src]
pub fn get_compiler(&self) -> Tool
Get the compiler that's in use for this configuration.
This function will return a Tool
which represents the culmination
of this configuration at a snapshot in time. The returned compiler can
be inspected (e.g. the path, arguments, environment) to forward along to
other tools, or the to_command
method can be used to invoke the
compiler itself.
This method will take into account all configuration such as debug information, optimization level, include directories, defines, etc. Additionally, the compiler binary in use follows the standard conventions for this path, e.g. looking at the explicitly set compiler, environment variables (a number of which are inspected here), and then falling back to the default configuration.
Panics
Panics if an error occurred while determining the architecture.
pub fn try_get_compiler(&self) -> Result<Tool, Error>
[src]
pub fn try_get_compiler(&self) -> Result<Tool, Error>
Get the compiler that's in use for this configuration.
This will return a result instead of panicing; see get_compiler() for the complete description.
Trait Implementations
impl Clone for Build
[src]
impl Clone for Build
fn clone(&self) -> Build
[src]
fn clone(&self) -> Build
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
impl Debug for Build
[src]
impl Debug for Build
fn fmt(&self, f: &mut Formatter) -> Result
[src]
fn fmt(&self, f: &mut Formatter) -> Result
Formats the value using the given formatter. Read more
impl Default for Build
[src]
impl Default for Build