structure overview

Repository layout

• contrib holds third party libraries required by the project. These include things like Catch2, Clara, and a locally-built BLAS/Lapack if requested by the user at configure time.
• src holds all of the component file triads, as well as the main.cpp that contains main() for the ASGarD binary.
• testing contains support files for code testing, including the data files holding golden values for comparison, the matlab scripts to generate the golden values, and any global auxiliary functions needed for testing.

Component-based structure

Having components makes adding new code to the CMake system fairly straightforward. There is a list of all components defined via set (components ..., which among other things allows the source files to be added and the tests to be built, all automatically.

To add a new component:

1. ensure that the component named "foo" consists of exactly three files in the top-level of the src/ directory named foo.hpp, foo.cpp, and foo_tests.cpp.
2. add the component name to the component list, in alphabetical order.
3. add a target_link_libraries entry for the component (again, alphabetically), defining its private/public/interface relations to other components.
4. if the component is directly used by the main.cpp file, then add the component name to the link list defined by set (main_app_link_deps ...)

component.hpp header files

The interface of the component, included exported template specializations via extern template.

• first line is #pragma once

• The component header should only #include what is needed to define the interface. The implementation (.cpp) file will take care of its own #includes.

• any necessary extern template declarations come at the very bottom of the header.

component.cpp files

The internal implementation of the component, including any explicitly instantiated templates that are needed.

• first line is always the #include for the component's own header, followed by a blank line (so that clang-format does not reorder into the list of the remaining #includes)

• remaining #includes are listed together with no blank lines, and clang-format will reorder them as necessary.

• any necessary explicit template instantiations come at the very bottom of the file.

component_tests.cpp files

Holds all (and only) unit tests of the component contained in Catch TEST_CASE(){} blocks.

Structural overview