Struct Target

pub struct Target { /* private fields */ }

Exposes an interface for testing whether the target system supports a particular feature or provides certain functionality. This is the bulk of the rsconf api.

Implementations

impl Target

pub fn new() -> Result<Target>

Create a new rsconf instance using the default cc::Build toolchain for the current compilation target.

Use Target::new_from() to use a configured cc::Build instance instead.

pub fn new_from(toolchain: Build) -> Result<Target>

Create a new rsconf instance from the configured cc::Build instance toolchain.

All tests inherit their base configuration from toolchain, so make sure it is configured with the appropriate header and library search paths as needed.

pub fn set_verbose(&mut self, verbose: bool)

Enables or disables verbose mode.

In verbose mode, output of rsconf calls to the compiler are displayed to stdout and stderr. It is not enabled by default.

Note that cargo suppresses all build.rs output in case of successful execution by default; intentionally fail the build (e.g. add a panic!() call) or compile with cargo build -vv to see verbose output.

pub fn has_type(&self, name: &str) -> bool

Checks whether a definition for type name exists without pulling in any headers.

This operation does not link the output; only the header file is inspected.

pub fn has_type_in(&self, name: &str, headers: &[&str]) -> bool

Checks whether a definition for type name exists in the supplied header or headers.

The headers are included in the order they are provided for testing. See has_type() for more info.

pub fn has_symbol(&self, symbol: &str) -> bool

Checks whether or not the the requested symbol is exported by libc/by default (without linking against any additional libraries).

See has_symbol_in() to link against one or more libraries and test.

This only checks for symbols exported by the C abi (so mangled names are required) and does not check for compile-time definitions provided by header files.

See has_type() to check for compile-time definitions. This function will return false if library could not be found or could not be linked; see has_library() to test if library can be linked separately.

pub fn has_symbol_in(&self, symbol: &str, libraries: &[&str]) -> bool

Like has_symbol() but links against a library or any number of libraries.

You might need to supply multiple libraries if symbol is in a library that has its own transitive dependencies that must also be linked for compilation to succeed. Note that libraries are linked in the order they are provided.

pub fn has_symbols_in(&self, symbols: &[&str], libraries: &[&str]) -> bool

Checks for the presence of all the named symbols in the libraries provided.

Libraries are linked in the order provided. See has_symbol() and has_symbol_in() for more information.

pub fn has_library(&self, library: &str) -> bool

Tests whether or not it was possible to link against library.

If it is not possible to link against library without also linking against its transitive dependencies, use has_libraries() to link against multiple libraries (in the order provided).

You should normally pass the name of the library without any prefixes or suffixes. If a suffix is provided, it will not be removed.

You may pass a full path to the library (again minus the extension) instead of just the library name in order to try linking against a library not in the library search path. Alternatively, configure the cc::Build instance with the search paths as needed before passing it to Target::new().

Under Windows, if library does not have an extension it will be suffixed with .lib prior to testing linking. (This way it works under under both cl.exe and clang.exe.)

pub fn has_libraries(&self, libraries: &[&str]) -> bool

Tests whether or not it was possible to link against all of libraries.

See has_library() for more information.

The libraries will be linked in the order they are provided in when testing, which may influence the outcome.

pub fn find_first_library<'a>(&self, libraries: &'a [&str]) -> Option<&'a str>

Returns the first library from those provided that can be successfully linked.

Returns a reference to the first library name that was passed in that was ultimately found and linked successfully on the target system or None otherwise. See has_library() for more information.

pub fn find_first_library_with<'a>( &self, libraries: &'a [&str], symbols: &[&str], ) -> Option<&'a str>

Returns the first library from those provided that can be successfully linked and contains all named symbols.

Returns a reference to the first library name that was passed in that was ultimately found on the target system and contains all the symbol names provided, or None if no such library was found. See has_library() and has_symbol() for more information.

pub fn has_header(&self, header: &str) -> bool

Checks whether the cc::Build passed to Target::new() as configured can pull in the named header file.

If including header requires pulling in additional headers before it to compile, use has_headers() instead to include multiple headers in the order they’re specified.

