Contributing
FIGURE is at v0.8.0; the API can still change before v1.0 (roadmap).
Reporting issues
- Open a ticket on the repository's GitHub Issues page.
- Describe the problem with the steps to reproduce it, the compiler and its version, the platform, and for display problems the SDL video driver and the OpenGL renderer (
glxinfo -Bon Linux).
Before a pull request
fobis build --mode tests-gnu-debug && exe/figure_test_headless # runtime checks and FPE traps
fobis build --mode tests-nvf && exe/figure_test_headless # rm -rf exe first when switching compilers
scripts/fpm.sh test
fobis rule --ex sync # fobos and fpm.toml in syncCI runs the tests with coverage on every push (fobis rule --ex makecoverage-analysis: the tests-gnu-debug mode, gfortran, Linux), and after a push to main the site publishes the coverage report: the lines executed in each source file, with a page per file. The report (docs/guide/coverage-analysis.md, docs/guide/*.gcov.md) is written by FoBiS's gcov analyzer and the badge's percentage (docs/public/coverage.json) by scripts/compute-coverage.sh; they are CI outputs, not in the repository. The same rule run locally writes them into docs/guide.
Rules of the code base
- Two builds, one truth. fobos is the primary build;
fpm.tomlmirrors it. A new program undersrc/examplesorsrc/tests, or a change of the native link libraries, goes into both:scripts/check_sync.py(fobis rule --ex sync) fails otherwise. - Generated raw layer.
src/lib/figure_cimgui*.F90,src/lib/figure_cimplot*.F90,native/figure_glue_generated.cpp,src/tests/figure_test_layout.F90anddocs/guide/raw-bindings.mdare generated: never edit them. After changingscripts/gen_bindings.pyor the pinned cimgui/cimplot, runfobis rule --ex bindingsand commit the result;fobis rule --ex bindings-check(also run by CI) fails on drift. - C ABI only. A cimgui/cimplot function is bound directly only if all its arguments are scalars, pointers or
ImVec2_c(the generator decides); anything taking a larger structure by value goes through the glue. Glue functions areextern "C", return a status, take strings as (pointer, length), and never let a C++ exception escape. - Status codes are defined twice, in
native/figure_native.handsrc/lib/figure_c_native.F90: change both. - Pinned versions. cimgui, cimplot and SDL3 are a matched set: do not bump one alone.
- Tests grow with bindings. Every new widget or plot item gets a headless check driven by synthetic input, as in
src/tests/figure_test_headless.F90.
Fortran style
- One module per file under
src/lib,.F90. !<documentation comments (formal and FORDdocmark), on the entity and on every dummy argument and local.- Kinds from
iso_fortran_envandiso_c_bindingonly (int32,real64,c_int, ...); literals with their kind (1.0_real64). implicit noneeverywhere;intenton every dummy argument.- Joined end statements:
endif,enddo,endfunction,endmodule. - Three-space indentation.
- Never name a local
size(nvfortran 26.9 internal compiler error, see Known issues).
Documentation
The pages live in docs/ (VitePress). Every Fortran snippet shown in the tutorial and the cookbook is included from a program in docs/examples/src, with marker comments: !region NAME ... !endregion NAME for a part shown on its own, !run ID COMMAND for a run whose output is shown (headless programs only).
Every run is a test. A !run must exit with status 0: a --test or --check self-test that fails, or a crash, fails build.sh. An example that ends with an error on purpose (an error stop shown in the pages) is marked !run-exit STATUS ID COMMAND and must exit with exactly that status; its output ends with [exit status STATUS]. build.sh goes through every run, then names each one that failed and its output file (written all the same, to be read) and exits with status 1.
python3 scripts/check_docs.py (CI runs it with --names --media) checks the pages against the code: a new public procedure needs a row in the feature map, a !< doc comment, a sentence on the page that row links to and a call in a program of docs/examples/src. It also checks that every table row has its header's cells, every internal link and anchor exists and the generated pages are current; its docstring lists each check.
bash docs/examples/build.sh # compile every example against src/lib, run the headless ones,
# regenerate docs/examples/snippets and docs/examples/output
cd docs && npm install && npm run docs:buildThe API section documents every module, type and procedure from the source's doc comments, generated by formal into docs/api: npm run docs:api (formal generate --mirror-sources --diagrams --project ford.md --output api), which npm run docs:dev and npm run docs:build run first. The pages are not in the repository: each build writes them from the sources it builds, so a change to the doc comments commits the comments only.
Every picture of the site is recorded headless by FIGURE's CPU renderer from a docs/media/<name>.rec, and CI renders each again and compares it with the committed poster (The documentation's recordings). A change that alters what a recorded program draws records it again in the same commit:
fobis build --mode examples-gnu # figure_hello, figure_mandelbrot (the rest: build.sh)
python3 scripts/docs_media.py --check # which pictures changed: <name>.new.png, <name>.diff.png
python3 scripts/docs_media.py --headless NAME # record one again (its video too), then look at it