diff --git a/.devcontainer/docs-test/devcontainer.json b/.devcontainer/docs-test/devcontainer.json new file mode 100644 index 00000000..80efc7c3 --- /dev/null +++ b/.devcontainer/docs-test/devcontainer.json @@ -0,0 +1,4 @@ +{ + "image": "ghcr.io/philips-software/amp-devcontainer-docs:${localEnv:IMAGE_VERSION}", + "workspaceFolder": "/workspaces/amp-devcontainer/test/docs/workspace" +} diff --git a/.devcontainer/docs/Dockerfile b/.devcontainer/docs/Dockerfile new file mode 100644 index 00000000..a44fab8f --- /dev/null +++ b/.devcontainer/docs/Dockerfile @@ -0,0 +1,34 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=ghcr.io/philips-software/amp-devcontainer-base:edge +FROM ${BASE_IMAGE} + +ARG DEBIAN_FRONTEND=noninteractive + +HEALTHCHECK NONE + +SHELL ["/bin/bash", "-Eeuo", "pipefail", "-c"] + +# Set default environment options +ENV PYTHONPYCACHEPREFIX=/cache/.python + +# Install the base system with all tool dependencies +RUN --mount=type=bind,source=.devcontainer/docs/apt-requirements.json,target=/tmp/apt-requirements.json \ + --mount=type=bind,source=.devcontainer/docs/requirements.txt,target=/tmp/requirements.txt \ + --mount=type=cache,target=/cache,sharing=locked \ + --mount=type=cache,target=/var/cache/apt,sharing=locked \ + --mount=type=cache,target=/var/lib/apt,sharing=locked \ + --mount=type=cache,target=/var/log,sharing=locked < amp-devcontainer.sbdl - name: Create document control context diff --git a/README.md b/README.md index 4fb8415c..fe27eb07 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ This repository contains [devcontainers](https://docs.github.com/en/codespaces/s - **Batteries Included** ๐Ÿ”‹: Pre-configured tools for local development and continuous integration. - **Developer Experience** ๐Ÿ‘ฉโ€๐Ÿ’ป: Minimal set-up time and maximal shift-left. - **Multi-platform Support** โš™๏ธ: Compatible with x64 and arm64 hardware on Windows, Linux, and macOS. -- **Image Flavors** ๐Ÿจ: Dedicated containers for C++, embedded C++, and Rust development. +- **Image Flavors** ๐Ÿจ: Dedicated containers for C++, embedded C++, Rust, and documentation generation. - **IDE Integration** ๐Ÿ’ป: Fully compatible with GitHub Codespaces and VS Code. - **Semantic Versioning** ๐Ÿ”ข: Clear versioning strategy for container images. - **Secure** ๐Ÿ”’: Emphasis on supply-chain security and compatible with Dependabot. @@ -54,6 +54,7 @@ The following devcontainers are published towards the [GitHub Container Registry - [amp-devcontainer-base](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-base); shared base image used by the other flavors - [amp-devcontainer-cpp](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-cpp); the C++ container +- [amp-devcontainer-docs](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-docs); the documentation generation container - [amp-devcontainer-embedded-cpp](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-embedded-cpp); the embedded C++ container - [amp-devcontainer-rust](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-rust); the Rust container @@ -69,22 +70,27 @@ It consolidates common tooling (e.g. certificates and test tooling) so that the #### amp-devcontainer-cpp -The amp-devcontainer-cpp built from this repository contains compilers and tools to facilitate modern C++ development. +The amp-devcontainer-cpp image built from this repository contains compilers and tools to facilitate modern C++ development. The amp-devcontainer-cpp includes support for host- and cross-compilation using gcc and clang compilers. Next to the compilers there is support for package management (using [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) and [Conan](https://conan.io/)) code-coverage measurement, mutation testing (using [mull](https://github.com/mull-project/mull)), fuzzing (using [libfuzzer](https://www.llvm.org/docs/LibFuzzer.html)) and static analysis and formatting (clang-format, clang-tidy, clangd, include-what-you-use). The default build system is set up to use CMake, Ninja and CCache. +#### amp-devcontainer-docs + +The amp-devcontainer-docs image built from this repository contains tooling to generate documentation from repository sources. +It includes [sbdl](https://sbdl.dev/) to capture the essence of system composition and behaviour in a simple yet powerful domain-specific language, together with [PlantUML](https://plantuml.com/) and [Graphviz](https://graphviz.org/) for rendering diagrams. + #### amp-devcontainer-embedded-cpp -The amp-devcontainer-embedded-cpp built from this repository contains the same tooling as amp-devcontainer-cpp, extended with support for embedded C++ development. +The amp-devcontainer-embedded-cpp image built from this repository contains the same tooling as amp-devcontainer-cpp, extended with support for embedded C++ development. On top of the host- and cross-compilation support it adds the arm-gcc (arm-none-eabi) toolchain for cross-compilation towards the ARM Cortex architecture, together with debugging support for micro-controllers (using [cortex-debug](https://github.com/Marus/cortex-debug) and gdb-multiarch). The default build system is set up to use CMake, Ninja and CCache. #### amp-devcontainer-rust -The amp-devcontainer-rust built from this repository contains the Rust ecosystem and additional tools to facilitate, embedded, Rust development. +The amp-devcontainer-rust image built from this repository contains the Rust ecosystem and additional tools to facilitate, embedded, Rust development. The amp-devcontainer-rust includes support for host- and cross-compilation. Next to the Rust ecosystem there is support for code-coverage measurement, mutation testing (using [cargo-mutants](https://mutants.rs/)), fuzzing (using [rust-fuzz](https://rust-fuzz.github.io/book/introduction.html)) and static analysis and formatting (clippy, rustfmt). diff --git a/test/docs/integration-tests.bats b/test/docs/integration-tests.bats new file mode 100644 index 00000000..0f205ab4 --- /dev/null +++ b/test/docs/integration-tests.bats @@ -0,0 +1,85 @@ +#!/usr/bin/env bats + +bats_require_minimum_version 1.5.0 + +setup() { + load '/usr/local/bats-support/load' + load '/usr/local/bats-assert/load' + + pushd ${BATS_TEST_DIRNAME}/workspace +} + +teardown() { + popd +} + +## This section contains tests for version correctness of the installed tools. +# Comparing the versions of the installed tools with the expected versions as +# pinned in the flavor's apt- and pip-requirements. + +# bats test_tags=Version,Graphviz +@test "graphviz version should be aligned with the expected version" { + EXPECTED_VERSION=$(get_expected_semver_for graphviz) + INSTALLED_VERSION=$(dot -V 2>&1 | to_semver) + + assert_equal "$INSTALLED_VERSION" "$EXPECTED_VERSION" +} + +# bats test_tags=Version,Pip +@test "pip version should be aligned with the expected version" { + EXPECTED_VERSION=$(get_expected_semver_for python3-pip) + INSTALLED_VERSION=$(pip --version | to_semver) + + assert_equal "$INSTALLED_VERSION" "$EXPECTED_VERSION" +} + +# bats test_tags=Version,Sbdl +@test "sbdl version should be aligned with the expected version" { + EXPECTED_VERSION=$(grep sbdl ${BATS_TEST_DIRNAME}/../../.devcontainer/docs/requirements.in | to_semver) + INSTALLED_VERSION=$(sbdl --version | to_semver) + + assert_equal "$INSTALLED_VERSION" "$EXPECTED_VERSION" +} + +## This section contains tests for the functional correctness of the installed tools. + +# bats test_tags=Functional,Plantuml +@test "plantuml should render a diagram to a png image" { + run plantuml -o build -tpng diagram.puml + + assert_success + assert [ -f build/diagram.png ] +} + +# bats test_tags=Functional,Graphviz +@test "graphviz should render a graph to an svg image" { + run dot -Tsvg graph.dot + + assert_success + assert_output --partial " Bob: Authentication Request +Bob --> Alice: Authentication Response +@enduml diff --git a/test/docs/workspace/graph.dot b/test/docs/workspace/graph.dot new file mode 100644 index 00000000..3f08981a --- /dev/null +++ b/test/docs/workspace/graph.dot @@ -0,0 +1,4 @@ +digraph { + a -> b; + b -> c; +} diff --git a/test/docs/workspace/sample.sbdl b/test/docs/workspace/sample.sbdl new file mode 100644 index 00000000..d6c1957d --- /dev/null +++ b/test/docs/workspace/sample.sbdl @@ -0,0 +1,5 @@ +#!sbdl +req-doc-0001 is requirement { + custom:title is "Sample requirement" + description is "A sample requirement used to validate the sbdl toolchain" +}