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. The seventh track leaves quad for a lab's libraries, used by name through package indexes.
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, CI with machine-readable output, fpm and Makefile export, quad as a package found and used by name, one fobos for many machines, several programs and a pkg-config library |
| 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 |
| 7. Packages and indexes | intermediate | a lab's libraries as packages: an index of its own, finding and adding by name, versions, installing for a compiler, trust without a central server, fpm and CMake packages, fpm projects |
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 |
| 8. quad as a package | fobis publish, index, search, info, add, transitive = true, pkg install, audit |
| 9. One fobos, many machines | [varset:NAME], --varset, cflags.gnu, [include], ?fobos.local |
| 10. Several programs and a library for others | [target.NAME], --target-filter, pkgconfig = True, --compile-commands |
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 |
7. Packages and indexes
This track leaves quad for a lab's libraries and a project, solver, that uses them.
| Chapter | You learn |
|---|---|
| 1. An index of your own | seed indexes, fobis index build, index check, index add, follows |
| 2. Find, add and remove | fobis search (--module, --build), info, add (name, INDEX:NAME, --module, URL), remove |
| 3. Versions | tags and ranges, fetch --update, add --semver --force, transitive = true, minimal version selection |
| 4. Install for your compiler | fobis pkg install, toolchain keys, pkg path --pkgconfig, pkg upgrade, pkg uninstall |
| 5. Trust without a central server | mirrors, the lock's hashes, fortran-advisories.toml, fobis audit, --witness |
| 6. Packages built with fpm and CMake | fobis publish --index, recipes, fpm and CMake packages in a FoBiS project |
| 7. An fpm project | search --build fpm, add and remove in fpm.toml |
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:
bash
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.