Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/philips-software/amp-devcontainer

🔋amp-devcontainer is a batteries-included devcontainer useable for modern, embedded, software development
https://github.com/philips-software/amp-devcontainer

clang-format clang-tidy clangd cmake cpp devcontainer embedded fuzzing mutation-testing rust

Last synced: 6 months ago
JSON representation

🔋amp-devcontainer is a batteries-included devcontainer useable for modern, embedded, software development

Awesome Lists containing this project

README 

          
# amp-devcontainer



[![Linting & Formatting](https://github.com/philips-software/amp-devcontainer/actions/workflows/linting-formatting.yml/badge.svg)](https://github.com/philips-software/amp-devcontainer/actions/workflows/linting-formatting.yml) [![Build & Push](https://github.com/philips-software/amp-devcontainer/actions/workflows/build-push.yml/badge.svg)](https://github.com/philips-software/amp-devcontainer/actions/workflows/build-push.yml) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9267/badge)](https://www.bestpractices.dev/projects/9267) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/philips-software/amp-devcontainer/badge)](https://securityscorecards.dev/viewer/?uri=github.com/philips-software/amp-devcontainer)



## Overview



This repository contains [devcontainers](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers) tailored towards modern, embedded, software development.



The containers try to be as "batteries included" as possible without being overly opinionated, and are useable 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](https://opencontainers.org/) compatible container engine. This includes Windows and Linux, and macOS on both Intel and Apple silicon.



## State



This repository is under active development; see [pulse](https://github.com/philips-software/amp-devcontainer/pulse) for more details.



## Description



### Image variants



The following devcontainers are published towards the [GitHub Container Registry](https://ghcr.io/):



- [amp-devcontainer-cpp](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-cpp); the C++ container

- [amp-devcontainer-rust](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-rust); the Rust container



Both containers include a full [Visual Studio Code](https://code.visualstudio.com/) configuration that is compatible with [GitHub Codespaces](https://github.com/features/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](https://github.com/philips-software/amp-devcontainer/network/dependencies), the SBOM published with a [release](https://github.com/philips-software/amp-devcontainer/releases), 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](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-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](https://mutants.rs/)), fuzzing (using [rust-fuzz](https://rust-fuzz.github.io/book/introduction.html)) and static analysis and formatting (clippy, rustfmt).



For embedded development and flashing and debugging [probe-rs](https://probe.rs/) and [flip-link](https://github.com/knurling-rs/flip-link) are included.



### 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](https://containers.dev/implementors/reference/#labels). It is possible to override, amend or change the options following this [merge logic](https://containers.dev/implementors/spec/#merge-logic).



## Usage



### Verify image signature



Prior to version 5.6.0



The container images are signed with [SigStore](https://www.sigstore.dev/) [Cosign](https://docs.sigstore.dev/cosign/signing/overview/) using a keyless signing method.



The signature can be [verified](https://docs.sigstore.dev/cosign/verifying/verify/) with the following command (using Docker), verifying that the image is actually signed by the GitHub CI system:



> amp-devcontainer-cpp



```sh

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



```sh

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](https://github.com/actions/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



```sh

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

```



> amp-devcontainer-rust



```sh

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](https://github.com/philips-software/amp-devcontainer/releases) for the SHA corresponding to a specific release.



#### amp-devcontainer-cpp



> .devcontainer/devcontainer.json or .devcontainer.json



```json

{

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

}

```



#### amp-devcontainer-rust



> .devcontainer/devcontainer.json or .devcontainer.json



```json

{

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

}

```



## Community



This project uses a [code of conduct](.github/CODE_OF_CONDUCT.md) 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](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) functionality of GitHub.



## Changelog



See the [changelog](./CHANGELOG.md) for more info on what's been changed.



## Contributing



This project uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) and [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) please see the [contributing](.github/CONTRIBUTING.md) guideline for more information.



### Build & Test



The containers can be built and tested locally by importing this repository in VS Code with the [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) plug-in installed. As a prerequisite an OCI compatible container engine needs to be installed on the host system. 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).



```dotenv

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](.github/SECURITY.md) for more information.



## Licenses



See [license](./LICENSE).