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)