Skip to content

DevOps

Jump to bottom
Bruno edited this page May 6, 2025 · 17 revisions

DevOps

Wiki

  • Tutorials, images etc... are stored in the Wiki (to avoid storing large binary files in the repository). The Wiki is a separate repository (geogram.wiki).

Workflows, YAML files

Syntax for YAML files is very tricky, tabs versus spaces, like in Makefiles !

  • use YAML Lint online before pushing workflows.
  • In emacs, <esc> <x> whitespace-mode to display spaces and tabs differently. Emacs create a tab by default on each newline (there is probably a YAML mode for emacs that avoid this but I did not find it...)
  • In emacs, to avoid automatic tabs when creating new lines (which breaks YAML files most of the time), add the following line (setq-default indent-tabs-mode nil) to your .emacs

Geogram uses the following workflows:

  • Build: builds geogram on Linux,Windows,MacOS on each push and launches test suite. Test results are published here
  • Nightly: builds geogram on Linux,Windows,MacOS each night and launches test suite under Valgrind. Test results are published here. They are pushed to another repository geogram.CI to the gh-pages pages, using peaceiris/action-gh-pages. To do that, a SSH ACTION_DEPLOY_KEY is used, as explained here. Publishing CI results in a separate repo prevents geogram repo from growing too much (CI test results take some space !). Note that the continuous action wipes the history, but the previous config (with everything in geogram's gh-pages) made it impossible to keep generated doc and test results while wiping test result history.
  • Doxygen: (manually triggered) generates the programmer's reference manual and publishes it here
  • Release: (manually triggered) generates Geogram releases (deb, rpm, Geogram PSMs) and publishes them to the latest release.
  • Emscripten: (manually triggered) generates Geogram on-line demos and publishes them to geogram.run (using a SSH ACTION_DEPLOY_KEY_RUN).

Doxygen documentation

  • The Doxygen documentation is hosted by GitHub Pages.
  • GitHub Pages are configured in the "Pages' category of project settings. The Source is the "gh-pages" branch, root directory.
  • The pages are generated using a manually triggered action (workflow_dispatch). To push the generated HTML pages to the gh-pages, it uses JamesIves/github-pages-deploy-action@v4, that has an option to clear the history (which we want to do, no need to keep history of generated stuff).
  • Test results are also pushed to gh-pages, but using peaceiris/actions-gh-pages@v3 that works under Linux/Mac/Windows (JamesIves only works under Linux).

Tests

Non-regression tests are based on RobotFramework and some extensions that were written by Thierry Valentin (RIP my friend, miss you...), initially for Jenkins (ported them to a github action). Latest test results are posted here.

To run the tests manually/locally:

  1. build geogram
$ cd geogram
$ ./configure.sh
$ cd build/xxxx
$ make -j 4
  1. install robotframework
$ pip3 install robotframework
  1. get test data
$ cd geogram/tests
$ git clone https://github.com/BrunoLevy/geogram.data.git .)
  1. run the tests
$ ./build/xxxx/tests/runpybot.sh --include=TESTCATEGORY tests/

where TESTCATEGORY is one of smoke,daily_valgrind, weekly_valgrind (see Tags in .robot files)

Optionally, memory checking, bound checking, coverage analysis can be selected using additional flags passed to runpybot.sh:

  • --with-valgrind
  • --with-callgrind
  • --with-gcov

The same --with-xxx=1 option needs to be passed before to configure.sh. Note the =1 (without it it does not work, configure.sh tests for its presence).

To use ASan (address sanitizer):

./configure.sh Linux64-gcc-dynamic --with-asan=1
(cd build/Linux64-gcc-dynamic-Debug; make -j 4)
./build/Linux64-gcc-dynamic-Release/tests/runpybot.sh --with-asan --include=smoke tests/

Things to do when creating a new release

  1. check that the PSMs still compile and work
  2. in CMakeLists.txt, set(VORPALINE_VERSION_RC FALSE), commit, push
  3. check continuous integration results
  4. create the release (see howto), Choose a tag dropdown, select Create a new tag. Make sure the release was set as the latest release.
  5. run release workflow (generates precompiled Linux packages and PSMs)
  6. run doxygen workflow (generates programmer's reference manual here)
  7. run emscripten workflow (generates online demo)
  8. For each PSM, update sources, and create new version
  9. Graphite:
 $ git clone https://github.com/BrunoLevy/GraphiteThree.git
 $ cd geogram
 $ git pull origin main
 $ cd ..
 $ git add geogram
 $ git commit -a
 $ git push
  1. in CMakeLists.txt, increment version number and set(VORPALINE_VERSION_RC TRUE)
Clone this wiki locally