Issue/336 transport iterfaces (#343)

First draft of transport interfaces

Added:
- `transport::ISession`
- `transport::IMessage[Rx|Ts]Session`
- `transport::I[Request|Response][Rx|Ts]Session`

Also:
- add "std: [14, 17, 20]" to the build matrix
- add hash tag triggering by #verification #docs tags
- strip repo absolute path prefix from doxygen file paths

---------

Co-authored-by: Sergei Shirokov <[email protected]>

.clang-format

@@ -28,7 +28,6 @@ BraceWrapping:
     AfterStruct: true
     AfterClass: true
     AfterControlStatement: true
-    AfterEnum: true
     AfterFunction: true
     AfterUnion: true
     AfterNamespace: true

.github/workflows/tests.yml

@@ -1,36 +1,25 @@
 name: "libcyphal_test"
 
 on:
-  push:
-    branches:
-      - main
-      - 'issue/*'
-      # todo: temp - remove this later!
-      - 'sshirokov/CI_*'
+  push:  # Further filtering is done in the jobs.
   pull_request:
     branches:
       - main
       - 'issue/*'
-      # todo: temp - remove this later!
-      - 'sshirokov/CI_*'
 
-# To test use https://github.com/nektos/act and specify the event as "act"
-# For example:
-#
-#           act act -j verification --bind --reuse
-#
-# That command will run the verification job locally and bind the current directory
-# into the container (You'll probably need to delete any existing build directory
-# before running act).
 jobs:
   warmup:
+    if: >
+      contains(github.event.head_commit.message, '#verification') ||
+      contains(github.event.head_commit.message, '#docs') ||
+      contains(github.ref, '/main') ||
+      contains(github.ref, '/issue/') ||
+      (github.event_name == 'pull_request')
     runs-on: ubuntu-latest
     container: ghcr.io/opencyphal/toolshed:ts22.4.3
     steps:
       - uses: actions/checkout@v4
-        if: ${{ github.event_name != 'act' }}
       - name: Cache ext modules
-        if: ${{ github.event_name != 'act' }}
         id: libcyphal-ext
         uses: actions/cache@v4
         env:
@@ -52,18 +41,26 @@ jobs:
           --build-flavor Debug
           clean-configure
   verification:
+    if: >
+      contains(github.event.head_commit.message, '#verification') ||
+      contains(github.ref, '/main') ||
+      contains(github.ref, '/issue/') ||
+      (github.event_name == 'pull_request')
     runs-on: ubuntu-latest
     container: ghcr.io/opencyphal/toolshed:ts22.4.3
     needs: [warmup]
     strategy:
       matrix:
-        flavor: [Release, Debug]
+        build_flavor: [Release, Debug]
+        std: [14, 17, 20]
         toolchain: [gcc, clang]
+        include:
+          - build_flavor: Coverage
+            std: 14
+            toolchain: gcc
     steps:
     - uses: actions/checkout@v4
-      if: ${{ github.event_name != 'act' }}
     - name: Cache ext modules
-      if: ${{ github.event_name != 'act' }}
       id: libcyphal-ext
       uses: actions/cache@v4
       env:
@@ -74,24 +71,43 @@ jobs:
     - name: get nunavut
       run: >
         pip install nunavut
-    - name: release
+    - name: run tests
+      env:
+        GTEST_COLOR: yes
       run: >
         ./build-tools/bin/verify.py
         --verbose
         --asserts
-        --cpp-standard 14
-        --build-flavor ${{ matrix.flavor }}
+        --cpp-standard ${{ matrix.std }}
+        --build-flavor ${{ matrix.build_flavor }}
         --toolchain ${{ matrix.toolchain }}
-        clean-release
+        test
+    - name: debug output
+      if: ${{ runner.debug == '1' }}
+      run: ls -lAhR build/
+    - name: upload-artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ matrix.build_flavor }}-${{ matrix.std }}-${{ matrix.toolchain }}
+        path: |
+          build/compile_commands.json
+          build/*/**/coverage.xml
+          build/*/**/*-sonarqube.xml
+          build/*/**/gcovr_html/*.*
+        if-no-files-found: error
+
   docs:
+    if: >
+      contains(github.event.head_commit.message, '#docs') ||
+      contains(github.ref, '/main') ||
+      contains(github.ref, '/issue/') ||
+      (github.event_name == 'pull_request')
     runs-on: ubuntu-latest
     container: ghcr.io/opencyphal/toolshed:ts22.4.3
     needs: [warmup]
     steps:
     - uses: actions/checkout@v4
-      if: ${{ github.event_name != 'act' }}
     - name: Cache ext modules
-      if: ${{ github.event_name != 'act' }}
       id: libcyphal-ext
       uses: actions/cache@v4
       env:
@@ -111,15 +127,15 @@ jobs:
         --build-flavor Debug
         build-docs
     - name: Setup Pages
-      if: ${{ github.event_name != 'pull_request' && github.event_name != 'act' }}
+      if: ${{ github.event_name != 'pull_request' }}
       uses: actions/configure-pages@v5
     - name: Upload docs
-      if: ${{ github.event_name != 'pull_request' && github.event_name != 'act' }}
+      if: ${{ github.event_name != 'pull_request' }}
       uses: actions/upload-pages-artifact@v3
       with:
         path: "build/docs/html/"
     - name: upload-pr-docs
-      if: ${{ github.event_name == 'pull_request' && github.event_name != 'act' }}
+      if: ${{ github.event_name == 'pull_request' }}
       uses: actions/upload-artifact@v4
       with:
         name: pr-docs

CONTRIBUTING.md

@@ -193,6 +193,28 @@ Reviewers, please check the following items when reviewing a pull-request:
     * Are the tests maintainable?
     * Is the code in the right namespace/class/function?
 
+### Format the sources
+
+Clang-Format may format the sources differently depending on the version used.
+To ensure that the formatting matches the expectations of the CI suite,
+invoke Clang-Format of the correct version from the container (be sure to use the correct image tag):
+
+```
+docker run --rm -v ${PWD}:/repo ghcr.io/opencyphal/toolshed:ts22.4.3 ./build-tools/bin/verify.py build-danger-danger-repo-clang-format-in-place
+```
+
+### `issue/*` and hashtag-based CI triggering
+
+Normally, the CI will only run on pull requests (PR), releases, and perhaps some other special occasions on `main` branch.
+Often, however, you will want to run it on your branch before proposing the changes to ensure all checks are
+green and test coverage is adequate - to do that:
+- either target your PR to any `issue/NN_LABEL` branch, where `NN` is the issue number and `LABEL` is a small title giving context (like `issue/83_any`)
+- or add a hashtag with the name of the workflow you need to run to the head commit;
+for example, making a commit with a message like `Add feature such and such #verification #docs #sonar`
+will force the CI to execute jobs named `verification`, `docs`, and `sonar`.
+
+Note that if the job you requested is dependent on other jobs that are not triggered, it will not run; 
+for example, if `sonar` requires `docs`, pushing a commit with `#sonar` alone will not make it run.
 
 ## CAN bus Physical Layer Notes
 

cmake/modules/Findcetl.cmake

@@ -6,7 +6,7 @@
 
 include(FetchContent)
 set(cetl_GIT_REPOSITORY "https://github.com/OpenCyphal/cetl.git")
-set(cetl_GIT_TAG "c1c2ae21ed446a7b25394d0067f3f4bec43a881b")
+set(cetl_GIT_TAG "884f3b38e7857daa790ed6ba7031f7037fb81a2e")
 
 FetchContent_Declare(
     cetl

docs/CMakeLists.txt

@@ -64,6 +64,7 @@ function (create_docs_target ARG_DOCS_DOXY_ROOT
     set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
     set(DOXYGEN_CONFIG_FILE ${DOXYGEN_OUTPUT_DIRECTORY}/doxygen.config)
     set(DOXYGEN_EXAMPLE_PATH ${ARG_EXAMPLES_PATH})
+    set(DOXYGEN_STRIP_FROM_PATH ${ARG_DOCS_DOXY_ROOT}/../include/libcyphal)
 
     list(APPEND DOXYGEN_INPUT_LIST ${ARG_INPUT_LIST})
     list(JOIN DOXYGEN_INPUT_LIST "\\\n    " DOXYGEN_INPUT )
@@ -129,7 +130,7 @@ endfunction(create_docs_target)
 file(GLOB_RECURSE DOXYGEN_INPUT_LIST
     LIST_DIRECTORIES false
     CONFIGURE_DEPENDS
-    ${LIBCYPHAL_ROOT}/include/libcyphal/**/*.hpp
+    ${LIBCYPHAL_ROOT}/include/**/*.hpp
 )
 
 get_property(LOCAL_EXAMPLES DIRECTORY "examples" PROPERTY IN_BUILD_TESTS)