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)
| Step | Sample | Why |
|---|---|---|
| 1 | SBE Feature Tour | Golden path. Full feature map: stages, EncodedLength, checked constructors + verify, Display, DTO with DomainVarData::Strings, all three conversion styles |
| 2a | L3 Order Book | Nested/ragged books; with_domain_type only; build-dep only (#[path] into src/generated/) |
| 2b | Exchange Example | Multi-schema; with_conversion only; IPC + app TryFromSbe |
| 3 | Codegen as Library | Generator as a library (no build.rs) |
| Later | Cluster Tutorial | Connect, offer, poll, keep-alive, close |
| Later | Cluster HA Orderbook | Claim-based Cluster publishing + HA-shaped book |
| Later | Cluster RFQ | RFQ / 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
| Sample | Config | Decode / encode surface |
|---|---|---|
| L3 Order Book | with_domain_type only | dec.price()? → Decimal; enc.price(d)? |
| Exchange Example | with_conversion only | dec.price_as::<T>()?; enc.price_from(&t)? (+ app TryFromSbe) |
| SBE Feature Tour | All three (different selectors) | bool/timestamp concrete (Generated); Decimal generic (demo_conversion_only); ManualDecimal concrete + app impl (demo_domain_type_manual_impl) |
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
Resultand?. - Delete a sample when it no longer exercises a distinct repository behavior.