Skip to content

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 -B on Linux).

Before a pull request ​

bash
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 sync

CI 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.toml mirrors it. A new program under src/examples or src/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.F90 and docs/guide/raw-bindings.md are generated: never edit them. After changing scripts/gen_bindings.py or the pinned cimgui/cimplot, run fobis rule --ex bindings and 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 are extern "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.h and src/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 FORD docmark), on the entity and on every dummy argument and local.
  • Kinds from iso_fortran_env and iso_c_binding only (int32, real64, c_int, ...); literals with their kind (1.0_real64).
  • implicit none everywhere; intent on 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
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:build

The 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:

bash
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

Released under the MIT licence.