pub struct Config { /* private fields */ }
Expand description
This struct is for advanced users of the build script. It allows providing
configuration options to cpp
and the compiler when it is used to build.
API Note
Internally, cpp
uses the cc
crate to build the compilation artifact,
and many of the methods defined on this type directly proxy to an internal
cc::Build
object.
Implementations§
source§impl Config
impl Config
sourcepub fn new() -> Config
pub fn new() -> Config
Create a new Config
object. This object will hold the configuration
options which control the build. If you don’t need to make any changes,
cpp_build::build
is a wrapper function around this interface.
sourcepub fn include<P: AsRef<Path>>(&mut self, dir: P) -> &mut Self
pub fn include<P: AsRef<Path>>(&mut self, dir: P) -> &mut Self
Add a directory to the -I
or include path for headers
sourcepub fn define(&mut self, var: &str, val: Option<&str>) -> &mut Self
pub fn define(&mut self, var: &str, val: Option<&str>) -> &mut Self
Specify a -D
variable with an optional value
sourcepub fn object<P: AsRef<Path>>(&mut self, obj: P) -> &mut Self
pub fn object<P: AsRef<Path>>(&mut self, obj: P) -> &mut Self
Add an arbitrary object file to link in
sourcepub fn flag(&mut self, flag: &str) -> &mut Self
pub fn flag(&mut self, flag: &str) -> &mut Self
Add an arbitrary flag to the invocation of the compiler
sourcepub fn flag_if_supported(&mut self, flag: &str) -> &mut Self
pub fn flag_if_supported(&mut self, flag: &str) -> &mut Self
Add an arbitrary flag to the invocation of the compiler if it supports it
sourcepub fn cpp_link_stdlib(&mut self, cpp_link_stdlib: Option<&str>) -> &mut Self
pub fn cpp_link_stdlib(&mut self, cpp_link_stdlib: Option<&str>) -> &mut Self
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.
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.
sourcepub fn cpp_set_stdlib(&mut self, cpp_set_stdlib: Option<&str>) -> &mut Self
pub fn cpp_set_stdlib(&mut self, cpp_set_stdlib: Option<&str>) -> &mut Self
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.
sourcepub fn host(&mut self, host: &str) -> &mut Self
pub fn host(&mut self, host: &str) -> &mut Self
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.
sourcepub fn opt_level(&mut self, opt_level: u32) -> &mut Self
pub fn opt_level(&mut self, opt_level: u32) -> &mut Self
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.
sourcepub fn opt_level_str(&mut self, opt_level: &str) -> &mut Self
pub fn opt_level_str(&mut self, opt_level: &str) -> &mut Self
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.
sourcepub fn debug(&mut self, debug: bool) -> &mut Self
pub fn debug(&mut self, debug: bool) -> &mut Self
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.
sourcepub fn compiler<P: AsRef<Path>>(&mut self, compiler: P) -> &mut Self
pub fn compiler<P: AsRef<Path>>(&mut self, compiler: P) -> &mut Self
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.
sourcepub fn archiver<P: AsRef<Path>>(&mut self, archiver: P) -> &mut Self
pub fn archiver<P: AsRef<Path>>(&mut self, archiver: P) -> &mut Self
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.
sourcepub fn cargo_metadata(&mut self, cargo_metadata: bool) -> &mut Self
pub fn cargo_metadata(&mut self, cargo_metadata: bool) -> &mut Self
Define whether metadata should be emitted for cargo allowing it to
automatically link the binary. Defaults to true
.
sourcepub fn pic(&mut self, pic: bool) -> &mut Self
pub fn pic(&mut self, pic: bool) -> &mut Self
Configures whether the compiler will emit position independent code.
This option defaults to false
for i686
and windows-gnu
targets and
to true
for all other targets.
sourcepub fn build<P: AsRef<Path>>(&mut self, crate_root: P)
pub fn build<P: AsRef<Path>>(&mut self, crate_root: P)
Extracts cpp
declarations from the passed-in crate root, and builds
the associated static library to be linked in to the final binary.
This method does not perform rust codegen - that is performed by cpp
and cpp_macros
, which perform the actual procedural macro expansion.
This method may technically be called more than once for ergonomic
reasons, but that usually won’t do what you want. Use a different
Config
object each time you want to build a crate.