Issue #222: v1 platform layer (#223)

* Issue #222: v1 platform layer

Interim PR here but I wanted to get this through review before it got
too big. Things of interest:

1. Coverage build logic is complete.
2. Better definition around the LVS (Libuavcan Validation Suite)
3. Start of the "media" layer for CAN.
4. More sadness that it isn't five years from now and we could just use
C++14.

* adding compile-time test

* Update ci/native-gcc-build-and-test.sh

Co-Authored-By: Pavel Kirienko <[email protected]>

* Update libuavcan/include/libuavcan/transport/media/can.hpp

Co-Authored-By: Pavel Kirienko <[email protected]>

* Tests, docs, and changes per PR comments.

* Update libuavcan/include/libuavcan/transport/media/can.hpp

Co-Authored-By: Pavel Kirienko <[email protected]>

* updating the docs with media layer design

* cleaning up some codacity warnings

* removed \"porting\" as a term.

* Adding newline to end of media.md.

Author: thirtytwobits

.buildkite/pipeline.yml

@@ -1,9 +1,10 @@
 steps:
   - label: ':hammer: native build and :mag: test'
-    command: "./ci/native-build-and-test.sh"
+    id: native-gcc-build-and-test
+    command: "./ci/native-gcc-build-and-test.sh"
     artifact_paths: 
-      - "build_ci_native/libuavcan"
-      - "build_ci_native/docs/**/*"
+      - "build_ci_native_gcc/libuavcan"
+      - "build_ci_native_gcc/docs/**/*"
     plugins:
       - docker#v3.1.0:
           workdir: /repo
@@ -12,7 +13,21 @@ steps:
       VERBOSE: 1
     agents:
       queue: 'default'
+    timeout_in_minutes: 15
+  - label: ':hammer: native build using clang'
+    id: native-clang-build
+    command: "./ci/native-clang-build.sh"
+    plugins:
+      - docker#v3.1.0:
+          workdir: /repo
+          image: "uavcan/libuavcan:latest"
+    env:
+      VERBOSE: 1
+    agents:
+      queue: 'default'
+    timeout_in_minutes: 15
   - label: ':hammer: s32k build'
+    id: ontarget-s32k-build
     command: "./ci/ontarget-s32k-build.sh"
     artifact_paths: 
       - "build_ci_ontarget_s32k/**/*.log"
@@ -28,6 +43,7 @@ steps:
       VERBOSE: 1
     agents:
       queue: 'default'
+    timeout_in_minutes: 15
   - wait
   - label: ":mag: ontarget testing"
     command: "./ci/ontarget-s32k-test.sh"

CMakeLists.txt

@@ -17,10 +17,12 @@ file(MAKE_DIRECTORY ${EXTERNAL_PROJECT_DIRECTORY})
 
 set(LIBUAVCAN_INCLUDE "${CMAKE_SOURCE_DIR}/libuavcan/include")
 set(LIBUAVCAN_INCLUDE_GENERATED "${CMAKE_CURRENT_BINARY_DIR}/dsdl")
+set(LIBUAVCAN_INCLUDE_LVS_PTEST "${CMAKE_SOURCE_DIR}/libuavcan_validation_suite/include")
 
 include_directories(
     ${LIBUAVCAN_INCLUDE}
     ${LIBUAVCAN_INCLUDE_GENERATED}
+    ${LIBUAVCAN_INCLUDE_LVS_PTEST}
 )
 
 if(NOT LIBUAVCAN_FLAG_SET)
@@ -55,11 +57,6 @@ find_package(public_regulated_data_types REQUIRED)
 #
 find_package(gtest REQUIRED)
 
-#
-# We generate coverage reports. Please look at them.
-#
-find_package(lcov REQUIRED)
-
 #
 # Finds programs needed to build the libuavcan documentation
 #
@@ -99,10 +96,15 @@ add_dependencies(format-generated dsdl-regulated)
 create_check_style_target(format-check ON "${LIBUAVCAN_INCLUDE}/**/*.hpp")
 
 # +---------------------------------------------------------------------------+