pub fn has_headers(&self, headers: &[&str]) -> bool

Checks whether the cc::Build passed to Target::new() as configured can pull in the named headers in the order they’re provided.

pub fn try_link_library(&self, library: &str, how: LinkType) -> bool

A convenience function that links against library if it is found and linkable.

This is internally a call to has_library() followed by a conditional call to link_library().

pub fn try_link_libraries(&self, libraries: &[&str], how: LinkType) -> bool

A convenience function that links against libraries only if they are all found and linkable.

This is internally a call to has_libraries() followed by a conditional call to link_libraries().

pub fn ifdef(&self, define: &str, headers: &[&str]) -> bool

Evaluates whether or not define is an extant preprocessor definition.

This is the C equivalent of #ifdef xxxx and does not check if there is a value associated with the definition. (You can use r#if() to test if a define has a particular value.)

pub fn if(&self, condition: &str, headers: &[&str]) -> bool

Evaluates whether or not condition evaluates to true at the C preprocessor time.

This can be used with condition set to defined(FOO) to perform the equivalent of ifdef() or it can be used to check for specific values e.g. with condition set to something like FOO != 0.

pub fn get_i32_value( &self, ident: &str, headers: &[&str], ) -> Result<i32, Box<dyn Error + Send + Sync + 'static>>

Attempts to retrieve the definition of ident as an i32 value.

Returns Ok in case ident was defined, has a concrete value, is a compile-time constant (i.e. does not need to be linked to retrieve the value), and is a valid i32 value.

Cross-compliation note:

The get_xxx_value() methods do not currently support cross-compilation scenarios as they require being able to run a binary compiled for the target platform.

pub fn get_u32_value( &self, ident: &str, headers: &[&str], ) -> Result<u32, Box<dyn Error + Send + Sync + 'static>>

Attempts to retrieve the definition of ident as a u32 value.

Returns Ok in case ident was defined, has a concrete value, is a compile-time constant (i.e. does not need to be linked to retrieve the value), and is a valid u32 value.

Cross-compliation note:

The get_xxx_value() methods do not currently support cross-compilation scenarios as they require being able to run a binary compiled for the target platform.

pub fn get_i64_value( &self, ident: &str, headers: &[&str], ) -> Result<i64, Box<dyn Error + Send + Sync + 'static>>

Attempts to retrieve the definition of ident as an i64 value.

Returns Ok in case ident was defined, has a concrete value, is a compile-time constant (i.e. does not need to be linked to retrieve the value), and is a valid i64 value.

Cross-compliation note:

The get_xxx_value() methods do not currently support cross-compilation scenarios as they require being able to run a binary compiled for the target platform.

pub fn get_u64_value( &self, ident: &str, headers: &[&str], ) -> Result<u64, Box<dyn Error + Send + Sync + 'static>>

Attempts to retrieve the definition of ident as a u64 value.

Returns Ok in case ident was defined, has a concrete value, is a compile-time constant (i.e. does not need to be linked to retrieve the value), and is a valid u64 value.

Cross-compliation note:

The get_xxx_value() methods do not currently support cross-compilation scenarios as they require being able to run a binary compiled for the target platform.

pub fn get_macro_value( &self, ident: &str, headers: &[&str], ) -> Result<Option<String>, Box<dyn Error + Send + Sync + 'static>>

Retrieve the definition of a C preprocessor macro or define.

For “function macros” like max(x, y), make sure to supply parentheses and pass in placeholders for the parameters (like the x and y in the example); they will be returned as-is in the expanded output.

pub fn get_macro_value_recursive( &self, ident: &str, headers: &[&str], ) -> Result<Option<String>, Box<dyn Error + Send + Sync + 'static>>

Retrieve the definition of a C preprocessor macro or define, recursively in case it is defined in terms of another #define.

For “function macros” like max(x, y), make sure to pass in placeholders for the parameters (they will be returned as-is in the expanded output).

Trait Implementations

impl From<Build> for Target

fn from(build: Build) -> Self

Converts to this type from the input type.