Browse documentation

Tutorials

Build a library and consumer

Create reusable Rust, test it through an application and change one result.

Create a reusable library and consumer, then change its revision value and update the test. Build the runtime first if it is not on your PATH.

The runtime binary needs a recorded source identity. A clean Git build records its commit. Non-colocated JJ or archive builds need EFFECTFUL_SOURCE_COMMIT set to the exact independently verified source commit. An unknown identity refuses this scaffold; do not label modified source with an unrelated commit.

1. Create and test

Use an absent or empty pricing directory:

effectful new ./pricing --kind library --name pricing
effectful verify ./pricing
effectful test ./pricing

The generated tests expect 6 × 7 = 42 and revision 1. These verification and test commands do not invoke Cargo, rustc or dependency downloads for each edit.

2. Read the project

Path under pricing/ Purpose
library.toml Library, consumers and runtime source identity
packages/pricing/src/lib.rs Reusable functions
consumers/example/src/lib.rs Checked entries calling the library
consumers/example/tests/ Consumer cases
oracle/ Separate native Rust comparison project

The library contains:

pub fn scale(value: i64, factor: i64) -> i64 {
    value * factor
}

The consumer exposes:

use effectful::effectful;

#[effectful]
pub fn scaled(value: i64, factor: i64) -> i64 {
    pricing::scale(value, factor)
}

The library owns no listener or deployment. The consumer supplies its execution context. Both use the crate-based compilation path; the Rust profile reference explains which constructs are supported.

3. Change the revision

In pricing/packages/pricing/src/lib.rs, change revision() from 1 to 2, keeping its signature.

effectful verify ./pricing
effectful test ./pricing

Verification can pass while the revision test fails. The source is valid, but its result differs from the expectation.

4. Accept the intended result

Confirm 2 is the intended result. Change pricing/consumers/example/tests/revision.json to expect ["s64", "2"], then rerun verification and tests.

The native oracle separately expects 1. If using it, update its reviewed expectation and run its tests with the toolchain in the generated README. The oracle has its own Cargo build.

You have changed reusable code and checked the application that consumes it. Continue with the watch loop or code and evidence.

Search concepts, guides and reference.