-# | BUILD AND RUN UNIT TESTS
+# | BUILD UNIT TESTS
 # +---------------------------------------------------------------------------+
 include(${LIBUAVCAN_TESTBUILD})
 
+# +---------------------------------------------------------------------------+
+# | DEFINE COMPILE-TIME TESTS
+# +---------------------------------------------------------------------------+
+include(${CMAKE_SOURCE_DIR}/test/compile/compile_tests.cmake)
+
 # +---------------------------------------------------------------------------+
 # | DOCUMENTATION GENERATION
 # +---------------------------------------------------------------------------+

README.md

@@ -3,6 +3,7 @@ UAVCAN stack in C++
 
 [![Build Status](https://badge.buildkite.com/af844974c06af6406e3b2192d98298b02b30f6ebebb5f8b16c.svg)](https://buildkite.com/uavcan/libuavcan-v1)
 [![Forum](https://img.shields.io/discourse/https/forum.uavcan.org/users.svg)](https://forum.uavcan.org)
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/5d487b332d99498699a0af687fa513a1)](https://www.codacy.com/app/UAVCAN/libuavcan_v1?utm_source=github.com&utm_medium=referral&utm_content=UAVCAN/libuavcan&utm_campaign=Badge_Grade)
 
 Portable reference implementation of the [UAVCAN protocol stack](https://new.uavcan.org) in C++ for embedded systems, Linux, and POSIX-compliant RTOSs.
 
@@ -25,7 +26,7 @@ You should never rewrite a codebase from scratch. It's a terrible idea. We're re
 
 Sorry.
 
-The reason we opted for a complete rewrite is that so much is changing. Between the updates to the specification, the abandonment of C++98 support, switching to header-only, removing the drivers from the main repository, adding CAN-FD support, etc, etc, etc; it was obvious that we'd be rewriting everything anyway. The good news is that v0 exists, is fully supported, and will be liberally copy-and-pasted from as this makes sense for v1. What we don't have is any git history tracing from v1 since this would be deceiving. Futhermore, the unit tests in uavcan v0 are a bit of a mess so we'll be writing them in a way that is more sustainable.
+The reason we opted for a complete rewrite is that so much is changing. Between the updates to the specification, the abandonment of C++98 support, switching to header-only, removing the drivers from the main repository, adding CAN FD support, etc, etc, etc; it was obvious that we'd be rewriting everything anyway. The good news is that v0 exists, is fully supported, and will be liberally copy-and-pasted from as this makes sense for v1. What we don't have is any git history tracing from v1 since this would be deceiving. Futhermore, the unit tests in uavcan v0 are a bit of a mess so we'll be writing them in a way that is more sustainable.
 
 ## Documentation
 
@@ -42,6 +43,8 @@ The reason we opted for a complete rewrite is that so much is changing. Between
 
 **/test/ontarget** - Tests cross-compiled for specific hardware* and run on a set of dedicated test devices. These tests may have strict timing constraints and may require specific physical or virtual busses and other test apparatuses be present. Each on-target test will fully document its requirements to enable anyone with access to the appropriate hardware to reproduce the tests. Furthermore, these tests must be inherently automateable having clear pass/fail criteria reducible to a boolean condition.
 
+**/test/compile** – Tests that run in the compiler. Most of these will be tests that pass if they fail to compile. For example, some tests will purposefully define template parameters that will cause static_asserts to fail. Tests that pass if they do compile are less interesting here since such happy paths are normally covered by unit-tests.
+
 **/example** - Contains a set of example applications providing real, practical, and tested uses of libuavcan.
 
 **/commons** - Reference implementations for parts of the libuavcan library. These implementations are optional but are provided as a convenience to accelerate evaluation and integration of libuavcan.
@@ -128,7 +131,7 @@ To use visual studio code to debug ontarget tests for the S32K146EVB you'll need
 ```
  {
     "cwd": "${workspaceRoot}",
-    "executable": "build/test_bus.elf",
+    "executable": "build/test_util_math.elf",
     "name": "On-target unit test.",
     "request": "launch",
     "type": "cortex-debug",

ci/native-build-and-test.sh renamed to ci/native-clang-build.sh

@@ -30,18 +30,18 @@ set -o pipefail
 # | deploy (i.e. There's really no 'I' going on).
 # +----------------------------------------------------------+
 
-mkdir -p build_ci_native
-pushd build_ci_native
-# We build native tests using clang since we use gcc for
-# cross-compiling. This gives us coverage by two different
-# compilers.
+mkdir -p build_ci_native_clang
+pushd build_ci_native_clang
+# We ensure we can build using clang but we rely on GCC for testing
+# since clang's coverage metrics have been broken for the last 
+# several years.
 cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/clang-native.cmake \
-      -DLIBUAVCAN_EXT_FOLDER=build_ci_ext \
+      -DLIBUAVCAN_EXT_FOLDER=build_ci_ext_clang \
       ..
+
 make -j4
 
+# We use ctest to run our compile tests.
 ctest -VV
 
-make docs
-
 popd

ci/native-gcc-build-and-test.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+
+# +----------------------------------------------------------+
+# | BASH : Modifying Shell Behaviour
+# |    (https://www.gnu.org/software/bash/manual)
+# +----------------------------------------------------------+
+# Treat unset variables and parameters other than the special
+# parameters ‘@’ or ‘*’ as an error when performing parameter
+# expansion. An error message will be written to the standard
+# error, and a non-interactive shell will exit.
+set -o nounset
+
+# Exit immediately if a pipeline returns a non-zero status.
+set -o errexit
+
+# If set, the return value of a pipeline is the value of the
+# last (rightmost) command to exit with a non-zero status, or
+# zero if all commands in the pipeline exit successfully.
+set -o pipefail
+
+# +----------------------------------------------------------+
+# | This script is one of the common set of commands run as
+# | part of a continuous integration build pipeline.
+# | These scrips are named using the following scheme:
+# |
+# |   [build_type]-[(optional)build_type qualifier]-[build|test|report|upload].sh
+# |
+# | Of course, libuavcan is a header-only distribution so
+# | CI is used to verify and test rather than package and
+# | deploy (i.e. There's really no 'I' going on).
+# +----------------------------------------------------------+
+
+mkdir -p build_ci_native_gcc
+pushd build_ci_native_gcc
+# GCC is our reference compiler since it does a better job with
+# coverage metrics.
+cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/gcc-native.cmake \
+      -DLIBUAVCAN_EXT_FOLDER=build_ci_ext_gcc \
+      -DLIBUAVCAN_INTROSPECTION_ENABLE_ASSERT=1 \
+      ..
+
+make -j4
+
+# We use ctest to run our compile tests.
+ctest -VV
+
+# This builds, runs, and reports on our native unit tests.
+# TODO: when we integrate with coveralls or codacy run make cov_info
+# instead to skip the genhtml step.
+make cov_all
+
+make docs
+
+popd

ci/ontarget-s32k-build.sh

@@ -45,4 +45,7 @@ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/gcc-arm-none-eabi.cmake \
 
 make -j4
 
+# We use ctest to run our compile tests.
+ctest -VV
+
 popd

cmake/common.cmake

@@ -31,10 +31,20 @@ function(apply_flag_set ARG_FLAG_SET)
         set(LOCAL_CMAKE_ASM_FLAGS "${LOCAL_CMAKE_ASM_FLAGS} ${ITEM}")
     endforeach()
 
+    # +-----------------------------------------------------------------------+
+    # | CONFIGURABLE DEFINITIONS
+    # +-----------------------------------------------------------------------+
+    if(DEFINED LIBUAVCAN_INTROSPECTION_ENABLE_ASSERT)
+        set(LOCAL_CMAKE_C_FLAGS "${LOCAL_CMAKE_C_FLAGS} -DLIBUAVCAN_INTROSPECTION_ENABLE_ASSERT=${LIBUAVCAN_INTROSPECTION_ENABLE_ASSERT}")
+        set(LOCAL_CMAKE_CXX_FLAGS "${LOCAL_CMAKE_CXX_FLAGS} -DLIBUAVCAN_INTROSPECTION_ENABLE_ASSERT=${LIBUAVCAN_INTROSPECTION_ENABLE_ASSERT}")
+    endif()
+    # +-----------------------------------------------------------------------+
+
     set(CMAKE_C_FLAGS ${LOCAL_CMAKE_C_FLAGS} PARENT_SCOPE)
     set(CMAKE_CXX_FLAGS ${LOCAL_CMAKE_CXX_FLAGS} PARENT_SCOPE)
     set(CMAKE_EXE_LINKER_FLAGS ${LOCAL_CMAKE_EXE_LINKER_FLAGS} PARENT_SCOPE)
     set(CMAKE_ASM_FLAGS ${LOCAL_CMAKE_ASM_FLAGS} PARENT_SCOPE)
 
     add_definitions(${DEFINITIONS_SET})
+
 endfunction()

cmake/compiler_flag_sets/native.cmake

@@ -65,3 +65,4 @@ list(APPEND CXX_FLAG_SET
 
 set(EXE_LINKER_FLAG_SET )
 set(DEFINITIONS_SET )
+

cmake/modules/Findlcov.cmake

@@ -1,9 +1,13 @@
 
-
 find_program(LCOV lcov)
+find_program(GENHTML genhtml)
 
 include(FindPackageHandleStandardArgs)
 
 find_package_handle_standard_args(lcov
     LCOV_FOUND
 )
+
+find_package_handle_standard_args(genhtml
+    GENHTML_FOUND
+)

cmake/modules/Findlibuavcan_docs.cmake

@@ -30,7 +30,7 @@ function (create_docs_target ARG_DOCS_TARGET_NAME ARG_ADD_TO_ALL)
     set(DOXYGEN_RDOMAIN_W_PROJECT org.uavcan.libuavcan)
     set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/docs)
     set(DOXYGEN_CONFIG_FILE ${DOXYGEN_OUTPUT_DIRECTORY}/doxygen.config)
-    set(DOXYGEN_INPUT "\"${CMAKE_CURRENT_SOURCE_DIR}/libuavcan/include\" \"${CMAKE_CURRENT_SOURCE_DIR}/README.md\"")
+    set(DOXYGEN_INPUT "\"${CMAKE_CURRENT_SOURCE_DIR}/libuavcan/include\" \"${CMAKE_CURRENT_SOURCE_DIR}/README.md\" \"${CMAKE_CURRENT_SOURCE_DIR}/doc_source/media.md\"")
     set(DOXYGEN_MAINPAGE "\"${CMAKE_CURRENT_SOURCE_DIR}/README.md\"")
 
     # +-----------------------------------------------------------------------+
@@ -40,6 +40,10 @@ function (create_docs_target ARG_DOCS_TARGET_NAME ARG_ADD_TO_ALL)
     set(DOXYGEN_HTML_STYLESHEET ${DOXYGEN_OUTPUT_DIRECTORY}/customdoxygen.css)
     set(DOXYGEN_HTML_HEADER ${DOXYGEN_OUTPUT_DIRECTORY}/header.html)
     set(DOXYGEN_HTML_FOOTER ${DOXYGEN_OUTPUT_DIRECTORY}/footer.html)
+    set(DOXYGEN_IMAGE_PATH ${DOXYGEN_OUTPUT_DIRECTORY}/images)
+    set(DOXYGEN_LOGO ${DOXYGEN_OUTPUT_DIRECTORY}/images/html/uavcan_logo_icon.png)
+
+    file(COPY ${DOXYGEN_SOURCE}/images DESTINATION ${DOXYGEN_OUTPUT_DIRECTORY})
 
     configure_file(${DOXYGEN_SOURCE}/header.html
                     ${DOXYGEN_OUTPUT_DIRECTORY}/header.html