diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt new file mode 100644 index 0000000..384222b --- /dev/null +++ b/.github/.cSpellWords.txt @@ -0,0 +1,47 @@ +cbmc +CBMC +cbor +CBOR +cmock +Cmock +CMock +CMOCK +coremqtt +coverity +Coverity +CSDK +ctest +DCMOCK +DCOV +decihours +Decihours +DECIHOURS +DNDEBUG +DUNITY +getpacketid +isystem +lcov +misra +Misra +MISRA +MQTT +mypy +nondet +Nondet +NONDET +pylint +pytest +pyyaml +sinclude +UNACKED +unpadded +Unpadded +UNPADDED +UNSUB +UNSUBACK +unsubscriptions +utest +vect +Vect +VECT +Wunused diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..6997339 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,37 @@ +# Each line is a file pattern followed by one or more owners. + +# These owners will be the default owners for everything in +# the repo. Unless a later match takes precedence, +# @global-owner1 and @global-owner2 will be requested for +# review when someone opens a pull request. +* @FreeRTOS/pr-bar-raiser + +# Order is important; the last matching pattern takes the most +# precedence. When someone opens a pull request that only +# modifies JS files, only @js-owner and not the global +# owner(s) will be requested for a review. +# *.c FreeRTOS/pr-bar-raiser + +# You can also use email addresses if you prefer. They'll be +# used to look up users just like we do for commit author +# emails. +# *.go docs@example.com + +# In this example, @doctocat owns any files in the build/logs +# directory at the root of the repository and any of its +# subdirectories. +# /build/logs/ @doctocat + +# The `docs/*` pattern will match files like +# `docs/getting-started.md` but not further nested files like +# `docs/build-app/troubleshooting.md`. +# docs/* docs@example.com + +# In this example, @octocat owns any file in an apps directory +# anywhere in your repository. +# apps/ @octocat + +# In this example, @doctocat owns any file in the `/docs` +# directory in the root of your repository and any of its +# subdirectories. +# /docs/ @doctocat \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e2675a3 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,22 @@ + + +Description +----------- + + +Test Steps +----------- + + +Checklist: +---------- + + +- [ ] I have tested my changes. No regression in existing tests. +- [ ] I have modified and/or added unit-tests to cover the code changes in this Pull Request. + +Related Issue +----------- + + +By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 31f5976..aeed5c7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,14 +10,15 @@ jobs: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build run: | sudo apt-get install -y lcov sed cmake -S test -B build/ \ -G "Unix Makefiles" \ -DCMAKE_BUILD_TYPE=Debug \ - -DBUILD_UNIT_TESTS=ON \ + -DUNITTEST=ON \ + -DBUILD_CLONE_SUBMODULES=ON \ -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -Werror' make -C build/ all - name: Test @@ -34,55 +35,61 @@ jobs: - name: Check Coverage uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@main with: - path: ./build/coverage.info + coverage-file: ./build/coverage.info + build-code-example: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build code example run: | cmake -S test -B Build -DBUILD_CODE_EXAMPLE=ON make -C Build code_example_posix -j8 + complexity: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check complexity uses: FreeRTOS/CI-CD-Github-Actions/complexity@main with: path: ./ + doxygen: - runs-on: ubuntu-20.04 + runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Run doxygen build uses: FreeRTOS/CI-CD-Github-Actions/doxygen@main with: path: ./ + spell-check: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Run spellings check uses: FreeRTOS/CI-CD-Github-Actions/spellings@main with: path: ./ + formatting: - runs-on: ubuntu-latest + runs-on: ubuntu-20.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check formatting uses: FreeRTOS/CI-CD-Github-Actions/formatting@main with: path: ./ + git-secrets: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Checkout awslabs/git-secrets - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: repository: awslabs/git-secrets ref: master @@ -93,32 +100,66 @@ jobs: run: | git-secrets --register-aws git-secrets --scan + custom-standard-c-header: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build run: | mkdir -p override-include cp source/include/stdint.readme override-include/stdint.h cmake -S test -B build/ \ -G "Unix Makefiles" \ - -DBUILD_CLONE_SUBMODULES=ON \ + -DCOV_ANALYSIS=ON \ -DCMAKE_C_FLAGS='-Wall -Wextra -Werror -I../override-include' make -C build/ coverity_analysis + memory_statistics: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: - submodules: 'recursive' + submodules: "recursive" - name: Install Python3 - uses: actions/setup-python@v2 + uses: actions/setup-python@v3 with: - python-version: '3.7.10' + python-version: "3.11.0" - name: Measure sizes uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@main with: - config: .github/memory_statistics_config.json - check_against: docs/doxygen/include/size_table.md + config: .github/memory_statistics_config.json + check_against: docs/doxygen/include/size_table.md + + link-verifier: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Check Links + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + uses: FreeRTOS/CI-CD-Github-Actions/link-verifier@main + with: + path: ./ + + verify-manifest: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + submodules: true + fetch-depth: 0 + + # At time of writing the gitmodules are set not to pull + # Even when using fetch submodules. Need to run this command + # To force it to grab them. + - name: Perform Recursive Clone + shell: bash + run: git submodule update --checkout --init --recursive + + - name: Run manifest verifier + uses: FreeRTOS/CI-CD-GitHub-Actions/manifest-verifier@main + with: + path: ./ + fail-on-incorrect-version: true diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml new file mode 100644 index 0000000..04786ba --- /dev/null +++ b/.github/workflows/formatting.yml @@ -0,0 +1,23 @@ +name: Format Pull Request Files + +on: + issue_comment: + types: [created] + +env: + bashPass: \033[32;1mPASSED - + bashInfo: \033[33;1mINFO - + bashFail: \033[31;1mFAILED - + bashEnd: \033[0m + +jobs: + Formatting: + name: Run Formatting Check + if: ${{ github.event.issue.pull_request && + ( ( github.event.comment.body == '/bot run uncrustify' ) || + ( github.event.comment.body == '/bot run formatting' ) ) }} + runs-on: ubuntu-20.04 + steps: + - name: Apply Formatting Fix + uses: FreeRTOS/CI-CD-Github-Actions/formatting-bot@main + id: check-formatting diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 046e78c..2e89994 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -11,12 +11,12 @@ on: required: true jobs: - generate-sbom-and-tag-commit: + tag-commit: name: Tag commit runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: ref: ${{ github.event.inputs.commit_id }} - name: Configure git identity @@ -53,7 +53,7 @@ jobs: - name: Install ZIP tools run: sudo apt-get install zip unzip - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: ref: ${{ github.event.inputs.commit_id }} path: backoffAlgorithm @@ -91,7 +91,7 @@ jobs: ctest -E system --output-on-failure cd .. - name: Create artifact of ZIP - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v4 with: name: backoffAlgorithm-${{ github.event.inputs.version_number }}.zip path: zip-check/backoffAlgorithm-${{ github.event.inputs.version_number }}.zip @@ -124,7 +124,7 @@ jobs: draft: false prerelease: false - name: Download ZIP artifact - uses: actions/download-artifact@v2 + uses: actions/download-artifact@v4 with: name: backoffAlgorithm-${{ github.event.inputs.version_number }}.zip - name: Upload Release Asset diff --git a/CHANGELOG.md b/CHANGELOG.md index 565b9e0..5bf3939 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,26 @@ # Changelog for backoffAlgorithm Library +## v1.4.1 (June 2024) + +### Changes +- Fix doxygen deployment on Github. + +## v1.4.0 (May 2024) + +### Changes +- [#51](https://github.com/FreeRTOS/backoffAlgorithm/pull/51) Update MISRA Check Information. +- [#45](https://github.com/FreeRTOS/backoffAlgorithm/pull/45) Update doxygen version to 1.9.6. + +## v1.3.0 (October 2022) + +### Changes + +- [#38](https://github.com/FreeRTOS/backoffAlgorithm/pull/38) MISRA compliance update + ## v1.2.0 (November 2021) + +### Changes + - [#31](https://github.com/FreeRTOS/backoffAlgorithm/pull/31) Update doxygen version for documentation. - [#30](https://github.com/FreeRTOS/backoffAlgorithm/pull/30) Add code examples to documentation. diff --git a/MISRA.md b/MISRA.md index 4f593a0..d265251 100644 --- a/MISRA.md +++ b/MISRA.md @@ -1,16 +1,21 @@ # MISRA Compliance -The backoffAlgorithm library files conform to the [MISRA C:2012](https://www.misra.org.uk) -guidelines, with some noted exceptions. Compliance is checked with Coverity static analysis. -The specific deviations, suppressed inline, are listed below. - -Additionally, [MISRA configuration file](https://github.com/FreeRTOS/backoffAlgorithm/blob/main/tools/coverity/misra.config) contains the project wide deviations. +The backoffAlgorithm library files conform to the +[MISRA C:2012](https://www.misra.org.uk) guidelines, with some noted exceptions. +Compliance is checked with Coverity static analysis. The specific deviations, +suppressed inline, are listed below. +Additionally, +[MISRA configuration file](https://github.com/FreeRTOS/backoffAlgorithm/blob/main/tools/coverity/misra.config) +contains the project wide deviations. ### Suppressed with Coverity Comments + To find the violation references in the source files run grep on the source code with ( Assuming rule 11.4 violation; with justification in point 2 ): + ``` grep 'MISRA Ref 11.4.2' . -rI ``` -*None.* \ No newline at end of file + +_None._ diff --git a/README.md b/README.md index fcf9bff..9a66f42 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,40 @@ ## backoffAlgorithm Library -This repository contains the backoffAlgorithm library, a utility library to calculate backoff period using an exponential backoff with jitter algorithm for retrying network operations (like failed network connection with server). -This library uses the "Full Jitter" strategy for the exponential backoff with jitter algorithm. -More information about the algorithm can be seen in the [Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) AWS blog. +**[API Documentation Pages for current and previous releases of this library can be found here](https://freertos.github.io/backoffAlgorithm/)** -The backoffAlgorithm library is distributed under the [MIT Open Source License](LICENSE). +This repository contains the backoffAlgorithm library, a utility library to +calculate backoff period using an exponential backoff with jitter algorithm for +retrying network operations (like failed network connection with server). This +library uses the "Full Jitter" strategy for the exponential backoff with jitter +algorithm. More information about the algorithm can be seen in the +[Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) +AWS blog. -Exponential backoff with jitter is typically used when retrying a failed network -connection or operation request with the server. An exponential backoff with jitter helps to -mitigate failed network operations with servers, that are caused due to network congestion or high request load on -the server, by spreading out retry requests across multiple devices attempting network operations. -Besides, in an environment with poor connectivity, a client can get disconnected at any time. -A backoff strategy helps the client to conserve battery by not repeatedly attempting reconnections when they are -unlikely to succeed. - -See memory requirements for this library [here](./docs/doxygen/include/size_table.md). +The backoffAlgorithm library is distributed under the +[MIT Open Source License](LICENSE). -**backoffAlgorithm v1.0.0 [source code](https://github.com/FreeRTOS/backoffAlgorithm/tree/v1.0.0/source) is part of the [FreeRTOS 202012.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202012.00-LTS) release.** +Exponential backoff with jitter is typically used when retrying a failed network +connection or operation request with the server. An exponential backoff with +jitter helps to mitigate failed network operations with servers, that are caused +due to network congestion or high request load on the server, by spreading out +retry requests across multiple devices attempting network operations. Besides, +in an environment with poor connectivity, a client can get disconnected at any +time. A backoff strategy helps the client to conserve battery by not repeatedly +attempting reconnections when they are unlikely to succeed. + +See memory requirements for this library +[here](./docs/doxygen/include/size_table.md). + +**backoffAlgorithm v1.4.1 +[source code](https://github.com/FreeRTOS/backoffAlgorithm/tree/v1.4.1/source) +is part of the +[FreeRTOS 202406.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202406.00-LTS) +release.** ## Reference example -The example below shows how to use the backoffAlgorithm library on a POSIX platform to retry a DNS resolution query for `amazon.com`. +The example below shows how to use the backoffAlgorithm library on a POSIX +platform to retry a DNS resolution query for `amazon.com`. ```c #include "backoff_algorithm.h" @@ -106,18 +120,25 @@ int main() ## Building the library -A compiler that supports **C90 or later** such as *gcc* is required to build the library. +A compiler that supports **C90 or later** such as _gcc_ is required to build the +library. + +Additionally, the library uses a header file introduced in ISO C99, `stdint.h`. +For compilers that do not provide this header file, the +[source/include](source/include) directory contains +[stdint.readme](source/include/stdint.readme), which can be renamed to +`stdint.h` to build the backoffAlgorithm library. -Additionally, the library uses a header file introduced in ISO C99, `stdint.h`. For compilers that do not provide this header file, the [source/include](source/include) directory contains [stdint.readme](source/include/stdint.readme), which can be renamed to `stdint.h` to -build the backoffAlgorithm library. +For instance, if the example above is copied to a file named `example.c`, _gcc_ +can be used like so: -For instance, if the example above is copied to a file named `example.c`, *gcc* can be used like so: ```bash gcc -I source/include example.c source/backoff_algorithm.c -o example ./example ``` -*gcc* can also produce an output file to be linked: +_gcc_ can also produce an output file to be linked: + ```bash gcc -I source/include -c source/backoff_algorithm.c ``` @@ -125,9 +146,16 @@ gcc -I source/include -c source/backoff_algorithm.c ## Building unit tests ### Checkout Unity Submodule -By default, the submodules in this repository are configured with `update=none` in [.gitmodules](.gitmodules), to avoid increasing clone time and disk space usage of other repositories (like [amazon-freertos](https://github.com/aws/amazon-freertos) that submodules this repository). -To build unit tests, the submodule dependency of Unity is required. Use the following command to clone the submodule: +By default, the submodules in this repository are configured with `update=none` +in [.gitmodules](.gitmodules), to avoid increasing clone time and disk space +usage of other repositories (like +[amazon-freertos](https://github.com/aws/amazon-freertos) that submodules this +repository). + +To build unit tests, the submodule dependency of Unity is required. Use the +following command to clone the submodule: + ``` git submodule update --checkout --init --recursive test/unit-test/Unity ``` @@ -135,17 +163,18 @@ git submodule update --checkout --init --recursive test/unit-test/Unity ### Platform Prerequisites - For running unit tests - - C89 or later compiler like gcc - - CMake 3.13.0 or later + - C89 or later compiler like gcc + - CMake 3.13.0 or later - For running the coverage target, gcov is additionally required. ### Steps to build Unit Tests -1. Go to the root directory of this repository. (Make sure that the **Unity** submodule is cloned as described [above](#checkout-unity-submodule).) +1. Go to the root directory of this repository. (Make sure that the **Unity** + submodule is cloned as described [above](#checkout-unity-submodule).) 1. Create build directory: `mkdir build && cd build` -1. Run *cmake* while inside build directory: `cmake -S ../test` +1. Run _cmake_ while inside build directory: `cmake -S ../test` 1. Run this command to build the library and unit tests: `make all` @@ -155,4 +184,5 @@ git submodule update --checkout --init --recursive test/unit-test/Unity ## Contributing -See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. +See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on +contributing. diff --git a/cspell.config.yaml b/cspell.config.yaml new file mode 100644 index 0000000..911ce1d --- /dev/null +++ b/cspell.config.yaml @@ -0,0 +1,31 @@ +--- +$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json +version: '0.2' +# Allows things like stringLength +allowCompoundWords: true + +# Read files not to spell check from the git ignore +useGitignore: true + +# Language settings for C +languageSettings: + - caseSensitive: false + enabled: true + languageId: c + locale: "*" + +# Add a dictionary, and the path to the word list +dictionaryDefinitions: + - name: freertos-words + path: '.github/.cSpellWords.txt' + addWords: true + +dictionaries: + - freertos-words + +# Paths and files to ignore +ignorePaths: + - 'dependency' + - 'docs' + - 'ThirdParty' + - 'History.txt' diff --git a/docs/doxygen/config.doxyfile b/docs/doxygen/config.doxyfile index 4bd077b..e5e835a 100644 --- a/docs/doxygen/config.doxyfile +++ b/docs/doxygen/config.doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.9.2 +# Doxyfile 1.9.6 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -12,6 +12,16 @@ # For lists, items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). +# +# Note: +# +# Use doxygen to compare the used configuration file with the template +# configuration file: +# doxygen -x [configFile] +# Use doxygen to compare the used configuration file with the template +# configuration file without replacing the environment variables or CMake type +# replacement variables: +# doxygen -x_noenv [configFile] #--------------------------------------------------------------------------- # Project related configuration options @@ -38,7 +48,7 @@ PROJECT_NAME = backoffAlgorithm # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = v1.2.0 +PROJECT_NUMBER = v1.4.1 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -60,16 +70,28 @@ PROJECT_LOGO = OUTPUT_DIRECTORY = docs/doxygen/output/ -# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- -# directories (in 2 levels) under the output directory of each output format and -# will distribute the generated files over these directories. Enabling this +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 +# sub-directories (in 2 levels) under the output directory of each output format +# and will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where # putting all generated files in the same directory would otherwise causes -# performance problems for the file system. +# performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to +# control the number of sub-directories. # The default value is: NO. CREATE_SUBDIRS = NO +# Controls the number of sub-directories that will be created when +# CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every +# level increment doubles the number of directories, resulting in 4096 +# directories at level 8 which is the default and also the maximum value. The +# sub-directories are organized in 2 levels, the first level always has a fixed +# number of 16 directories. +# Minimum value: 0, maximum value: 8, default value: 8. +# This tag requires that the tag CREATE_SUBDIRS is set to YES. + +CREATE_SUBDIRS_LEVEL = 8 + # If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII # characters to appear in the names of generated files. If set to NO, non-ASCII # characters will be escaped, for example _xE3_x81_x84 will be used for Unicode @@ -81,14 +103,14 @@ ALLOW_UNICODE_NAMES = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. -# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, -# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), -# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, -# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), -# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, -# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, -# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, -# Ukrainian and Vietnamese. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian, +# Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English +# (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek, +# Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with +# English messages), Korean, Korean-en (Korean with English messages), Latvian, +# Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, +# Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, +# Swedish, Turkish, Ukrainian and Vietnamese. # The default value is: English. OUTPUT_LANGUAGE = English @@ -452,7 +474,7 @@ TYPEDEF_HIDES_STRUCT = YES LOOKUP_CACHE_SIZE = 0 -# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use # during processing. When set to 0 doxygen will based this on the number of # cores available in the system. You can set it explicitly to a value larger # than 0 to get more control over the balance between CPU load and processing @@ -546,7 +568,8 @@ HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set # to NO, these classes will be included in the various overviews. This option -# has no effect if EXTRACT_ALL is enabled. +# will also hide undocumented C++ concepts if enabled. This option has no effect +# if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO @@ -577,14 +600,15 @@ INTERNAL_DOCS = NO # filesystem is case sensitive (i.e. it supports files in the same directory # whose names only differ in casing), the option must be set to YES to properly # deal with such files in case they appear in the input. For filesystems that -# are not case sensitive the option should be be set to NO to properly deal with +# are not case sensitive the option should be set to NO to properly deal with # output files written for symbols that only differ in casing, such as for two # classes, one named CLASS and the other named Class, and to also support # references to files without having to specify the exact matching casing. On # Windows (including Cygwin) and MacOS, users should typically set this option # to NO, whereas on Linux or other Unix flavors it should typically be set to # YES. -# The default value is: system dependent. +# Possible values are: SYSTEM, NO and YES. +# The default value is: SYSTEM. CASE_SENSE_NAMES = NO @@ -836,6 +860,14 @@ WARN_IF_INCOMPLETE_DOC = YES WARN_NO_PARAMDOC = NO +# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about +# undocumented enumeration values. If set to NO, doxygen will accept +# undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: NO. + +WARN_IF_UNDOC_ENUM_VAL = NO + # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS # then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but @@ -851,13 +883,27 @@ WARN_AS_ERROR = NO # and the warning text. Optionally the format may contain $version, which will # be replaced by the version of the file (if it could be obtained via # FILE_VERSION_FILTER) +# See also: WARN_LINE_FORMAT # The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" +# In the $text part of the WARN_FORMAT command it is possible that a reference +# to a more specific place is given. To make it easier to jump to this place +# (outside of doxygen) the user can define a custom "cut" / "paste" string. +# Example: +# WARN_LINE_FORMAT = "'vi $file +$line'" +# See also: WARN_FORMAT +# The default value is: at line $line of file $file. + +WARN_LINE_FORMAT = "at line $line of file $file" + # The WARN_LOGFILE tag can be used to specify a file to which warning and error # messages should be written. If left blank the output is written to standard -# error (stderr). +# error (stderr). In case the file specified cannot be opened for writing the +# warning and error messages are written to standard error. When as file - is +# specified the warning and error messages are written to standard output +# (stdout). WARN_LOGFILE = @@ -880,10 +926,21 @@ INPUT = ./docs/doxygen \ # libiconv (or the iconv built into libc) for the transcoding. See the libiconv # documentation (see: # https://www.gnu.org/software/libiconv/) for the list of possible encodings. +# See also: INPUT_FILE_ENCODING # The default value is: UTF-8. INPUT_ENCODING = UTF-8 +# This tag can be used to specify the character encoding of the source files +# that doxygen parses The INPUT_FILE_ENCODING tag can be used to specify +# character encoding on a per file pattern basis. Doxygen will compare the file +# name with each pattern and apply the encoding instead of the default +# INPUT_ENCODING) if there is a match. The character encodings are a list of the +# form: pattern=encoding (like *.php=ISO-8859-1). See cfg_input_encoding +# "INPUT_ENCODING" for further information on supported encodings. + +INPUT_FILE_ENCODING = + # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and # *.h) to filter out the source-files in the directories. @@ -941,7 +998,7 @@ EXCLUDE_PATTERNS = # (namespaces, classes, functions, etc.) that should be excluded from the # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test +# ANamespace::AClass, ANamespace::*Test # # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* @@ -991,6 +1048,11 @@ IMAGE_PATH = # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. # +# Note that doxygen will use the data processed and written to standard output +# for further processing, therefore nothing else, like debug statements or used +# commands (so in case of a Windows batch file always use @echo OFF), should be +# written to standard output. +# # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. @@ -1032,6 +1094,15 @@ FILTER_SOURCE_PATTERNS = USE_MDFILE_AS_MAINPAGE = +# The Fortran standard specifies that for fixed formatted Fortran code all +# characters from position 72 are to be considered as comment. A common +# extension is to allow longer lines before the automatic comment starts. The +# setting FORTRAN_COMMENT_AFTER will also make it possible that longer lines can +# be processed before the automatic comment starts. +# Minimum value: 7, maximum value: 10000, default value: 72. + +FORTRAN_COMMENT_AFTER = 72 + #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- @@ -1118,46 +1189,6 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES -# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the -# clang parser (see: -# http://clang.llvm.org/) for more accurate parsing at the cost of reduced -# performance. This can be particularly helpful with template rich C++ code for -# which doxygen's built-in parser lacks the necessary type information. -# Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse_libclang=ON option for CMake. -# The default value is: NO. - -CLANG_ASSISTED_PARSING = NO - -# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS -# tag is set to YES then doxygen will add the directory of each input to the -# include path. -# The default value is: YES. -# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. - -CLANG_ADD_INC_PATHS = YES - -# If clang assisted parsing is enabled you can provide the compiler with command -# line options that you would normally use when invoking the compiler. Note that -# the include paths will already be set by doxygen for the files and directories -# specified with INPUT and INCLUDE_PATH. -# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. - -CLANG_OPTIONS = - -# If clang assisted parsing is enabled you can provide the clang parser with the -# path to the directory containing a file called compile_commands.json. This -# file is the compilation database (see: -# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the -# options used when the source files were built. This is equivalent to -# specifying the -p option to a clang tool, such as clang-check. These options -# will then be passed to the parser. Any options specified with CLANG_OPTIONS -# will be added as well. -# Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse_libclang=ON option for CMake. - -CLANG_DATABASE_PATH = - #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1169,10 +1200,11 @@ CLANG_DATABASE_PATH = ALPHABETICAL_INDEX = YES -# In case all classes in a project start with a common prefix, all classes will -# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag -# can be used to specify a prefix (or a list of prefixes) that should be ignored -# while generating the index headers. +# The IGNORE_PREFIX tag can be used to specify a prefix (or a list of prefixes) +# that should be ignored while generating the index headers. The IGNORE_PREFIX +# tag works for classes, function and member names. The entity will be placed in +# the alphabetical list under the first letter of the entity name that remains +# after removing the prefix. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = @@ -1251,7 +1283,12 @@ HTML_STYLESHEET = # Doxygen will copy the style sheet files to the output directory. # Note: The order of the extra style sheet files is of importance (e.g. the last # style sheet in the list overrules the setting of the previous ones in the -# list). For an example see the documentation. +# list). +# Note: Since the styling of scrollbars can currently not be overruled in +# Webkit/Chromium, the styling will be left out of the default doxygen.css if +# one or more extra stylesheets have been specified. So if scrollbar +# customization is desired it has to be added explicitly. For an example see the +# documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_STYLESHEET = ./docs/doxygen/style.css @@ -1266,6 +1303,19 @@ HTML_EXTRA_STYLESHEET = ./docs/doxygen/style.css HTML_EXTRA_FILES = +# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output +# should be rendered with a dark or light theme. +# Possible values are: LIGHT always generate light mode output, DARK always +# generate dark mode output, AUTO_LIGHT automatically set the mode according to +# the user preference, use light mode if no preference is set (the default), +# AUTO_DARK automatically set the mode according to the user preference, use +# dark mode if no preference is set and TOGGLE allow to user to switch between +# light and dark mode via a button. +# The default value is: AUTO_LIGHT. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE = AUTO_LIGHT + # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a color-wheel, see @@ -1360,6 +1410,13 @@ GENERATE_DOCSET = NO DOCSET_FEEDNAME = "Doxygen generated docs" +# This tag determines the URL of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDURL = + # This tag specifies a string that should uniquely identify the documentation # set bundle. This should be a reverse domain-name style string, e.g. # com.mycompany.MyDocSet. Doxygen will append .docset to the name. @@ -1564,7 +1621,7 @@ GENERATE_TREEVIEW = YES # area (value NO) or if it should extend to the full height of the window (value # YES). Setting this to YES gives a layout similar to # https://docs.readthedocs.io with more room for contents, but less room for the -# project logo, title, and description. If either GENERATOR_TREEVIEW or +# project logo, title, and description. If either GENERATE_TREEVIEW or # DISABLE_INDEX is set to NO, this option has no effect. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1595,6 +1652,13 @@ TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +# If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email +# addresses. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +OBFUSCATE_EMAILS = YES + # If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg # tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see # https://inkscape.org) to generate formulas as SVG images instead of PNGs for @@ -1615,17 +1679,6 @@ HTML_FORMULA_FORMAT = png FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANSPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES - # The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands # to create new LaTeX commands to be used in formulas as building blocks. See # the section "Including formulas" for details. @@ -2216,7 +2269,8 @@ SEARCH_INCLUDES = YES # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by the -# preprocessor. +# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of +# RECURSIVE has no effect here. # This tag requires that the tag SEARCH_INCLUDES is set to YES. INCLUDE_PATH = @@ -2308,15 +2362,6 @@ EXTERNAL_PAGES = NO # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = YES - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. @@ -2349,35 +2394,50 @@ HAVE_DOT = NO DOT_NUM_THREADS = 0 -# When you want a differently looking font in the dot files that doxygen -# generates you can specify the font name using DOT_FONTNAME. You need to make -# sure dot is able to find the font, which can be done by putting it in a -# standard location or by setting the DOTFONTPATH environment variable or by -# setting DOT_FONTPATH to the directory containing the font. -# The default value is: Helvetica. +# DOT_COMMON_ATTR is common attributes for nodes, edges and labels of +# subgraphs. When you want a differently looking font in the dot files that +# doxygen generates you can specify fontname, fontcolor and fontsize attributes. +# For details please see Node, +# Edge and Graph Attributes specification You need to make sure dot is able +# to find the font, which can be done by putting it in a standard location or by +# setting the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the +# directory containing the font. Default graphviz fontsize is 14. +# The default value is: fontname=Helvetica,fontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTNAME = Helvetica +DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10" -# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of -# dot graphs. -# Minimum value: 4, maximum value: 24, default value: 10. +# DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can +# add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. Complete documentation about +# arrows shapes. +# The default value is: labelfontname=Helvetica,labelfontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTSIZE = 10 +DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10" -# By default doxygen will tell dot to use the default font as specified with -# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set -# the path where dot can find it using this tag. +# DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes +# around nodes set 'shape=plain' or 'shape=plaintext' Shapes specification +# The default value is: shape=box,height=0.2,width=0.4. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" + +# You can set the path where dot can find font specified with fontname in +# DOT_COMMON_ATTR and others dot attributes. # This tag requires that the tag HAVE_DOT is set to YES. DOT_FONTPATH = -# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for -# each documented class showing the direct and indirect inheritance relations. -# Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO. +# If the CLASS_GRAPH tag is set to YES (or GRAPH) then doxygen will generate a +# graph for each documented class showing the direct and indirect inheritance +# relations. In case HAVE_DOT is set as well dot will be used to draw the graph, +# otherwise the built-in generator will be used. If the CLASS_GRAPH tag is set +# to TEXT the direct and indirect inheritance relations will be shown as texts / +# links. +# Possible values are: NO, YES, TEXT and GRAPH. # The default value is: YES. -# This tag requires that the tag HAVE_DOT is set to YES. CLASS_GRAPH = YES @@ -2391,7 +2451,8 @@ CLASS_GRAPH = YES COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for -# groups, showing the direct groups dependencies. +# groups, showing the direct groups dependencies. See also the chapter Grouping +# in the manual. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2506,6 +2567,13 @@ GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES +# The DIR_GRAPH_MAX_DEPTH tag can be used to limit the maximum number of levels +# of child directories generated in directory dependency graphs by dot. +# Minimum value: 1, maximum value: 25, default value: 1. +# This tag requires that the tag DIRECTORY_GRAPH is set to YES. + +DIR_GRAPH_MAX_DEPTH = 1 + # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: @@ -2559,10 +2627,10 @@ MSCFILE_DIRS = DIAFILE_DIRS = # When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the -# path where java can find the plantuml.jar file. If left blank, it is assumed -# PlantUML is not used or called during a preprocessing step. Doxygen will -# generate a warning when it encounters a \startuml command in this case and -# will not generate output for the diagram. +# path where java can find the plantuml.jar file or to the filename of jar file +# to be used. If left blank, it is assumed PlantUML is not used or called during +# a preprocessing step. Doxygen will generate a warning when it encounters a +# \startuml command in this case and will not generate output for the diagram. PLANTUML_JAR_PATH = @@ -2600,18 +2668,6 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not seem -# to support this out of the box. -# -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_TRANSPARENT = NO - # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support @@ -2624,6 +2680,8 @@ DOT_MULTI_TARGETS = NO # If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page # explaining the meaning of the various boxes and arrows in the dot generated # graphs. +# Note: This tag requires that UML_LOOK isn't set, i.e. the doxygen internal +# graphical representation for inheritance and collaboration diagrams is used. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. diff --git a/lexicon.txt b/lexicon.txt deleted file mode 100644 index 6d5a7ed..0000000 --- a/lexicon.txt +++ /dev/null @@ -1,63 +0,0 @@ -api -apis -aws -backoff -backoff -backoffalgorithm -backoffalgorithmretriesexhausted -backoffalgorithmrngfailure -backoffalgorithmsuccess -backoffbase -br -colspan -com -copydoc -defgroup -dns -endif -fd -freertos -gcc -getaddrinfo -github -html -https -ifdef -ifndef -inc -ingroup -iot -iso -longjmp -mainpage -maxattempts -maxbackoff -maxretryattempts -md -min -misra -mockrng -noninfringement -os -param -pcontext -pnextbackoff -posix -pretrycontext -pretryparams -prng -rand -randomvalue -readme -rm -rng -sdk -shouldn -stderr -sublicense -tcp -td -toolchain -tr -trng -usleep diff --git a/manifest.yml b/manifest.yml index a2e6a1f..f7a5e32 100644 --- a/manifest.yml +++ b/manifest.yml @@ -1,5 +1,14 @@ name : "backoffAlgorithm" -version: "v1.2.0" +version: "v1.4.1" description: | "Algorithm for calculating exponential backoff with jitter for network retry attempts.\n" license: "MIT" + +dependencies: + - name: "Unity" + version: v2.6.0 + license: "MIT" + repository: + type: "git" + url: "https://github.com/ThrowTheSwitch/Unity.git" + path: test/unit-test/Unity \ No newline at end of file diff --git a/source/backoff_algorithm.c b/source/backoff_algorithm.c index c08c686..bd8916f 100644 --- a/source/backoff_algorithm.c +++ b/source/backoff_algorithm.c @@ -1,7 +1,9 @@ /* - * backoffAlgorithm v1.2.0 + * backoffAlgorithm v1.4.1 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * + * SPDX-License-Identifier: MIT + * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to diff --git a/source/include/backoff_algorithm.h b/source/include/backoff_algorithm.h index 5b3c9b3..9b72e84 100644 --- a/source/include/backoff_algorithm.h +++ b/source/include/backoff_algorithm.h @@ -1,7 +1,9 @@ /* - * backoffAlgorithm v1.2.0 + * backoffAlgorithm v1.4.1 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * + * SPDX-License-Identifier: MIT + * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index bda37f7..fdb6b95 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required( VERSION 3.13.0 ) project( "backoffAlgorithm unit test" - VERSION 1.0.0 + VERSION 1.4.1 LANGUAGES C ) # Allow the project to be organized into folders. @@ -22,31 +22,36 @@ set( UNIT_TEST_DIR ${MODULE_ROOT_DIR}/test/unit-test CACHE INTERNAL "backoffAlgo set( UNITY_DIR ${UNIT_TEST_DIR}/Unity CACHE INTERNAL "Unity library source directory." ) # Configure options to always show in CMake GUI. -option( BUILD_UNIT_TESTS +option( UNITTEST "Set this to ON to build unit tests. This will clone the required Unity test framework submodule if it is not cloned already." OFF ) +option( COV_ANALYSIS + "Set this to ON to build coverity analysis project." + OFF ) # Set output directories. set( CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin ) set( CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib ) set( CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib ) -# ================================ Coverity Analysis Configuration ================================= - # Include filepaths for source and include. include( ${MODULE_ROOT_DIR}/backoffAlgorithmFilePaths.cmake ) -# Target for Coverity analysis that builds the library. -add_library( coverity_analysis - ${BACKOFF_ALGORITHM_SOURCES} ) +# ================================ Coverity Analysis Configuration ================================= +if( COV_ANALYSIS ) -# Backoff Algorithm library public include path. -target_include_directories( coverity_analysis - PUBLIC - ${BACKOFF_ALGORITHM_INCLUDE_PUBLIC_DIRS} ) + # Target for Coverity analysis that builds the library. + add_library( coverity_analysis + ${BACKOFF_ALGORITHM_SOURCES} ) -# Disable logging/assert() calls when building the Coverity analysis target -target_compile_options(coverity_analysis PUBLIC -DNDEBUG ) + # Backoff Algorithm library public include path. + target_include_directories( coverity_analysis + PUBLIC + ${BACKOFF_ALGORITHM_INCLUDE_PUBLIC_DIRS} ) + + # Disable logging/assert() calls when building the Coverity analysis target + target_compile_options(coverity_analysis PUBLIC -DNDEBUG ) +endif() # ==================================== Unit Test Configuration ==================================== @@ -54,15 +59,18 @@ if(${BUILD_CODE_EXAMPLE}) # Target for code example binary. add_executable( code_example_posix - ${MODULE_ROOT_DIR}/docs/doxygen/code_examples/backoff_algorithm_posix.c ) - - target_link_libraries( code_example_posix coverity_analysis ) + ${MODULE_ROOT_DIR}/docs/doxygen/code_examples/backoff_algorithm_posix.c + ${BACKOFF_ALGORITHM_SOURCES} ) + # Backoff Algorithm library public include path. + target_include_directories( code_example_posix + PUBLIC + ${BACKOFF_ALGORITHM_INCLUDE_PUBLIC_DIRS} ) endif() # ==================================== Unit Test Configuration ==================================== -if(${BUILD_UNIT_TESTS}) +if( UNITTEST ) # Include Unity build configuration. include( unit-test/unity_build.cmake ) @@ -71,7 +79,12 @@ if(${BUILD_UNIT_TESTS}) # if BUILD_CLONE_SUBMODULES configuration is enabled. if( NOT EXISTS ${UNITY_DIR}/src ) # Attempt to clone Unity. - clone_unity() + if( ${BUILD_CLONE_SUBMODULES} ) + clone_unity() + else() + message( FATAL_ERROR "The required submodule Unity does not exist. Either clone it manually, or set BUILD_CLONE_SUBMODULES to 1 to automatically clone it during build." ) + endif() + endif() # Add unit test and coverage configuration. diff --git a/test/unit-test/Unity b/test/unit-test/Unity index 386c540..860062d 160000 --- a/test/unit-test/Unity +++ b/test/unit-test/Unity @@ -1 +1 @@ -Subproject commit 386c540510929c0cf6f7b8d04cb4af40754bb822 +Subproject commit 860062d51b2e8a75d150337b63ca2a472840d13c diff --git a/test/unit-test/backoff_algorithm_utest.c b/test/unit-test/backoff_algorithm_utest.c index 5a2767a..2dfecd4 100644 --- a/test/unit-test/backoff_algorithm_utest.c +++ b/test/unit-test/backoff_algorithm_utest.c @@ -1,7 +1,9 @@ /* - * backoffAlgorithm v1.2.0 + * backoffAlgorithm v1.4.1 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * + * SPDX-License-Identifier: MIT + * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to diff --git a/test/unit-test/catch_assert.h b/test/unit-test/catch_assert.h index 62ae3ea..2c216d3 100644 --- a/test/unit-test/catch_assert.h +++ b/test/unit-test/catch_assert.h @@ -1,7 +1,9 @@ /* - * backoffAlgorithm v1.2.0 + * backoffAlgorithm v1.4.1 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * + * SPDX-License-Identifier: MIT + * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to @@ -42,7 +44,7 @@ #define CATCH_JMPBUF waypoint_ #endif -jmp_buf CATCH_JMPBUF; +static jmp_buf CATCH_JMPBUF; #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wunused-function" diff --git a/tools/coverity/README.md b/tools/coverity/README.md new file mode 100644 index 0000000..c1715a7 --- /dev/null +++ b/tools/coverity/README.md @@ -0,0 +1,79 @@ +# Static code analysis for backoffAlgorithm library +This directory is made for the purpose of statically testing the MISRA C:2012 compliance of backoffAlgorithm using +[Synopsys Coverity](https://www.synopsys.com/software-integrity/security-testing/static-analysis-sast.html) static analysis tool. +To that end, this directory provides a [configuration file](https://github.com/FreeRTOS/backoffAlgorithm/blob/main/tools/coverity/misra.config) to use when +building a binary for the tool to analyze. + +> **Note** +For generating the report as outlined below, we have used Coverity version 2023.6.1. + +For details regarding the suppressed violations in the report (which can be generated using the instructions described below), please +see the [MISRA.md](https://github.com/FreeRTOS/backoffAlgorithm/blob/main/MISRA.md) file. + +## Getting Started +### Prerequisites +You can run this on a platform supported by Coverity. The list and other details can be found [here](https://sig-docs.synopsys.com/polaris/topics/c_coverity-compatible-platforms.html). +To compile and run the Coverity target successfully, you must have the following: + +1. CMake version > 3.13.0 (You can check whether you have this by typing `cmake --version`) +2. GCC compiler + - You can see the downloading and installation instructions [here](https://gcc.gnu.org/install/). +3. Download the repo and include the submodules using the following commands. + - `git clone --recurse-submodules git@github.com:FreeRTOS/backoffAlgorithm.git ./backoffAlgorithm` + - `cd ./backoffAlgorithm` + - `git submodule update --checkout --init --recursive` + +### To build and run coverity: +Go to the root directory of the library and run the following commands in terminal: +1. Update the compiler configuration in Coverity + ~~~ + cov-configure --force --compiler cc --comptype gcc + ~~~ +2. Create the build files using CMake in a `build` directory + ~~~ + cmake -B build -S test -DCOV_ANALYSIS=1 + ~~~ +3. Go to the build directory and copy the coverity configuration file + ~~~ + cd build/ + ~~~ +4. Build the static analysis target + ~~~ + cov-build --emit-complementary-info --dir cov-out make coverity_analysis + ~~~ +5. Go to the Coverity output directory (`cov-out`) and begin Coverity static analysis + ~~~ + cd cov-out/ + cov-analyze --dir . --coding-standard-config ../../tools/coverity/misra.config --tu-pattern "file('.*/source/.*')" + ~~~ +6. Format the errors in HTML format so that it is more readable while removing the test and build directory from the report + ~~~ + cov-format-errors --dir . --file "source" --exclude-files '(/build/|/test/)' --html-output html-out; + ~~~ +7. Format the errors in JSON format to perform a jq query to get a simplified list of any exceptions. + NOTE: A blank output means there are no defects that aren't being suppressed by the config or inline comments. + ~~~ + cov-format-errors --dir . --file "source" --exclude-files '(/build/|/test/)' --json-output-v2 defects.json; + echo -e "\n-------------------------Non-Suppresed Deviations, if any, Listed Below-------------------------\n"; + jq '.issues[] | .events[] | .eventTag ' defects.json | sort | uniq -c | sort -nr; + echo -e "\n-------------------------Non-Suppresed Deviations, if any, Listed Above-------------------------\n"; + ~~~ + +For your convenience the commands above are below to be copy/pasted into a UNIX command friendly terminal. + ~~~ + cov-configure --force --compiler cc --comptype gcc; + cmake -B build -S test -DCOV_ANALYSIS=1; + cd build/; + cov-build --emit-complementary-info --dir cov-out make coverity_analysis; + cd cov-out/ + cov-analyze --dir . --coding-standard-config ../../tools/coverity/misra.config; + cov-format-errors --dir . --file "source" --exclude-files '(/build/|/test/)' --html-output html-out; + cov-format-errors --dir . --file "source" --exclude-files '(/build/|/test/)' --json-output-v2 defects.json; + echo -e "\n-------------------------Non-Suppresed Deviations, if any, Listed Below-------------------------\n"; + jq '.issues[] | .events[] | .eventTag ' defects.json | sort | uniq -c | sort -nr; + echo -e "\n-------------------------Non-Suppresed Deviations, if any, Listed Above-------------------------\n"; + cd ../../; + ~~~ + +You should now have the HTML formatted violations list in a directory named `build/cov-out/html-output`. +With the current configuration and the provided project, you should not see any deviations. \ No newline at end of file diff --git a/tools/coverity/misra.config b/tools/coverity/misra.config index 84a6078..eeb29ec 100644 --- a/tools/coverity/misra.config +++ b/tools/coverity/misra.config @@ -1,26 +1,23 @@ -// MISRA C-2012 Rules - { - version : "2.0", - standard : "c2012", - title: "Coverity MISRA Configuration", - deviations : [ - // Disable the following rules. + "version" : "2.0", + "standard" : "c2012", + "title" : "Coverity MISRA Configuration", + "deviations" : [ { - deviation: "Directive 4.9", - reason: "Allow inclusion of function like macros. Logging is done using function like macros." + "deviation" : "Directive 4.9", + "reason" : "Allow inclusion of function like macros. Logging is done using function like macros." }, { - deviation: "Rule 2.4", - reason: "Allow unused tags. Some compilers warn if types are not tagged." + "deviation" : "Rule 2.4", + "reason" : "Allow unused tags. Some compilers warn if types are not tagged." }, { - deviation: "Rule 3.1", - reason: "Allow nested comments. Documentation blocks contain comments for example code." + "deviation" : "Rule 3.1", + "reason" : "Allow nested comments. Documentation blocks contain comments for example code." }, { - deviation: "Rule 8.7", - reason: "API functions are not used by library. They must be externally visible in order to be used by the application." - }, + "deviation" : "Rule 8.7", + "reason" : "API functions are not used by library. They must be externally visible in order to be used by the application." + } ] }