Struct cc::Build[][src]

pub struct Build { /* fields omitted */ }
Expand description

A builder for compilation of a native 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.

Implementations

Construct a new instance of a blank set of configuration.

This builder is finished with the compile function.

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");

Add multiple directories to the -I include path.

Example

let mut extra_dir = None;
if condition {
    extra_dir = Some(Path::new("/path/to"));
}

cc::Build::new()
    .file("src/foo.c")
    .includes(extra_dir)
    .compile("foo");

Specify a -D variable with an optional value.

Example

cc::Build::new()
    .file("src/foo.c")
    .define("FOO", "BAR")
    .define("BAZ", None)
    .compile("foo");

Add an arbitrary object file to link in

Add an arbitrary flag to the invocation of the compiler

Example

cc::Build::new()
    .file("src/foo.c")
    .flag("-ffunction-sections")
    .compile("foo");

Add an arbitrary flag to the invocation of the compiler

Example

cc::Build::new()
    .file("src/foo.c")
    .file("src/bar.c")
    .ar_flag("/NODEFAULTLIB:libc.dll")
    .compile("foo");

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 compiler 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.

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");

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");

Disables the generation of default compiler flags. The default compiler flags may cause conflicts in some cross compiling scenarios.

Setting the CRATE_CC_NO_DEFAULTS environment variable has the same effect as setting this to true. The presence of the environment variable and the value of no_default_flags will be OR’d together.

Add a file which will be compiled

Add files which will be compiled

Set C++ support.

The other cpp_* options will only become active if this is set to true.

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.

Link CUDA run-time.

This option mimics the --cudart NVCC command-line option. Just like the original it accepts {none|shared|static}, with default being static. The method has to be invoked after .cuda(true), or not at all, if the default is right for the project.

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");

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");

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");

Set the standard library to link against when compiling with C++ support.

See get_cpp_link_stdlib documentation for the default value. If the CXXSTDLIB environment variable is set, its value will override the default value, but not the value explicitly set by calling this function.

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 GNU
  • c++ for Clang
  • c++_shared or c++_static for Android

Example

cc::Build::new()
    .file("src/foo.c")
    .shared_flag(true)
    .cpp_link_stdlib("stdc++")
    .compile("libfoo.so");

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 conjunction 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 GNU
  • c++ for Clang

Example

cc::Build::new()
    .file("src/foo.c")
    .cpp_set_stdlib("c++")
    .compile("libfoo.a");

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");

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");

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.

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.

Configures whether the compiler will emit debug information when generating object files.

This option is automatically scraped from the DEBUG environment variable by build scripts, so it’s not required to call this function.

Configures whether the compiler will emit instructions to store frame pointers during codegen.

This option is automatically enabled when debug information is emitted. Otherwise the target platform compiler’s default will be used. You can use this option to force a specific setting.

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.

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.

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.

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 lib
  • rustc-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

Configures whether the compiler will emit position independent code.

This option defaults to false for windows-gnu and bare metal targets and to true for all other targets.

Configures whether the Procedure Linkage Table is used for indirect calls into shared libraries.

The PLT is used to provide features like lazy binding, but introduces a small performance loss due to extra pointer indirection. Setting use_plt to false can provide a small performance increase.

Note that skipping the PLT requires a recent version of GCC/Clang.

This only applies to ELF targets. It has no effect on other platforms.

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.

Run the compiler, generating the file output

This will return a result instead of panicing; see compile() for the complete description.

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 compiler 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.

This will return a result instead of panicing; see expand() for the complete description.

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();

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.

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.