Issue #222: v1 platform layer

.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 → 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

cmake/toolchains/clang-native.cmake

@@ -7,3 +7,9 @@
 set(CMAKE_C_COMPILER clang)
 set(CMAKE_CXX_COMPILER clang++)
 set(CMAKE_ASM_COMPILER clang)
+
+# Signal to unit tests that the coverage data will be generated by
+# clang so they should try to use llvm-cov if it's available. 
+# Things are weird between gcov and llvm-cov right now but this 
+# seems to work in our Ubuntu 18 Docker container, so...?
+set(LIBUAVCAN_USE_LLVM_COV ON)

cmake/toolchains/gcc-native.cmake

@@ -0,0 +1,8 @@
+#
+# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Toolchain for using gcc on what-ever-platform-this-is (aka "native").
+#
+set(CMAKE_C_COMPILER gcc)
+set(CMAKE_CXX_COMPILER g++)
+set(CMAKE_ASM_COMPILER gcc)

doc_source/doxygen.ini

@@ -44,14 +44,14 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = Portable reference implementation of the UAVCAN protocol stack written in C++ for embedded systems, Linux, and POSIX-compliant RTOSs.
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = @DOXYGEN_LOGO@
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -98,7 +98,7 @@ OUTPUT_LANGUAGE        = English
 # documentation (similar to Javadoc). Set to NO to disable this.
 # The default value is: YES.
 
-BRIEF_MEMBER_DESC      = YES
+BRIEF_MEMBER_DESC      = NO
 
 # If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief
 # description of a member or function before the detailed description
@@ -135,7 +135,7 @@ ABBREVIATE_BRIEF       = "The $name class" \
 # description.
 # The default value is: NO.
 
-ALWAYS_DETAILED_SEC    = NO
+ALWAYS_DETAILED_SEC    = YES
 
 # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
 # inherited members of a class in the documentation of that class as if those
@@ -187,7 +187,7 @@ SHORT_NAMES            = NO
 # description.)
 # The default value is: NO.
 
-JAVADOC_AUTOBRIEF      = YES
+JAVADOC_AUTOBRIEF      = NO
 
 # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
 # line (until the first dot) of a Qt-style comment as the brief description. If
@@ -253,7 +253,7 @@ TCL_SUBST              =
 # members will be omitted, etc.
 # The default value is: NO.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 # Python sources only. Doxygen will then generate output that is more tailored
@@ -927,7 +927,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = @DOXYGEN_IMAGE_PATH@
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program