Struct probe_c_api::Probe

pub struct Probe<'a> { /* fields omitted */ }

A struct that stores information about how to compile and run test programs.

The main functionality of probe_c_api is implemented using the methods on Probe. The lifetime parameter is provided in order to allow closures to be used for the compiler and run commands. If 'static types implementing Fn are used (e.g. function pointers), the lifetime may be 'static.

Methods

impl<'a> Probe<'a>

fn new<C: 'a, R: 'a>(
    headers: Vec<String>,
    work_dir: &Path,
    compile_to: C,
    run: R
) -> Result<Probe<'a>, NewProbeError> where
    C: Fn(&Path, &Path) -> CommandResult,
    R: Fn(&Path) -> CommandResult, 

Construct a Probe by specifying a work directory, a method to compile a C program, and a method to run a C program.

The headers argument is a vector of headers to include in every C program written by this probe. Each header should have the <> or "" delimiters surrounding it.

The work_dir argument should be a path to a directory where the probe can read, write, and execute files. We could attempt to verify this, but in practice there are too many platforms and security measures out there. So it is up to the user to figure out the difference between a failure of a test and an inability to run the test due to security measures.

Files in the work_dir are kept from colliding via random number generator, which makes it possible to execute tests in parallel, in practice.

The compile_to argument is responsible for taking a source file &Path (the first argument) and producing a runnable program at another &Path (the second argument). This is roughly equivalent to the shell script:

gcc -c $1 -o $2

compile_to should yield a CommandResult, which allows the exit status to be checked, and provides the standard output and error for debugging purposes.

The run argument is responsible for running the process and yielding its status and output, again as a CommandResult.

FIXME! Suggestions for equivalent non-POSIX examples, especially anything relevant for Windows, are welcomed.

fn check_compile(&self, source: &str) -> CommandResult

Write a byte slice to a file, then attempt to compile it.

This is not terribly useful, and is provided mostly for users who simply want to reuse a closure that was used to construct the Probe, as well as for convenience and testing of probe-c-api itself.

fn check_run(&self, source: &str) -> Result<CompileRunOutput>

Write a byte slice to a file, then attempt to compile and run it.

Like check_compile, this provides little value, but is available as a minor convenience.

fn size_of(&self, type_: &str) -> CProbeResult<usize>

Get the size of a C type, in bytes.

fn align_of(&self, type_: &str) -> CProbeResult<usize>

Get the alignment of a C type, in bytes.

Note that this method depends on the compiler having implemented C11 alignment facilities (specifically stdalign.h and alignof).

fn is_defined_macro(&self, token: &str) -> CProbeResult<bool>

Check to see if a macro is defined.

One obvious use for this is to check for macros that are intended to be used with #ifdef, e.g. macros that communicate configuration options originally used to build the library.

A less obvious use is to check whether or not a constant or function has been implemented as a macro, for cases where this is not specified in the API documentation, or differs between library versions. In such cases, bindings may have to omit functionality provided by macros, or else implement such functionality via some special workaround.

fn is_signed(&self, type_: &str) -> CProbeResult<bool>

Check to see if an integer type is signed or unsigned.

Trait Implementations

impl<'a> Debug for Probe<'a>

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Probe<'static>

We provide a default Probe<'static> that runs in an OS-specific temporary directory, uses gcc, and simply runs each test.

Panics

Panics if probe creation fails.

FIXME? Can we do better than the gcc command on Windows?

fn default() -> Self

Returns the "default value" for a type.