Crate seacan 

A library for interacting with cargo to build things.

The main entrypoints are bin::Compiler and test::Compiler.

Binaries and examples

Building binaries and examples is relatively simple, although we do use regexes to give you nicer errors in a few cases.

use seacan::bin;
let binary_artifact = bin::Compiler::bin("binary_name").release(true).compile()?;
let example_artifact = bin::Compiler::example("example_name").compile()?;

Example return value:

Ok(ExecutableArtifact {
    package_id: PackageId { .. },
    target: Target { .. },
    profile: ArtifactProfile { .. },
    features: [],
    filenames: [ .. ],
    executable: "/path/to/crate/.target/debug/example_name",
    fresh: true,
})

Tests

Building tests is a bit more complicated. We expose all of Cargo’s api for specifying which test artifacts to build. After we build each artifact we ask it for a list of all the test or benchmark functions in it that match the spec you provided.

use seacan::test;
let mut artifacts = test::Compiler::new(
    test::NameSpec::exact("test_frobs_baz"),
    test::TypeSpec::integration("frob_*"),
).compile()?;

Example return value:

Ok(vec![
    Artifact {
        artifact: ExecutableArtifact {
            target: Target {
                name: "frob_a",
                ..
            },
            ...
        },
        tests: vec![
            TestFn {
                name: "test_frobs_baz",
                test_type: TestType::Test,
            },
        ],
    },
    Artifact {
        artifact: ExecutableArtifact {
            target: Target {
                name: "frob_b",
                ..
            },
            ...
        },
        tests: vec![],
    }
])

Only the default test runner (libtest) is supported.

Why the name?

A Sea Can is another word for a shipping container. Shipping containers were invented to provide a standard interface around handling cargo.

Modules

bin

Compile bins and examples (i.e. what you can cargo run)

test

Compile tests (unit tests in lib, doctests, integration tests, and unit tests in bins and examples)

Structs

ArtifactProfile

Profile settings used to determine which compiler flags to use for a target.

CompilerMessage

Message left by the compiler

Diagnostic

A diagnostic message generated by rustc

ExecutableArtifact

Like cargo_metadata::Artifact, but always has an executable

FeatureSpec

Describe a configuration of feature flags

PackageId

An “opaque” identifier for a package. It is possible to inspect the repr field, if the need arises, but its precise format is an implementation detail and is subject to change.

Target

A single target (lib, bin, example, …) provided by a crate

Utf8Path

A slice of a UTF-8 path (akin to str).

Utf8PathBuf

An owned, mutable UTF-8 path (akin to String).

Enums

BuildError

Failed to build

DiagnosticLevel

The diagnostic level

PackageSpec

Describe a package (i.e. the --package flag)