Struct cpp_build::Config

pub struct Config { /* fields omitted */ }

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 gcc-rs to build the compilation artifact, and many of the methods defined on this type directly proxy to an internal gcc::Config object.

Methods

impl Config

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.

fn include<P: AsRef<Path>>(&mut self, dir: P) -> &mut Self

Add a directory to the -I or include path for headers

fn define(&mut self, var: &str, val: Option<&str>) -> &mut Self

Specify a -D variable with an optional value

fn object<P: AsRef<Path>>(&mut self, obj: P) -> &mut Self

Add an arbitrary object file to link in

fn flag(&mut self, flag: &str) -> &mut Self

Add an arbitrary flag to the invocation of the compiler

fn file<P: AsRef<Path>>(&mut self, p: P) -> &mut Self

Add a file which will be compiled

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.