{"id":31598671,"url":"https://github.com/akospasztor/stm32-project-template","last_synced_at":"2026-03-06T00:31:18.967Z","repository":{"id":255068013,"uuid":"848418246","full_name":"akospasztor/stm32-project-template","owner":"akospasztor","description":"STM32-based firmware project template featuring modern, CMake-based build system, documentation generation with Doxygen, source code formatting with clang-format, linting, enforcing style and naming conventions with clang-tidy, devcontainer, proven and scalable folder organization and more.","archived":false,"fork":false,"pushed_at":"2025-07-06T07:00:48.000Z","size":2631,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-06T05:58:22.493Z","etag":null,"topics":["build-system","clang-format","clang-tidy","cmake","devcontainer","doxygen","stm32","vscode"],"latest_commit_sha":null,"homepage":"https://akospasztor.github.io/stm32-project-template/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akospasztor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-27T18:12:15.000Z","updated_at":"2025-10-01T20:07:08.000Z","dependencies_parsed_at":"2025-03-13T11:38:05.795Z","dependency_job_id":null,"html_url":"https://github.com/akospasztor/stm32-project-template","commit_stats":null,"previous_names":["akospasztor/stm32-project-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/akospasztor/stm32-project-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akospasztor%2Fstm32-project-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akospasztor%2Fstm32-project-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akospasztor%2Fstm32-project-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akospasztor%2Fstm32-project-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akospasztor","download_url":"https://codeload.github.com/akospasztor/stm32-project-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akospasztor%2Fstm32-project-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30156285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-system","clang-format","clang-tidy","cmake","devcontainer","doxygen","stm32","vscode"],"created_at":"2025-10-06T05:50:14.325Z","updated_at":"2026-03-06T00:31:18.959Z","avatar_url":"https://github.com/akospasztor.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# STM32 Project Template\n\nThis repository contains a project template for STM32-based firmware projects.\nIt features a modern, CMake-based build system, documentation generation with\nDoxygen, source code formatting with clang-format, linting, enforcing style and\nnaming conventions with clang-tidy, verifying MISRA C compliance with Cppcheck,\ndevcontaine support, proven and scalable folder organization and more.\n\nThe project template runs on a\n[STM32L496 Discovery](https://www.st.com/en/evaluation-tools/32l496gdiscovery.html)\nboard out of the box. By default, the debug configuration is set up with a\nSEGGER J-Link debug probe. SEGGER offers a tool to convert the onboard ST-Link\ndebugger on Discovery and Nucleo boards into a SEGGER J-Link debugger. The\nonboard ST-Link debugger on the STM32L496 Discovery board used in this project\nwas converted to a J-Link debugger\n[with this tool](https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/).\n\n[https://akospasztor.github.io/stm32-project-template/](https://akospasztor.github.io/stm32-project-template/)\n\n[![CI Pipeline](https://github.com/akospasztor/stm32-project-template/actions/workflows/ci-pipeline.yml/badge.svg)](https://github.com/akospasztor/stm32-project-template/actions/workflows/ci-pipeline.yml)\n\n## Contents\n\n- [Contents](#contents)\n- [Usage](#usage)\n  - [Prerequisites](#prerequisites)\n  - [Build system commands](#build-system-commands)\n  - [Manual execution of cppcheck](#manual-execution-of-cppcheck)\n  - [Inline suppression of messages](#inline-suppression-of-messages)\n- [Features](#features)\n  - [Build system](#build-system)\n  - [Documentation](#documentation)\n  - [Format check](#format-check)\n  - [Static code analysis \\\u0026 linting](#static-code-analysis--linting)\n  - [Style check](#style-check)\n  - [Continuous integration](#continuous-integration)\n  - [Development container](#development-container)\n  - [VSCode integration](#vscode-integration)\n- [Repository structure](#repository-structure)\n\n## Usage\n\n### Prerequisites\n\n- [CMake](https://cmake.org/download/) is installed and available on your PATH.\n- [Cppcheck](https://cppcheck.sourceforge.io/) is installed and available on\n  your PATH.\n- [Ninja](https://ninja-build.org) is installed and available on your PATH.\n  Alternatively, you can use Make.\n- [GCC for ARM](https://developer.arm.com/downloads/-/gnu-rm) (GNU Arm Embedded\n  Toolchain) is installed and available in your PATH.\n- Clang-format and clang-tidy tools are installed and available in your PATH.\n  These tools are used for source code formatting and performing style checks.\n  You can obtain these tools via your preferred package manager or by installing\n  the [LLVM](https://llvm.org) toolchain.\n- Python is required to run clang-format from the build system. Additionally,\n  the `requirements.txt` file contains packages that are used for style checks.\n  It is highly recommended to install and run the python packages in a python\n  virtual environment (virtualenv).\n\nNote: In case the GCC for ARM or the clang-tools are not available in your PATH\n(e.g. you have multiple, different versions installed), you can specify the\ntoolchain paths in the respective toolchain `.cmake` file.\n\n### Build system commands\n\n| Command                                              | Description                                               |\n|:-----------------------------------------------------|:----------------------------------------------------------|\n| `cmake --list-presets`                               | List all CMake presets                                    |\n| `cmake --preset Debug`                               | Configure the project for Debug build                     |\n| `cmake --build --preset Debug`                       | Build the firmware with Debug build type                  |\n| `cmake --build --preset Debug --target clean`        | Clean the Debug target                                    |\n| `cmake --build --preset Debug --target check-format` | Check source code formatting with clang-format            |\n| `cmake --build --preset Debug --target run-format`   | Run source code formatting with clang-format              |\n| `cmake --build --preset Debug --target cppcheck`     | Perform analysis and MISRA conformity check with cppcheck |\n| `cmake --build --preset Debug --target tidy`         | Perform analysis and style check with clang-tidy          |\n| `cmake --build --preset Debug --target doxygen`      | Generate documentation with Doxygen                       |\n\nSupported CMake configurations and build presets:\n\n| Preset           | Description                                                                         |\n|:-----------------|:------------------------------------------------------------------------------------|\n| `Debug`          | Debug preset for debugging, without any optimization enabled                        |\n| `Release`        | Release preset with `O3` optimization                                               |\n| `MinSizeRel`     | Release preset with `Os` optimization for size with link time optimization enabled  |\n| `RelWithDebInfo` | Release preset with `O2` optimization with debug information                        |\n\n### Manual execution of cppcheck\n\nMake sure that the build and output directories exist because Cppcheck does not\ncreate them automatically:\n\n```shell\nmkdir -p build/Debug/cppcheck/report\n```\n\nRun Cppcheck:\n\n```shell\ncppcheck \\\n--project=build/Debug/compile_commands.json \\\n--cppcheck-build-dir=build/Debug/cppcheck \\\n--checkers-report=build/Debug/cppcheck/report/checkers.txt \\\n--addon=lint/misra.json \\\n--check-level=exhaustive \\\n--enable=all \\\n--error-exitcode=1 \\\n--inconclusive \\\n--inline-suppr \\\n--max-ctu-depth=10 \\\n--safety \\\n--std=c11 \\\n--suppressions-list=lint/suppressions.txt \\\n-D__GNUC__ \\\n-j$(nproc)\n```\n\n### Inline suppression of messages\n\nWhen a suppression for a message needs to be added, it must be added with the\nfollowing format. All suppressions must have a justification.\n\n```c\n// Message:     The actual message from the static code analysis tool\n// Reason:      The reason why this message pops up and why this message needs\n//              to be suppressed.\n// Risk:        The risk and possible unwanted side-effects by supressing the\n//              message.\n// Prevention:  How can be the risk prevented/mitigated.\n// cppcheck-suppress [...]\n```\n\n## Features\n\n### Build system\n\nThe project has a CMake-based build system that allows seamless execution of all\nbuild-related tasks regardless of environment. The build system commands can be\nexecuted directly from the command line and can also be integrated into the IDEs\nand editors that support CMake (e.g. Visual Studio Code). It also works both\nlocally and in a remote environment, such as in a container or a continuous\nintegration (CI) pipeline.\n\nSee to the [Usage](#usage) section for the supported build types and built-in\nCMake build targets.\n\n### Documentation\n\nThe source code is documented with Javadoc style comment blocks. The\ndocumentation output is generated with Doxygen. The output html files are\nautomatically deployed to GitHub pages after a successful merge to the default\nbranch.\n\n### Format check\n\nSource code formatting can be checked with clang-format. The check verifies that\nthe source code conforms to the formatting guidelines contained in the\n`.clang-format` file. The source code can also be reformatted with the\nappropriate command (see the [Usage](#usage) section) to conform to the\nformatting guidelines.\n\n### Static code analysis \u0026 linting\n\nClang-tidy is used for basic linting of the source code. In addition, this tool\nalso checks and enforces naming conventions and style violations.\n\nCppcheck is used for static code analysis, including verifying compliance with\nMISRA C. The official MISRA headlines for Cppcheck can be obtained at:\n[https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/tools/-/tree/main](https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/tools/-/tree/main)\n\n### Style check\n\nThe `requirements.txt` file contains packages that are used for style checking.\n[Editorconfig-checker](https://github.com/editorconfig-checker/editorconfig-checker)\nis used to check that all files in the repository conform to the `.editorconfig`\nfile. [Flake8](https://flake8.pycqa.org/en/latest/) and\n[yamllint](https://yamllint.readthedocs.io/en/stable/) packages are used to\nenforce style guides for python and yaml files respectively.\n\nThese style checking tasks are not part of the build system, however they are\nrun as part of the CI pipeline.\n\n### Continuous integration\n\nThe continuous integration (CI) pipeline is set up with GitHub Actions. It runs\nautomatically on every git push and has the following stages:\n\n1. Check stage:\n   - Check source code formatting with clang-format\n   - Run editorconfig-checker\n   - Run flake8\n   - Run yamllint\n2. Build stage:\n   - Build the firmware with all build configurations\n   - Build the documentation with Doxygen\n   - Run clang-tidy\n   - Run cppcheck\n3. Deploy stage:\n   - Collect artifacts\n   - Deploy Doxygen output to GitHub pages (runs only on master branch, e.g.\n     after merging a pull request)\n\n### Development container\n\nThe repository contains a devcontainer file that enables development inside a\ncontainer. The development container uses the\n[akospasztor/docker-gcc-arm](https://hub.docker.com/r/akospasztor/docker-gcc-arm)\nDocker image.\n\n### VSCode integration\n\nThe project includes C/C++ configuration presets, debug launch presets and CMake\npresets for Visual Studio Code. The following extensions are recommended for the\nbest development experience:\n\n- [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring)\n- [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)\n- [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)\n- [Cortex Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)\n- [Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)\n- [Doxygen Documentation Generator](https://marketplace.visualstudio.com/items?itemName=cschlosser.doxdocgen)\n- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)\n- [Remote Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack)\n\n## Repository structure\n\n```text\nstm32-project-template\n├── .devcontainer\n├── .github\n│   └── workflows\n├── .vscode\n├── build\n├── cmake\n│   ├── microcontrollers\n│   ├── toolchains\n│   └── tools\n├── docs\n│   └── doxygen\n├── include\n├── lib\n│   ├── CMSIS\n│   └── STM32L4xx_HAL_Driver\n├── mcal\n│   └── st-stm32l4\n│       ├── gcc-arm\n│       ├── include\n│       ├── source\n│       └── svd\n├── project\n│   └── ozone\n├── script\n└── source\n```\n\nThe `.devcontainer` folder contains the devcontainer file which enables\ndevelopment inside a container.\n\nThe `.github` folder contains the GitHub Actions workflow file which describes\nthe CI pipeline that runs automatically on every git push operation.\n\nUpon building the project, a `build` folder is created. All build-related files\nand output binaries are located in the `build` folder, organized into\nsubfolders. Each build target and their respective output files have their own\nsubfolder. The generated Doxygen documentation output files are also located in\nthe `build` folder.\n\nThe `cmake` folder contains the files related to the CMake-based build system,\nincluding the toolchain and microcontroller-specific files.\n\nThe `docs` folder contains the doxygen configuration file (Doxyfile) and other\ndocumentation-related static files.\n\nThe application-level source code and corresponding header files are located in\nthe `source` and `include` folders respectively.\n\nThe `lib` folder contains all third-party code, including the CMSIS (Cortex\nMicrocontroller Software Interface Standard) as well as the HAL (Hardware\nAbstraction Layer) drivers from ST.\n\nThe `mcal` folder stands for Microcontroller Abstraction Library. This folder\ncontains the microcontroller-specific files and drivers. These drivers are\ninterfaced by the application source code and they function as tiny wrappers\naround the low-level (HAL) drivers. This allows the application to interface\nthese thin wrappers instead of the manufacturer-specific low-level code, thus\nproviding easy portability across different chips and microcontrollers.\n\nThe `project` folder contains SDK- and debugger-specific files organized into\nsubfolders.\n\nThe `script` folder contains helper scripts related to the project and the build\nsystem.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakospasztor%2Fstm32-project-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakospasztor%2Fstm32-project-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakospasztor%2Fstm32-project-template/lists"}