Skip to content

Developer‐Oriented

Jump to bottom
Greg Sjaardema edited this page Aug 28, 2025 · 7 revisions

Developer-Oriented Things (Release, Analyzers, ...)

Github CI Process

  • When a commit is pushed or a PR started, mutiple workflows are run by github:
    • The workflows exist in the repository in .github/workflows
    • Main workflows are:
      • Build and run SEACAS tests (gnu, clang, mpi compiler, HDF5 1.10.X and 1.14.X, netCDF 4.9.3, CGNS 4.4.0)
      • Build Using Ubuntu-installed libraries (don't build TPLs, use the ones Ubuntu provides)
      • Clang Format Commit Changes (run clang format on newly committed code and commit the changes)
      • docker-seacas (build seacas and create a docker image)
      • docker-exodus (build exodus and create a docker image)
      • Intel OneAPI build (build using serial and parallel Intel compiler)
      • Python Linting (run flake8 on python code)
      • SEACAS MSYS2 Build (build using Microsoft MSYS2 compiler system)
      • SEACAS no-hdf5-netcdf builds (build a netCDF library that does not provide HDF5 capability. We have some customers using this configuration)
      • SEACAS Spack build (make sure develop branch builds using spack rules)
      • SEACAS Variant builds (lots of options -- debug, threadsafe, sanitizers, gtest-enables, subsets, CATALYST2, KOKKOS, deprecated code disabled, C++20, and others)
      • Static Build
    • The workflows use cached builds of the TPLs to avoid building them each time. Need to update the cache version when changing to a new TPL version or build option so that the new code will be built...
    • There are also "non-workflow" builds that get triggered by a commit or PR:
      • Codacy is a static analyzer.
      • Appveyor is a windows build. Currently builds the non-fortran code.
  • There are also some "hardening" workflows (dependabot.yml) which check what is being used by the other workflows and updates to specific versions when new versions are released.

Release

  • Current versioning used by SEACAS is the date of the release. For example, if releasing the code on August 25, 2025, the release version would be v2025-08-25
  • When the code is released, it is installed in:
    • Sierra repository for the bjam build
    • Sierra spack updated to pull the latest release
    • External spack so release is available via spack (needed also for internal SRN installs)
    • Trilinos
  • The most efficient order to do this is:
    • Update version number in packages/seacas/libraries/ioss/src/Ioss_Version.h
    • snapshot into Sierra. Create a MR and let it run all builds and tests.
    • Once the sierra MR finishes correctly, tag the code and do a release on github.
    • Can also snapshot/PR into Trilinos at the same time or after the Sierra snapshot/MR
    • Once Sierra and Trilinos MR and PR are passing, then tag the source and create a release in github.
    • Now create a PR for external spack seacas package
    • The checksum that you add to the external spack PR should also be added to the Sierra spack build in environments repository and an MR created here.
    • Once the external spack PR is merged, the SRN installs should get triggered to install the latest release.

Snapshot into Sierra

  • Make sure Sierra repository is clean and up-to-date with remote repository.
  • Create a Merge Request branch in the Sierra repository. Something like:
    • git checkout -b SEACAS-snapshot-2023-11-11
  • cd to root of Seacas repository. Make sure repository is clean and up-to-date with github.
  • Do the snapshot.
    • cmake/tribits/snapshot.py --skip-commit --orig-dir={full_path_to_seacas}/packages/seacas/ --dest-dir={full_path_to_sierra}/seacas/
  • cd to {full_path_to_sierra}
  • Sierra also has some other restores needed...
    • git restore seacas/libraries/svdi/vdi_drivers
    • git restore seacas/scripts/grope
    • Some unit testing has switched from doctest.h to Catch2, but Catch2 is not a Sierra TPL, so need to revert those changes:
      • git restore seacas/libraries/ioss/src/doctest.h
      • git restore seacas/libraries/ioss/src/utest
  • The SEACAS build generates the export files needed for windows. This does not happen in sierra
    • Do a git status -uno seacas/libraries/ioss/src and look for any deleted files that end in _export.h
      • If you see any, do a git restore on those.
      • can also use wildcards: git restore seacas/libraries/ioss/src/*_export.h seacas/libraries/ioss/src/*/*_export.h
  • You can now start adding changed files that will be committed in the merge request.

Snapshot into Trilinos

  • Make sure Trilinos repository is clean and up-to-date with remote repository. See the CONTRIBUTING.md Trilinos document for more details. You want to start on the develop branch; not master
  • Create a Merge Request branch in the Trilinos repository. Something like:
    • git checkout -b SEACAS-snapshot-2023-11-11
  • cd to root of Seacas repository. Make sure repository is clean and up-to-date with github.
  • Do the snapshot.
    • cmake/tribits/snapshot.py --skip-commit --orig-dir={full_path_to_seacas}/packages/seacas/ --dest-dir={full_path_to_trilinos}/packages/seacas/
  • cd to {full_path_to_trilinos}
  • Trilinos has an embedded version of the lib::fmt library, so there are some estores needed...
    • git restore packages/seacas/libraries/ioss/src/private_copy_fmt
    • git restore packages/seacas/libraries/suplib_cpp/fmt
    • git restore packages/seacas/libraries/aprepro_lib/fmt
    • git restore packages/seacas/libraries/ioss/cmake/Dependencies.cmake (related to internal vs external lib::fmt)
    • git restore packages/seacas/libraries/suplib_cpp/cmake/Dependencies.cmake (related to internal vs external lib::fmt)
    • git restore packages/seacas/scripts/CMakeLists.txt (turns off testing of exodus.py and exomerge.py in Trilinos)
  • You can now start adding changed files that will be committed in the merge request.
  • When creating the PR on the Trilinos github site, make sure that the branch is set to develop
  • Fill in details in PR template; in particular the teamname.
  • Labels are PA: Data Services, pkg:seacas

Tagging a release or intermediate state

  • Update the version in packages/seacas/libraries/ioss/src/Ioss_Version.h
  • Tagging the current state for use as a release -- begin tag with v:
    • git tag -a -m 'Release the current set of new features' v2024-11-04
  • Push the tag so available in the github repository:
    • git push origin --tags or if you are working with a fork of the repository git push upstream --tags
  • Make the tag available as a release through github:
    • click on Tags near top of source listing on github
    • click on the tag you want to make a release from
    • click on Create release from tag
    • Fill in the information requested and click Publish release
  • See https://git-scm.com/book/en/v2/Git-Basics-Tagging for more details.

SEACAS Documentation web site

  • http://sandialabs.github.io/seacas/
  • Some of this is built using doxygen running over the repository
    • INSERT INSTRUCTIONS
  • The exodus.py and exomerge.py API documentation is built using sphinx
    • INSERT INSTRUCTIONS

TriBITS

The Tribal Build, Integrate, and Test System (TriBITS) is a framework designed to handle large software development projects involving multiple independent development teams and multiple source repositories which is built on top of the open-source CMake set of tools. TriBITS also defines a complete software development, testing, and deployment system supporting processes consistent with modern agile software development best practices.

SEACAS uses TriBITS (primarily because Trilinos uses it and it is easier to not have to have two different CMakeLists.txt files or lots of ifdefs between the two systems.). The TriBITS is embedded into SEACAS at the top level in the cmake subdirectory. The TriBITS version should be updated periodically when Roscoe makes significant changes...

I have a checked out version of the TriBITS repository and update it and then:

  • cd to top-level directory of the seacas repository
  • cmake/tribits/snapshot_tribits.py --skip-commit --orig-dir=/Users/gdsjaar/src/TriBITS/tribits/ --dest-dir=/Users/gdsjaar/src/seacas/cmake/tribits/
  • look at the changes between the current SEACAS TriBITS and the new version. SEACAS uses its own versions of some of the FindTPLYYYY.cmake commands, so there will probably be differences, but look at the differences and see if they should be included (not sure how to best describe that...). (I should work with Roscoe and see if he will accept our changes...)
  • commit desired changes to SEACAS repository.

Zoltan

SEACAS repository contains a version of zoltan in its repository. It may also need to be updated periodically; however, most development currently is in Zoltan2 and not much changes in Zoltan.

Miscellaneous

  • Codespell: codespell -I codespell-ignore.txt --skip="*.eps,*.pdf,*.png,*.cgns,*.g"
    • Checks the spelling of comments and variables in the code base. There will be lots of false positives, primarily with the Fortran variable names. The codespell-ignore.txt file can be used to add frequent false positives to reduce the clutter.
    • I typically ran about every month or two.
  • Coverity: git checkout coverity; git merge master; git push; git checkout master
    • Good static analyzer, although like all of them there are some false positives.
    • I typically ran about once every month or two.
  • I sometimes run clang-tidy on the source code.
  • Changing build of aprepro_lib to use reflex instead of flex: Use reflex instead of flex in aprepro_lib
    • Not sure if this is beneficial or not or if it will even work.
Clone this wiki locally