Teaching Path

Standalone crates that exercise repository APIs. They are excluded from the workspace, set publish = false, and are not production reference implementations — they move with experimental APIs on purpose.

Start here (product teaching path)

StepSampleWhy
1SBE Feature TourGolden path. Full feature map: stages, EncodedLength, checked constructors + verify, Display, DTO with DomainVarData::Strings, both conversion styles
2aL3 Order BookNested/ragged books; with_domain_type only; build-dep only (plain include!)
2bExchange ExampleMulti-schema; with_conversion only; IPC + app TryFromSbe
3Codegen as LibraryGenerator as a library (no build.rs)
LaterCluster TutorialConnect, offer, poll, keep-alive, close
LaterCluster HA OrderbookClaim-based Cluster publishing + HA-shaped book
LaterCluster RFQRFQ / auction codecs over Cluster
# 1 — always start here
cargo run  --manifest-path samples/sbe-feature-tour/Cargo.toml

# 2 — pick the conversion style you want in product code
cargo run  --manifest-path samples/l3-book/Cargo.toml
cargo test --manifest-path samples/exchange-example/Cargo.toml

Rule of thumb: one conversion style per schema type (with_domain_type or with_conversion, not both for the same selector).

Conversion: which sample uses what

SampleConfigDecode / encode surface
L3 Order Bookwith_domain_type onlydec.try_price()? → Decimal; enc.try_price(d)?
Exchange Examplewith_conversion onlydec.price_as::<T>()?; enc.price_from(&t)? (+ app TryFromSbe)
SBE Feature TourBoth (different selectors)bool/timestamp concrete; Decimal generic (demo_conversion_only)

Rule: one style per selector. with_domain_type already enables conversion; do not stack with_conversion on the same selector.

#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // A — generic converter: one wire type, many app types
    let _cfg =
        GenerationConfig::new("msgs").with_conversion(ConversionSelector::named_type("Decimal"));
}
#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // B — concrete mapping: one Rust type per wire type (already enables conversion)
    let _cfg = GenerationConfig::new("msgs").with_domain_type(
        ConversionSelector::named_type("Decimal"),
        "rust_decimal::Decimal",
    );
}

Rules

  • Keep every sample outside the workspace and unpublished.
  • Do not expose sample-only abstractions as product APIs.
  • Size SBE buffers from generated encoded-length APIs (prefer stack when const).
  • Propagate fallible operations with Result and ?.
  • Delete a sample when it no longer exercises a distinct repository behavior.