amp-devcontainer

Table of Contents

• Overview
• State
• Description
  • Image flavors
  • Versioning
  • Visual Studio Code
• Usage
  • Verify image signature
  • Local development
  • Continuous Integration
• Community
• Changelog
• Contributing
• Reporting vulnerabilities
• Licenses

Overview

This repository contains devcontainers tailored towards modern, embedded, software development.

Key Features

• Batteries Included 🔋: Pre-configured tools for local development and continuous integration.
• Multi-platform Support ⚙️: Compatible with x64 and arm64 hardware on Windows, Linux, and macOS.
• Image Flavors 🍨: Dedicated containers for C++ and Rust development.
• 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.
• Tested ✅: Includes verification tests.

The containers try to be as "batteries included" as possible without being overly opinionated, and are usable for both local development and continuous integration.

All containers are multi-platform and can be used on x64 (x86-64) and arm64 hardware on an operating system that supports an OCI compatible container engine. This includes Windows, Linux, and macOS on both Intel and Apple silicon.

State

This repository is under active development; see pulse for more details.

Description

Image flavors

The following devcontainers are published towards the GitHub Container Registry:

• amp-devcontainer-cpp; the C++ container
• amp-devcontainer-rust; the Rust container

Both containers include a full Visual Studio Code configuration that is compatible with GitHub Codespaces.

A summary of the included tools can be found below. For the full list of all included tools and tool versions see the Dependency Graph, the SBOM published with a release, or the SBOM attached to the image.

amp-devcontainer-cpp

The amp-devcontainer-cpp built from this repository contains compilers and tools to facilitate modern, embedded, C++ development. The amp-devcontainer-cpp includes support for host- and cross-compilation using gcc, arm-gcc and clang compilers. Next to the compilers there is support for package management (using CPM.cmake and Conan) code-coverage measurement, mutation testing (using mull), fuzzing (using libfuzzer) 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-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 includes support for host- and cross-compilation. Next to the Rust ecosystem there is support for code-coverage measurement, mutation testing (using cargo-mutants), fuzzing (using rust-fuzz) and static analysis and formatting (clippy, rustfmt).

For embedded development and flashing and debugging probe-rs and flip-link are included.

Versioning

The amp-devcontainer repository follows a semantic versioning strategy for its container images. This ensures clear communication of updates and compatibility. The versioning format used is <major>.<minor>.<patch>. Released containers are tagged with <major>, <major>.<minor>, <major>.<minor>.<patch> and v<major>.<minor>.<patch>. The latest build on the default branch is tagged with edge and pull request builds are tagged with pr-<number>.

Branch	Tag
Default	edge
Pull Request	pr-<number>
Release	v<major>.<minor>.<patch>
	<major>.<minor>.<patch>
	<major>.<minor>
	<major>

Released containers will never be cleaned-up, pull request builds are cleaned up when the pull request is merged, and edge builds may be cleaned up after being stale for a while.

The release notes always contain an overview of the corresponding image versions that include the full SHA next to the version number. This makes it possible for humans to easily see what version is used while still pinning to an exact version. This is the recommended way to refer to an image.

All container images are included in a release. This might change in the future when the need arises to have separate releases per container.

This versioning strategy is implemented as GitHub Actions workflows, ensuring consistency and security across releases. Only the GitHub Action workflow is allowed to create a release, and the resulting images are signed.

Visual Studio Code

Both containers can be used in Visual Studio Code or GitHub Codespaces without any additional configuration. All included tools are set-up and necessary plug-ins will be installed at container start. This behavior is implemented by appending devcontainer metadata to an image label according to these specifications. It is possible to override, amend or change the options following this merge logic.

Usage

Verify image signature

Prior to version 5.6.0

The container images are signed with SigStore Cosign using a keyless signing method.

The signature can be verified with the following command (using Docker), verifying that the image is actually signed by the GitHub CI system:

amp-devcontainer-cpp

docker run --rm gcr.io/projectsigstore/cosign verify ghcr.io/philips-software/amp-devcontainer-cpp --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp https://github.com/philips-software/amp-devcontainer

amp-devcontainer-rust

docker run --rm gcr.io/projectsigstore/cosign verify ghcr.io/philips-software/amp-devcontainer-rust --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp https://github.com/philips-software/amp-devcontainer

The container images are signed using the attest-build-provenance action.

The attestations can be checked with the following command, verifying that the image is actually built by the GitHub CI system:

amp-devcontainer-cpp

gh attestation verify --repo philips-software/amp-devcontainer oci://ghcr.io/philips-software/amp-devcontainer-cpp

amp-devcontainer-rust

gh attestation verify --repo philips-software/amp-devcontainer oci://ghcr.io/philips-software/amp-devcontainer-rust

Local development

The resulting containers can be used in a .devcontainer.json file or in a .devcontainer folder.

Note

While the following examples use the latest tag, it is recommended to pin to a specific version. Or better yet, a specific SHA. See the releases for the SHA corresponding to a specific release.

amp-devcontainer-cpp

.devcontainer/devcontainer.json or .devcontainer.json

{
    "image": "ghcr.io/philips-software/amp-devcontainer-cpp:latest"
}

amp-devcontainer-rust

.devcontainer/devcontainer.json or .devcontainer.json

{
    "image": "ghcr.io/philips-software/amp-devcontainer-rust:latest"
}

Continuous integration

The resulting containers can be used in a GitHub workflow by using the container property on a job.

jobs:
  container-job:
    runs-on: ubuntu-latest
    container: ghcr.io/philips-software/amp-devcontainer-cpp:latest

Community

This project uses a code of conduct to define expected conduct in our community. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the repository administrators by using the report content functionality of GitHub.

Changelog

See the changelog for more info on what's been changed.

Contributing

This project uses Semantic Versioning 2.0.0 and Conventional Commits 1.0.0 please see the contributing guideline for more information.

Build & Test

If you already have VS Code and a OCI compatible container engine installed, you can click the badge above or here to get started. Clicking these links will cause VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use. Alternatively a GitHub Codespace can be started.

Running the Integration Tests

Run the included bats integration tests from the test explorer. Alternatively run all tests with Ctrl + ; A.

Running the Acceptance Tests

Create a .env file in the root of the workspace with the following contents, this assumes a GitHub account that has rights to create a Codespace on this repository and is configured for time-based one-time password (TOTP) two-factor authentication (2FA).

GITHUB_USER=
GITHUB_PASSWORD=
GITHUB_TOTP_SECRET=

Test can now be run using the Test Explorer. The user interface is available on port 6080 by-default. When port 6080 is already taken another port will be exposed. This can be seen with the Ports view (Ctrl + Shift + P, Ports: Focus on Ports View).

Reporting vulnerabilities

If you find a vulnerability, please report it to us! See security for more information.

Licenses

amp-devcontainer is licensed under the MIT license. See license for more information.