Tutorials
The tutorials follow one project, quad: a small library of quadrature rules (the trapezoidal and Simpson rules) and a program that uses it. It starts as three source files and no build script, and grows track by track: modes, a library, tests, dependencies, then verified numerical results, a linted and reviewed code, and an AI assistant that works under the same checks.
Each track is a sequence of chapters, from the simplest to the most demanding; a track assumes the previous ones. Every command output shown is the real one: the pages include what the commands printed when docs/scripts/docs_examples.py ran them, and the CI reruns them and fails when an output changes.
Tracks
| Track | Level | You learn |
|---|---|---|
| 1. First steps | basic | build without configuration, a fobos with modes, a library, tests and coverage, dependencies |
| 2. Growing a project | intermediate | templates and variables, build profiles and feature flags, external libraries (MPI, OpenMP), rules, the cache, CI with machine-readable output, fpm and Makefile export |
| 3. Many repositories | intermediate | an ecosystem of projects: dashboard, commands across all of them, checking the projects downstream, the release train |
| 4. Code quality | advanced | the linter, baselines and fixes, reviewing a change, querying the code, verified modernisation, C and Python bindings |
| 5. Verified numerics | advanced | cases and references, shadow builds and the compiler matrix, error and uncertainty assessment, differential runs, benchmarks, the gate, profiling, clusters |
| 6. AI-assisted development | expert | a local model, explained failures, questions answered from the sources, generated tests, merge conflicts, an agent working under the gate |
1. First steps
| Chapter | You learn |
|---|---|
| 1. A first build | fobis build with no configuration: source discovery, dependency order, incremental rebuilds |
| 2. A fobos file | modes, --mode, build directories, fobis run |
| 3. A library | static and shared libraries, fobis install, linking an installed library |
| 4. Tests | fobis test, doctests, coverage |
| 5. Dependencies | [dependencies], fobis fetch, the lock file |
flowchart LR A[1 first build] --> B[2 fobos] --> C[3 library] --> D[4 tests] --> E[5 dependencies]
2. Growing a project
| Chapter | You learn |
|---|---|
| 1. Templates and variables | template, $variables, fobis introspect |
| 2. Build profiles and features | build_profile, [features], cflags_heritage |
| 3. OpenMP and MPI | openmp = True, mpi = True |
| 4. A project that depends on quad | dependon, interface changes followed |
| 5. Rules | [rule-NAME], pre_build/post_build, intrinsic rules, --jobs |
| 6. Continuous integration | fobis check, --json, a CI workflow |
| 7. Other build systems | fobis fpm export, --makefile |
3. Many repositories
| Chapter | You learn |
|---|---|
| 1. An ecosystem | the registry, discover, add, graph |
| 2. The dashboard | releases due, CI, drift, stale pins; JSON and HTML |
| 3. Acting on every project | exec, fetch, in release order |
| 4. Before releasing | check (dependents against a working copy), impact |
| 5. Shared boilerplate | scaffold status and sync |
| 6. The release train | release: plan, pre-flight, release in order |
4. Code quality
| Chapter | You learn |
|---|---|
| 1. The linter | fobis lint, --explain, --select, formats for CI |
| 2. Suppressions, baselines and fixes | inline suppressions, --diff/--fix, the baseline |
| 3. Reviewing a change | fobis review, findings on the changed lines only |
| 4. Querying the code | fobis query: callers, writers, regions, MPI calls |
| 5. Verified modernisation | fobis modernize: fixes kept only when tests pass |
| 6. C and Python bindings | fobis bindings, a shared library, ctypes |
| 7. Instructions for agents | fobis agents-md |
5. Verified numerics
| Chapter | You learn |
|---|---|
| 1. Cases and quantities | [case:NAME], quantities, fobis case run, provenance |
| 2. References | fobis verify, --update, a failure explained by its provenance |
| 3. Defects only some builds see | --shadow checks/sanitize/strict, fobis matrix |
| 4. How accurate is the result? | fobis assess: refinement, precision and rounding families, budgets |
| 5. Is a refactoring harmless? | fobis diff-run REF, --assess, tolerances |
| 6. Is it faster? | fobis bench, --compare, --record |
| 7. One command for all of it | fobis gate, [gate] |
| 8. Where the time goes | fobis profile: gprof, callgrind |
| 9. On a cluster | --runner slurm, the login-node guard, nsys on a GPU |
6. AI-assisted development
| Chapter | You learn |
|---|---|
| 1. A local model | fobis llm: runtime, models, doctor |
| 2. Build failures, explained | build --explain: diagnoses from facts, cited answers |
| 3. Crashes, located | run --explain, trusted locations |
| 4. Questions about the code | fobis ask, what a citation guarantees |
| 5. Generated tests | fobis testgen: skeletons, accepted tests |
| 6. A second reader for a change | review --deep |
| 7. Commit messages | fobis commit, --show-facts |
| 8. Merge conflicts | fobis merge-assist, compiled proposals |
| 9. An agent under the gate | fobis mcp, an agent calling the gate |
Running the examples yourself
The project of each chapter is in docs/examples/tutorial: the files/ of a chapter are what it adds or changes, its session.sh the commands it runs. To rerun them all:
python docs/scripts/docs_examples.py # regenerates docs/examples/output
python docs/scripts/docs_examples.py --check # compares with the committed outputsThe outputs were produced with gfortran 13, the compiler of the CI; DOCS_FC=gfortran-14 runs them with another. Timings, profiles and the cluster chapter depend on the machine: they were recorded once (files named *.measured.txt) and the CI checks only that their commands are unchanged.