From 0fbe5817c358ccd43e56f48916198a0d10b6e931 Mon Sep 17 00:00:00 2001 From: Ramya Subramanyam Date: Sun, 23 Mar 2025 09:36:12 +0530 Subject: [PATCH] Extend README.md documentation Signed-off-by: Ramya Subramanyam --- Makefile | 8 +--- README.md | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 116 insertions(+), 12 deletions(-) diff --git a/Makefile b/Makefile index 1f83d23..79c432b 100644 --- a/Makefile +++ b/Makefile @@ -31,15 +31,11 @@ USERYAML=config/user.yml pull-container: docker pull $(REGISTRY) + find ./tools/code_checks/ -name "*.sh" -exec chmod +x {} \; run-container-check-all: clean-results pull-container $(DOCKER) python3 $(CODECHECK) --projectYAML $(PROJECTYAML) --userYAML $(USERYAML) --getAllChecks - $(DOCKER) python3 $(CODECHECK) ---projectYAML $(PROJECTYAML) --userYAML $(USERYAML) -runAllChecks - -run-container-project-setup-script-with-show-logs: clean-results pull-container - $(DOCKER) python3 $(CODECHECK) --projectYAML $(PROJECTYAML) --userYAML $(USERYAML) --getAllChecks - $(DOCKER) python3 $(CODECHECK) --projectYAML $(PROJECTYAML) --userYAML $(USERYAML) --runCheck check-clang-tidy - $(DOCKER) python3 $(CODECHECK) --projectYAML $(PROJECTYAML) --userYAML $(USERYAML) --runAllChecks + $(DOCKER) python3 $(CODECHECK) --projectYAML $(PROJECTYAML) --userYAML $(USERYAML) --runAllChecks run-container-cppcheck: pull-container -rm -rf _results/cppcheck/* diff --git a/README.md b/README.md index 767674e..2336196 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,20 @@
  • Installation
    • +
  • + How to run Code checks locally + +
  • Usage
  • Roadmap
  • Contributing
    • @@ -91,11 +105,41 @@ ## About The Project +This repository provides templates for creating a new project. The following files can be modified and reused: +1. README.md +2. SECURITY.md +3. CODE_OF_CONDUCT.md +4. CONTRIBUTING.md +5. LICENSE +6. templates/RELEASE_NOTES.md +7. .github/ISSUE_TEMPLATE/bug_report_template.md +8. .github/ISSUE_TEMPLATE/feature_request_template.md + +It also provides a set of scripts and configurations to automate code quality checks and formatting for C/C++ and Python projects. It is designed to be integrated as a submodule in any project and includes workflows for running checks both locally and in GitHub Actions (GA) environments.

    (back to top)

    ### Features +1. Reusable Template Files + +2. Scripts to Run Code Quality Checks: + + - cppcheck: Static analysis for C/C++ code. + - clang-tidy: Linter and static analysis for C/C++ code. + - clang-format: Code formatting for C/C++. + - black: Code formatting for Python scripts. + +3. Seamless Integration: + + - Can be added as a submodule to any project. + - Supports local execution of code quality checks in development environments. + - Includes a GitHub Actions workflow for CI/CD integration. + +4. Customizable Checks: + + Project-specific and user-specific configurations using project.yml and user.yml. +

    (back to top)

    ### Built With @@ -119,8 +163,6 @@

    (back to top)

    - - ## Getting Started @@ -153,7 +195,77 @@ This is an example of how to list things you need to use the software and how to

    (back to top)

    +## How to run Code checks locally + +### Add Repository as a Submodule + +Include this repository as a submodule in your project using the following command: + +```bash +git submodule add extras/makers-devops +``` + +### Configure Your Project + +Create the following YAML files in your project to define the tools and checks to run: + +- project.yml: Contains project-specific configurations such as tools and commands. +- user.yml: Optionally define user-specific configurations. + +Add new tools and checks in the project.yml under the check: section to extend the configuration. +### Running Locally + +#### To execute using Docker and Make + +Ensure you have Docker installed to run containerized tools. The repository provides a Makefile to simplify execution of code quality checks. Some common commands include: + +- Clean Results: +```sh +make clean-results +``` + +- Run All Checks: +```sh +make run-container-check-all +``` + +- Run Specific Tools: +```sh +make run-container-cppcheck +make run-container-clang-tidy-check +make run-container-clang-tidy-format +make run-container-black-format +``` +For more details, refer to the Makefile in the repository. + +#### To execute without Docker + +Install the following tools locally: +- python3 +- cppcheck +- llvm +- black + +### Running in CI CD + +The repository includes a predefined workflow script that can be triggered to run all the defined checks in the GitHub Actions (GA) environment. + +In order to integrate, reference the workflow script from this repository ".github/workflows/code_checks.yml". +Ensure your project sets the inputs, project-yaml and user-yaml for configuration. + +### Generating Reports + +After running cppcheck and clang-tidy, you can generate a collective HTML report: + +```sh +make run-container-generate-html-report +``` + +The report will be available under the directory +_results/cppcheck/html-report/index.html + +

    (back to top)

    ## Usage @@ -164,8 +276,6 @@ _For more examples, please refer to the [Documentation](https://github.com/Infin

    (back to top)

    - - ## Roadmap @@ -178,8 +288,6 @@ See the [open issues](https://github.com/Infineon/makers-devops/issues) for a fu

    (back to top)

    - - ## Contributing