Working in the flodl Source Checkout

The flodl repo’s own fdl.yml ships the concrete command set used to develop floDl itself. These are examples of the manifest system from the previous section, not built-in commands.

Development loop

fdl check              # type-check without building
fdl build              # debug build
fdl clippy             # lint (tests + workspace + ddp-bench)
fdl test               # all CPU tests
fdl test-release       # tests in release mode
fdl test-live          # tests needing network / external resources (see below)
fdl doc                # rustdoc, strict (-D warnings)

Live tests

fdl test-live runs integration tests that depend on network access or external resources (Hugging Face Hub downloads, cached safetensors checkpoints, etc.). The canonical pattern:

flodl-hf uses this for its PyTorch parity tests (bert_parity_vs_pytorch_live, bert_tokenizer_matches_parity_fixture_live, and the RoBERTa / DistilBERT / ALBERT / XLM-RoBERTa siblings), each asserting max_abs_diff <= 1e-5 on logits or hidden state against a pinned HF Python reference. Weights cache under .hf-cache/ via HF_HOME=/workspace/.hf-cache in the Docker service.

Any project (not just flodl itself) can adopt the _live suffix + #[ignore] convention; fdl test-live picks up any test matching the pattern within its cargo test scope.

CUDA / GPU testing

fdl cuda-build            # build with CUDA feature
fdl cuda-clippy           # lint with CUDA feature
fdl cuda-test             # parallel CUDA tests (excludes NCCL / Graph)
fdl cuda-test-nccl        # NCCL/DDP tests only (isolated processes)
fdl cuda-test-graph       # CUDA Graph tests (exclusive GPU, single-threaded)
fdl cuda-test-serial      # remaining serial tests
fdl cuda-test-all         # full suite: parallel + NCCL isolated + serial

Benchmarks

bench is a path:-kind sub-command rooted at ./benchmarks/. Presets are defined in benchmarks/fdl.yml; options come from benchmarks/run.sh --fdl-schema and are auto-cached on first use.

fdl bench                              # quick single-round run (CUDA)
fdl bench publish                      # publication run (10 interleaved rounds, 15s warmup)
fdl bench cpu                          # CPU-only quick run
fdl bench cpu-publish                  # CPU-only publication run

fdl bench --rounds 20 --output ...     # ad-hoc flags (listed by `fdl bench -h`)

DDP validation suite

ddp-bench/ is a path:-kind sub-command with its own fdl.yml and preset commands. Example presets (from ddp-bench/fdl.yml):

fdl ddp-bench quick                   # fast smoke test (1 epoch, linear model)
fdl ddp-bench validate                # full DDP validation matrix
fdl ddp-bench validate --report out   # validation + write report to out/
fdl ddp-bench --help                  # list all presets + options

HuggingFace (flodl-hf)

flodl-hf/ is another path:-kind sub-command with its own fdl.yml, enabled through the convention entry flodl-hf: in the root manifest. Same shape as ddp-bench/ and benchmarks/: the root declares the sub-command, the child fdl.yml defines its tasks.

fdl flodl-hf                          # list sub-commands
fdl flodl-hf convert <repo_id>        # convert pytorch_model.bin -> model.safetensors

# Runnable examples (fourteen demos across the six BERT-family architectures)
fdl flodl-hf example                  # list example names
fdl flodl-hf example auto-classify    # family-agnostic via AutoModel
fdl flodl-hf example bert-embed       # + bert-classify / bert-ner / bert-qa
fdl flodl-hf example roberta-embed    # + roberta-classify / -ner / -qa
fdl flodl-hf example distilbert-embed # + distilbert-classify / -ner / -qa
fdl flodl-hf example distilbert-finetune  # fine-tune walkthrough (loss curve + export recipe)

# Round-trip export to the HF ecosystem (any supported family/head)
fdl flodl-hf export --hub bert-base-uncased --out /tmp/bert-export
fdl flodl-hf export --checkpoint ./my.fdl  --out /tmp/my-export
fdl flodl-hf verify-export /tmp/bert-export             # auto-detects Hub source from stamped config
fdl flodl-hf verify-export /tmp/my-export --no-hub-source

# 30-cell pre-release gate (six families x base/seqcls/tokcls/qa/mlm)
fdl flodl-hf verify-matrix
fdl flodl-hf verify-matrix -- --families bert,albert --heads base,seqcls

# Parity-fixture regeneration (contributors; 29 per-head commands plus `parity all`)
fdl flodl-hf parity                       # list parity targets
fdl flodl-hf parity all                   # run every fixture in sequence (PASS/FAIL grid)
fdl flodl-hf parity bert                  # bert-base-uncased backbone fixture
fdl flodl-hf parity bert-seqcls           # per-head fixtures
fdl flodl-hf parity albert-mlm            # ALBERT family masked-LM fixture
fdl flodl-hf parity deberta-v2-qa         # DeBERTa-v2 QA fixture
# (29 in total: bert/roberta/distilbert/albert/xlm-roberta + seqcls/tokencls/qa/mlm
#  per family, plus the bare-backbone targets; deberta-v2 has no -mlm fixture
#  due to a documented MLM gap in flodl-hf/tests/deberta_v2_parity.rs)

hub, checkpoint, and parity modes all run in a dedicated hf-parity Docker service (python:3.12-slim + torch CPU wheel + transformers) declared in docker-compose.yml. HF_HOME=/workspace/.hf-cache keeps weights and tokenizers cached between runs (gitignored). The verify-export and verify-matrix runners route Python through the same service automatically.

See the HuggingFace Integration tutorial for end-user usage of the crate itself (API walkthroughs, install profiles, AutoModel dispatch, fine-tune + export round-trip recipe, the 30-cell parity matrix).

Interactive shells

fdl shell         # dev container (CPU)
fdl cuda-shell    # CUDA container

Re-building the CLI

After editing flodl-cli/:

fdl self-build    # rebuild fdl and replace the installed binary

This uses the currently-running fdl to rebuild itself, and swaps the new binary into place atomically.

Architecture notes

The CLI is built as a pure Rust binary with zero external crate dependencies beyond serde. GPU detection uses nvidia-smi, downloads use curl/wget, and zip extraction uses unzip (or PowerShell on Windows). This means:

Pre-compiled binaries are published to GitHub Releases on every tagged release. The fdl shell script is a thin bootstrap that downloads the right binary, falling back to cargo build if no binary is available for your platform.

← Previous The fdl.yml Manifest