From 515d3ed0e0a27c2098bc94c12d6f75b315791d42 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Thu, 24 Aug 2023 15:17:17 -0700 Subject: [PATCH 01/10] Use new version of CI-CD Actions --- .github/.cSpellWords.txt | 8 +++ .github/workflows/ci.yml | 127 ++++++++++++++++++++++++++++++--------- cspell.config.yaml | 22 +++++++ source/core_mqtt.c | 2 +- 4 files changed, 128 insertions(+), 31 deletions(-) create mode 100644 .github/.cSpellWords.txt create mode 100644 cspell.config.yaml diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt new file mode 100644 index 000000000..158bf07f9 --- /dev/null +++ b/.github/.cSpellWords.txt @@ -0,0 +1,8 @@ +CMOCK +CMock +Cmock +Coverity +MISRA +Misra +coverity +misra diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b64cd2893..75927cb1d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,10 @@ -name: CI Checks +name: "CI Checks" + +env: + bashPass: \033[32;1mPASSED - + bashInfo: \033[33;1mINFO - + bashFail: \033[31;1mFAILED - + bashEnd: \033[0m on: push: @@ -12,9 +18,14 @@ jobs: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 - - name: Build + uses: actions/checkout@v3 + + - env: + stepName: Build CoreMQTT run: | + # ${{ env.stepName }} + echo -e "::group::${{ env.bashInfo }} ${{ env.stepName }} ${{ env.bashEnd }}" + sudo apt-get install -y lcov cmake -S test -B build/ \ -G "Unix Makefiles" \ @@ -22,61 +33,78 @@ jobs: -DBUILD_CLONE_SUBMODULES=ON \ -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -Werror -DNDEBUG -DLIBRARY_LOG_LEVEL=LOG_DEBUG' make -C build/ all - - name: Test - run: | - cd build/ - ctest -E system --output-on-failure - cd .. - - name: Run Coverage + echo "::endgroup::" + + echo -e "${{ env.bashPass }} ${{env.stepName}} ${{ env.bashEnd }}" + + - name: Run System Tests + run: ctest --test-dir build -E system --output-on-failure + + - env: + stepName: Line and Branch Coverage Build run: | + # ${{ env.stepName }} + echo -e "::group::${{ env.bashInfo }} Build Coverage Target ${{ env.bashEnd }}" + # Build the coverage target make -C build/ coverage - declare -a EXCLUDE=("\*test\*" "\*CMakeCCompilerId\*" "\*mocks\*") - echo ${EXCLUDE[@]} | xargs lcov --rc lcov_branch_coverage=1 -r build/coverage.info -o build/coverage.info + + echo -e "::group::${{ env.bashInfo }} Generate Coverage Report ${{ env.bashEnd }}" + # Generate coverage report, excluding extra directories + lcov --rc lcov_branch_coverage=1 -r build/coverage.info -o build/coverage.info '*test*' '*CMakeCCompilerId*' '*mocks*' + + echo "::endgroup::" lcov --rc lcov_branch_coverage=1 --list build/coverage.info + echo -e "${{ env.bashPass }} ${{env.stepName}} ${{ env.bashEnd }}" + - name: Check Coverage - uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@main + uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@v2 with: - path: ./build/coverage.info + coverage-file: ./build/coverage.info + 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 + uses: FreeRTOS/CI-CD-Github-Actions/complexity@v2 with: path: ./ - horrid_threshold: 10 + horrid_threshold: 12 + doxygen: 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 + uses: FreeRTOS/CI-CD-Github-Actions/doxygen@v2 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 + uses: FreeRTOS/CI-CD-GitHub-Actions/rust-spell-check@v2 with: path: ./ + formatting: - runs-on: ubuntu-20.04 + runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check formatting - uses: FreeRTOS/CI-CD-Github-Actions/formatting@main + uses: FreeRTOS/CI-CD-Github-Actions/formatting@v2 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 @@ -87,37 +115,76 @@ jobs: run: | git-secrets --register-aws git-secrets --scan + custom-standard-c-headers: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 - - name: Build + uses: actions/checkout@v3 + - env: + stepName: Build With Custom Headers run: | + # ${{ env.stepName }} + echo -e "::group::${{ env.bashInfo }} ${{ env.stepName }} ${{ env.bashEnd }}" + + # Copy the custom headers into the build directory mkdir -p override-include cp source/include/stdbool.readme override-include/stdbool.h cp source/include/stdint.readme override-include/stdint.h + + # Build using the custom headers cmake -S test -B build/ \ -G "Unix Makefiles" \ -DBUILD_CLONE_SUBMODULES=ON \ -DCMAKE_C_FLAGS='-Wall -Wextra -I../override-include' make -C build/ coverity_analysis + echo "::endgroup::" + + echo -e "${{ env.bashPass }} ${{ env.stepName }} ${{ env.bashEnd }}" + memory_statistics: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: submodules: 'recursive' - name: Install Python3 - uses: actions/setup-python@v2 + uses: actions/setup-python@v3 with: python-version: '3.11.0' - name: Measure sizes - uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@main + uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@v2 with: 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@v2 + with: + path: ./ + + verify-manifest: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + submodules: true + fetch-depth: 0 + + - name: Run manifest verifier + uses: FreeRTOS/CI-CD-GitHub-Actions/manifest-verifier@v2 + with: + path: ./ + fail-on-incorrect-version: true + proof_ci: + if: ${{ github.event.pull_request }} runs-on: cbmc_ubuntu-latest_64-core steps: - name: Set up CBMC runner diff --git a/cspell.config.yaml b/cspell.config.yaml new file mode 100644 index 000000000..e7d8a56fd --- /dev/null +++ b/cspell.config.yaml @@ -0,0 +1,22 @@ +--- +$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json +version: '0.2' +# Allows things like stringLength +allowCompoundWords: true +useGitignore: true +# Could split this up? And do a dictionary for each repo? +# But feel like if this isn't super slow +# That having just one single dictionary might be nicer? +dictionaryDefinitions: + - name: freertos-words + path: '.github/.cSpellWords.txt' + addWords: true +dictionaries: + - freertos-words +ignorePaths: + - 'node_modules' + - '.cSpellWords.txt' + - 'dependency' + - 'docs' + - 'ThirdParty' + diff --git a/source/core_mqtt.c b/source/core_mqtt.c index 340321636..738572eaf 100644 --- a/source/core_mqtt.c +++ b/source/core_mqtt.c @@ -2630,7 +2630,7 @@ MQTTStatus_t MQTT_InitStatefulQoS( MQTTContext_t * pContext, else if( pContext->appCallback == NULL ) { LogError( ( "MQTT_InitStatefulQoS must be called only after MQTT_Init has" - " been called succesfully.\n" ) ); + " been called successfully.\n" ) ); status = MQTTBadParameter; } else From f6733156eb981cb8b1221f4b98ae80dba8323f8b Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Fri, 25 Aug 2023 03:54:22 -0700 Subject: [PATCH 02/10] Use cSpell spell check, and use ubuntu-20.04 for formatting check --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 75927cb1d..5c6b37e5a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -86,12 +86,12 @@ jobs: - name: Clone This Repo uses: actions/checkout@v3 - name: Run spellings check - uses: FreeRTOS/CI-CD-GitHub-Actions/rust-spell-check@v2 + uses: FreeRTOS/CI-CD-GitHub-Actions/spellings@v2 with: path: ./ formatting: - runs-on: ubuntu-latest + runs-on: ubuntu-20.04 steps: - uses: actions/checkout@v3 - name: Check formatting From 6e414227731aac54a98b2638068fa9ffb6ea90ae Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Fri, 25 Aug 2023 08:25:00 -0700 Subject: [PATCH 03/10] Fix incorrect spellings, add needed words to the word list --- .github/.cSpellWords.txt | 26 +++ README.md | 4 +- lexicon.txt | 439 --------------------------------------- 3 files changed, 28 insertions(+), 441 deletions(-) delete mode 100644 lexicon.txt diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt index 158bf07f9..7fca1fb29 100644 --- a/.github/.cSpellWords.txt +++ b/.github/.cSpellWords.txt @@ -1,8 +1,34 @@ +CBMC +CBOR CMOCK CMock +CSDK Cmock Coverity +DCMOCK +DNDEBUG +DUNITY MISRA +MQTT Misra +UNACKED +UNSUB +UNSUBACK +Wunused +cbmc +cbor +cmock +coremqtt coverity +ctest +getpacketid +isystem +lcov misra +mypy +pylint +pytest +pyyaml +sinclude +unsubscriptions +utest diff --git a/README.md b/README.md index 97e2e0583..5bc04010a 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ See memory requirements for this library [here](./docs/doxygen/include/size_tabl ## MQTT Config File The MQTT client library exposes build configuration macros that are required for building the library. -A list of all the configurations and their default values are defined in [core_mqtt_config_defaults.h](source/include/core_mqtt_config_defaults.h). +A list of all the configurations and their default values are defined in [core_mqtt_config_defaults.h](source/include/core_mqtt_config_defaults.h). To provide custom values for the configuration macros, a custom config file named `core_mqtt_config.h` can be provided by the application to the library. @@ -19,7 +19,7 @@ By default, a `core_mqtt_config.h` custom config is required to build the librar and build the library with default configuration values, provide `MQTT_DO_NOT_USE_CUSTOM_CONFIG` as a compile time preprocessor macro. **Thus, the MQTT library can be built by either**: -* Defining a `core_mqtt_config.h` file in the application, and adding it to the include directories list of the library +* Defining a `core_mqtt_config.h` file in the application, and adding it to the include directories list of the library **OR** * Defining the `MQTT_DO_NOT_USE_CUSTOM_CONFIG` preprocessor macro for the library build. diff --git a/lexicon.txt b/lexicon.txt deleted file mode 100644 index 608b3295a..000000000 --- a/lexicon.txt +++ /dev/null @@ -1,439 +0,0 @@ -ack -acked -acks -addrecord -addtogroup -alt -ansi -api -apis -app -aws -bool -br -bufferlength -bytesorerror -bytesreceived -bytesrecvd -bytesremaining -bytessent -bytessentthisvector -bytestoread -bytestoreceive -bytestorecv -bytestosend -bytestowrite -calculatestateack -calculatestatepublish -calltlsrecvfunc -cb -cbmc -chk -cleansession -clientidentifierlength -cmock -colspan -com -cond -config -configpagestyle -configs -connack -connectinfo -connectpacketsize -const -copydoc -coremqtt -coverity -csdk -css -currentstate -de -defgroup -defragmenting -deserialization -deserializationresult -deserialize -deserializeack -deserialized -deserializepublish -deserializer -deserializers -deserializestatus -deserializing -didn -disconnectpacketsize -doesn -doxygen -dup -emptyindex -endcode -endcond -endif -enum -enums -eventcallback -expectprocessloopcalls -filterindex -findinrecord -fixedbuffer -fn -freertos -gcc -getconnectpacketsize -getdisconnectpacketsize -getincomingpackettypeandlength -getnewpacketid -getpacketid -getpingreqpacketsize -getpublish -getpublishpacketsize -getsubackstatuscodes -getsubscribepacketsize -gettime -gettimefunction -gettimestampms -getunsubscribepacketsize -github -handleincomingack -handleincomingpublish -handlekeepalive -hasn -headersize -html -http -https -ifdef -ifndef -img -inc -incomingpacket -incomingpublish -incomingpublishcount -incomingpublishrecords -ingroup -init -initializeconnectinfo -initializesubscribeinfo -initializewillinfo -int -io -iot -ioveccount -ip -isn -iso -keepaliveintervalsec -keepalivems -keepaliveseconds -lastpackettxtime -linux -logdebug -logerror -loginfo -logwarn -lsb -lwt -mainpage -malloc -managekeepalive -matchtopic -maxrecordcount -md -mdash -memcpy -memset -metadata -mib -min -minimise -misra -mit -modifyincomingpacket -mq -mqtt -mqttbadparameter -mqttbadresponse -mqttconnected -mqttconnectinfo -mqttcontext -mqttdeserializedinfo -mqtteventcallback -mqttfixedbuffer -mqttgetcurrenttimefunc -mqttillegalstate -mqttkeepalivetimeout -mqttneedmorebytes -mqttnodataavailable -mqttnomemory -mqttnotconnected -mqttpacketinfo -mqttpuback -mqttpubackpending -mqttpubacksend -mqttpubacktype -mqttpubcomp -mqttpubcomppending -mqttpubcompsend -mqttpublishdone -mqttpublishinfo -mqttpublishsend -mqttpublishstate -mqttpubrec -mqttpubrecpending -mqttpubrecsend -mqttpubrel -mqttpubrelpending -mqttpubrelsend -mqttqos -mqttrecvfailed -mqttsendfailed -mqttserverrefused -mqttsocket -mqttstatecollision -mqttstatecursor -mqttstatenull -mqttstateoperation -mqttstatus -mqttsubackfailure -mqttsubackstatus -mqttsubacksuccessqos -mqttsubscribeinfo -mqttsuccess -msb -mutex -mynetworkrecvimplementation -mynetworksendimplementation -mytcpsocketcontext -mytlscontext -networkbuffer -networkcontext -networkinterfacereceivestub -networkinterfacesendstub -networkrecv -networksend -newstate -nextpacketid -noninfringement -numcodes -optype -org -os -outgoingpublishes -outgoingpublishcount -outgoingpublishrecords -packetid -packetidentifier -packetsize -packettype -param -paramters -passwordlength -payloadlength -pbuffer -pbuffertosend -pclientidentifier -pcodes -pconnack -pconnectinfo -pcontext -pcurrentstate -pcursor -pdeserializedinfo -pdestination -pexpectparams -pfilter -pfilterindex -pfixedbuffer -pheadersize -pincomingpacket -pincomingpublishrecords -pindex -pingreq -pingreqs -pingreqsendtimems -pingresp -pingresps -piovec -pismatch -plaintext -pmatch -pmessage -pmqttcontext -pmqttheader -pnameindex -pnetworkbuffer -pnetworkcontext -pnetworkinterface -pnewstate -png -posix -poutgoingpublishrecords -ppacketid -ppacketidentifier -ppacketinfo -ppacketsize -ppassword -ppayload -ppayloadsize -ppayloadstart -ppingresp -ppubinfo -ppublishinfo -pqos -pre -premainingdata -premaininglength -presendpublish -printf -processloop -processloopstatus -psessionpresent -psource -pstate -pstatusstart -psuback -psubackpacket -psubscribeinfo -psubscribes -psubscription -psubscriptionlist -ptopic -ptopicfilter -ptopicname -ptotalmessagelength -ptr -ptransport -ptransportinterface -puback -pubacks -pubcomp -pubcomps -publishflags -publishinfo -publishpacketid -publishstate -publishtoresend -pubrec -pubrecs -pubrel -pubrels -pubreltoresend -pusername -pwillinfo -qos -readfunc -receiveincomingpacket -receiveloop -receivepacket -recordcount -recordindex -recv -recvexact -recvfunc -reestablishment -remaininglength -remainingtime -remainingtimems -resending -reservestate -responsecode -rm -rx -sdk -searchstates -sendpacket -sendpublish -sendpublishacks -serializeack -serializeconnect -serializeconnectpacket -serializedisconnect -serializedlength -serializedpasswordlength -serializedpayloadlength -serializedtopiclength -serializedusernamelength -serializepayload -serializepingreq -serializepublish -serializepublishheader -serializestatus -serializesubscribe -serializeunsubscribe -sessionpresent -shoulddelete -shouldn -sizeof -someclientid -somenetworkinterface -somepassword -sometransportcontext -someusername -sourcelength -spdx -src -stateafterdeserialize -stateafterserialize -statuscount -strerror -strlen -struct -structs -suback -sublicense -subscribeinfo -subscriptioncount -subscriptionlist -subscriptiontype -sys -tcp -tcpsocket -tcpsocketcontext -td -testcase -timeoutms -tls -tlscontext -tlsrecv -tlsrecvcount -tlssend -toolchain -topicfilterlength -topicnamelength -totalmessagelength -tr -transportcallback -transportinterface -transportpage -transportrecv -transportsectionimplementation -transportsectionoverview -transportsend -transportsendnobytes -transportstruct -tx -typename -uint -un -unacked -unsuback -unsubscribelist -updatedlength -updatestateack -updatestatepublish -updatestatestatus -usercallback -usernamelength -utf -validatesubscribeunsubscribeparams -validator -waitingforpingresp -willinfo -writev -xa -xb -xc -xd -xe -xf From d00d2b3ba051397d488243dcda73f4bd18f9ea84 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Wed, 30 Aug 2023 15:29:06 -0700 Subject: [PATCH 04/10] Use the new version of the cspell.config.yaml --- cspell.config.yaml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/cspell.config.yaml b/cspell.config.yaml index e7d8a56fd..331f137e1 100644 --- a/cspell.config.yaml +++ b/cspell.config.yaml @@ -4,6 +4,12 @@ version: '0.2' # Allows things like stringLength allowCompoundWords: true useGitignore: true +languageSettings: + - allowCompoundWords: true + caseSensitive: false + enabled: true + languageId: c + locale: "*" # Could split this up? And do a dictionary for each repo? # But feel like if this isn't super slow # That having just one single dictionary might be nicer? @@ -14,9 +20,8 @@ dictionaryDefinitions: dictionaries: - freertos-words ignorePaths: - - 'node_modules' - '.cSpellWords.txt' - 'dependency' - 'docs' - 'ThirdParty' - + - 'History.txt' From 7c7b2db240f184c269a87a129426b52b14acb539 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Thu, 31 Aug 2023 14:19:22 -0700 Subject: [PATCH 05/10] Update the cspell config file to clean it up a bit --- cspell.config.yaml | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/cspell.config.yaml b/cspell.config.yaml index 331f137e1..911ce1d8f 100644 --- a/cspell.config.yaml +++ b/cspell.config.yaml @@ -3,24 +3,28 @@ $schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell 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: - - allowCompoundWords: true - caseSensitive: false + - caseSensitive: false enabled: true languageId: c locale: "*" -# Could split this up? And do a dictionary for each repo? -# But feel like if this isn't super slow -# That having just one single dictionary might be nicer? + +# 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: - - '.cSpellWords.txt' - 'dependency' - 'docs' - 'ThirdParty' From af4155b4e23bf5895fcc7fa11df0b8b4e4d872c2 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Fri, 1 Sep 2023 09:31:48 -0700 Subject: [PATCH 06/10] Use merged version of some actions --- .github/workflows/ci.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5c6b37e5a..bac0ed91d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -57,7 +57,7 @@ jobs: echo -e "${{ env.bashPass }} ${{env.stepName}} ${{ env.bashEnd }}" - name: Check Coverage - uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@v2 + uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@main with: coverage-file: ./build/coverage.info @@ -66,7 +66,7 @@ jobs: steps: - uses: actions/checkout@v3 - name: Check complexity - uses: FreeRTOS/CI-CD-Github-Actions/complexity@v2 + uses: FreeRTOS/CI-CD-Github-Actions/complexity@main with: path: ./ horrid_threshold: 12 @@ -178,7 +178,7 @@ jobs: fetch-depth: 0 - name: Run manifest verifier - uses: FreeRTOS/CI-CD-GitHub-Actions/manifest-verifier@v2 + uses: FreeRTOS/CI-CD-GitHub-Actions/manifest-verifier@main with: path: ./ fail-on-incorrect-version: true From a73470fc9a8441d88d088e21e47a5325d32f9877 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Fri, 1 Sep 2023 18:22:11 -0700 Subject: [PATCH 07/10] Use merged mainline version of formatting --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bac0ed91d..ed11137ed 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -95,7 +95,7 @@ jobs: steps: - uses: actions/checkout@v3 - name: Check formatting - uses: FreeRTOS/CI-CD-Github-Actions/formatting@v2 + uses: FreeRTOS/CI-CD-Github-Actions/formatting@main with: path: ./ From 20791626a24ee17747b2d10d7dab8b3ea86e5092 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Sat, 2 Sep 2023 16:09:32 -0700 Subject: [PATCH 08/10] Update the README file --- README.md | 184 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 128 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 5bc04010a..46096af2e 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,65 @@ # coreMQTT Client Library -This repository contains the coreMQTT library that has been optimized for a low memory footprint. The coreMQTT library is compliant with the [MQTT 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) standard. It has no dependencies on any additional libraries other than the standard C library, a customer-implemented network transport interface, and *optionally* a user-implemented platform time function. This library is distributed under the [MIT Open Source License](LICENSE). - -This library has gone through code quality checks including verification that no function has a [GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) score over 8, and checks against deviations from mandatory rules in the [MISRA coding standard](https://www.misra.org.uk). Deviations from the MISRA C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This library has also undergone both static code analysis from [Coverity static analysis](https://scan.coverity.com/), and validation of memory safety through the [CBMC automated reasoning tool](https://www.cprover.org/cbmc/). - -See memory requirements for this library [here](./docs/doxygen/include/size_table.md). - -**coreMQTT v2.1.0 [source code](https://github.com/FreeRTOS/coreMQTT/tree/v2.1.0/source) is part of the [FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) release.** +**[API Documentation Pages for current and previous releases of this library can be found here](https://freertos.github.io/coreMQTT/)** + +This repository contains the coreMQTT library that has been optimized for a low +memory footprint. The coreMQTT library is compliant with the +[MQTT 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) +standard. It has no dependencies on any additional libraries other than the +standard C library, a customer-implemented network transport interface, and +_optionally_ a user-implemented platform time function. This library is +distributed under the [MIT Open Source License](LICENSE). + +This library has gone through code quality checks including verification that no +function has a +[GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) +score over 8, and checks against deviations from mandatory rules in the +[MISRA coding standard](https://www.misra.org.uk). Deviations from the MISRA +C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This +library has also undergone both static code analysis from +[Coverity static analysis](https://scan.coverity.com/), and validation of memory +safety through the +[CBMC automated reasoning tool](https://www.cprover.org/cbmc/). + +See memory requirements for this library +[here](./docs/doxygen/include/size_table.md). + +**coreMQTT v2.1.0 +[source code](https://github.com/FreeRTOS/coreMQTT/tree/v2.1.0/source) is part +of the +[FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) +release.** ## MQTT Config File -The MQTT client library exposes build configuration macros that are required for building the library. -A list of all the configurations and their default values are defined in [core_mqtt_config_defaults.h](source/include/core_mqtt_config_defaults.h). -To provide custom values for the configuration macros, a custom config file named `core_mqtt_config.h` can be -provided by the application to the library. +The MQTT client library exposes build configuration macros that are required for +building the library. A list of all the configurations and their default values +are defined in +[core_mqtt_config_defaults.h](source/include/core_mqtt_config_defaults.h). To +provide custom values for the configuration macros, a custom config file named +`core_mqtt_config.h` can be provided by the application to the library. -By default, a `core_mqtt_config.h` custom config is required to build the library. To disable this requirement -and build the library with default configuration values, provide `MQTT_DO_NOT_USE_CUSTOM_CONFIG` as a compile time preprocessor macro. +By default, a `core_mqtt_config.h` custom config is required to build the +library. To disable this requirement and build the library with default +configuration values, provide `MQTT_DO_NOT_USE_CUSTOM_CONFIG` as a compile time +preprocessor macro. **Thus, the MQTT library can be built by either**: -* Defining a `core_mqtt_config.h` file in the application, and adding it to the include directories list of the library -**OR** -* Defining the `MQTT_DO_NOT_USE_CUSTOM_CONFIG` preprocessor macro for the library build. + +- Defining a `core_mqtt_config.h` file in the application, and adding it to the + include directories list of the library + **OR** +- Defining the `MQTT_DO_NOT_USE_CUSTOM_CONFIG` preprocessor macro for the + library build. ## Sending metrics to AWS IoT -When establishing a connection with AWS IoT, users can optionally report the Operating System, Hardware Platform and MQTT client version information of their device to AWS. This information can help AWS IoT provide faster issue resolution and technical support. If users want to report this information, they can send a specially formatted string (see below) in the username field of the MQTT CONNECT packet. +When establishing a connection with AWS IoT, users can optionally report the +Operating System, Hardware Platform and MQTT client version information of their +device to AWS. This information can help AWS IoT provide faster issue resolution +and technical support. If users want to report this information, they can send a +specially formatted string (see below) in the username field of the MQTT CONNECT +packet. Format @@ -37,17 +71,24 @@ The format of the username string with metrics is: Where -* is the actual username used for authentication, if username and password are used for authentication. When username and password based authentication is not used, this -is an empty value. -* is the Operating System the application is running on (e.g. FreeRTOS) -* is the version number of the Operating System (e.g. V10.4.3) -* is the Hardware Platform the application is running on (e.g. WinSim) -* is the MQTT Client library being used (e.g. coreMQTT) -* is the version of the MQTT Client library being used (e.g. 1.0.2) +- is the actual username used for authentication, if username + and password are used for authentication. When username and password based + authentication is not used, this is an empty value. +- is the Operating System the application is running on (e.g. + FreeRTOS) +- is the version number of the Operating System (e.g. V10.4.3) +- is the Hardware Platform the application is running on + (e.g. WinSim) +- is the MQTT Client library being used (e.g. coreMQTT) +- is the version of the MQTT Client library being used + (e.g. 1.0.2) Example -* Actual_Username = “iotuser”, OS_Name = FreeRTOS, OS_Version = V10.4.3, Hardware_Platform_Name = WinSim, MQTT_Library_Name = coremqtt, MQTT_Library_version = 2.1.0. If username is not used, then “iotuser” can be removed. +- Actual_Username = “iotuser”, OS_Name = FreeRTOS, OS_Version = V10.4.3, + Hardware_Platform_Name = WinSim, MQTT_Library_Name = coremqtt, + MQTT_Library_version = 2.1.0. If username is not used, then “iotuser” can be + removed. ``` /* Username string: @@ -70,24 +111,43 @@ mqttStatus = MQTT_Connect( pMqttContext, &connectInfo, NULL, CONNACK_RECV_TIMEOU ## Upgrading to v2.0.0 and above -With coreMQTT versions >=v2.0.0, there are breaking changes. Please refer to the [coreMQTT version >=v2.0.0 Migration Guide](MigrationGuide.md). +With coreMQTT versions >=v2.0.0, there are breaking changes. Please refer to the +[coreMQTT version >=v2.0.0 Migration Guide](MigrationGuide.md). ## Building the Library -The [mqttFilePaths.cmake](mqttFilePaths.cmake) file contains the information of all source files and the header include path required to build the MQTT library. +The [mqttFilePaths.cmake](mqttFilePaths.cmake) file contains the information of +all source files and the header include path required to build the MQTT library. -Additionally, the MQTT library requires two header files that are not part of the ISO C90 standard library, `stdbool.h` and `stdint.h`. For compilers that do not provide these header files, the [source/include](source/include) directory contains the files [stdbool.readme](source/include/stdbool.readme) and [stdint.readme](source/include/stdint.readme), which can be renamed to `stdbool.h` and `stdint.h`, respectively, to provide the type definitions required by MQTT. +Additionally, the MQTT library requires two header files that are not part of +the ISO C90 standard library, `stdbool.h` and `stdint.h`. For compilers that do +not provide these header files, the [source/include](source/include) directory +contains the files [stdbool.readme](source/include/stdbool.readme) and +[stdint.readme](source/include/stdint.readme), which can be renamed to +`stdbool.h` and `stdint.h`, respectively, to provide the type definitions +required by MQTT. -As mentioned in the previous section, either a custom config file (i.e. `core_mqtt_config.h`) OR `MQTT_DO_NOT_USE_CUSTOM_CONFIG` macro needs to be provided to build the MQTT library. +As mentioned in the previous section, either a custom config file (i.e. +`core_mqtt_config.h`) OR `MQTT_DO_NOT_USE_CUSTOM_CONFIG` macro needs to be +provided to build the MQTT library. -For a CMake example of building the MQTT library with the `mqttFilePaths.cmake` file, refer to the `coverity_analysis` library target in [test/CMakeLists.txt](test/CMakeLists.txt) file. +For a CMake example of building the MQTT library with the `mqttFilePaths.cmake` +file, refer to the `coverity_analysis` library target in +[test/CMakeLists.txt](test/CMakeLists.txt) file. ## Building Unit Tests ### Checkout CMock 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 CMock 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 CMock is required. Use the +following command to clone the submodule: + ``` git submodule update --checkout --init --recursive test/unit-test/CMock ``` @@ -97,21 +157,26 @@ git submodule update --checkout --init --recursive test/unit-test/CMock - Docker or the following: + - For running unit tests - - **C90 compiler** like gcc - - **CMake 3.13.0 or later** - - **Ruby 2.0.0 or later** is additionally required for the CMock test framework (that we use). -- For running the coverage target, **gcov** and **lcov** are additionally required. + - **C90 compiler** like gcc + - **CMake 3.13.0 or later** + - **Ruby 2.0.0 or later** is additionally required for the CMock test + framework (that we use). +- For running the coverage target, **gcov** and **lcov** are additionally + required. ### Steps to build **Unit Tests** 1. If using docker, launch the container: - 1. `docker build -t coremqtt .` - 1. `docker run -it -v "$PWD":/workspaces/coreMQTT -w /workspaces/coreMQTT coremqtt` -1. Go to the root directory of this repository. (Make sure that the **CMock** submodule is cloned as described [above](#checkout-cmock-submodule)) + 1. `docker build -t coremqtt .` + 1. `docker run -it -v "$PWD":/workspaces/coreMQTT -w /workspaces/coreMQTT coremqtt` -1. Run the *cmake* command: `cmake -S test -B build` +1. Go to the root directory of this repository. (Make sure that the **CMock** + submodule is cloned as described [above](#checkout-cmock-submodule)) + +1. Run the _cmake_ command: `cmake -S test -B build` 1. Run this command to build the library and unit tests: `make -C build all` @@ -121,40 +186,46 @@ or the following: ## CBMC -To learn more about CBMC and proofs specifically, review the training material [here](https://model-checking.github.io/cbmc-training). +To learn more about CBMC and proofs specifically, review the training material +[here](https://model-checking.github.io/cbmc-training). The `test/cbmc/proofs` directory contains CBMC proofs. -In order to run these proofs you will need to install CBMC and other tools by following the instructions [here](https://model-checking.github.io/cbmc-training/installation.html). +In order to run these proofs you will need to install CBMC and other tools by +following the instructions +[here](https://model-checking.github.io/cbmc-training/installation.html). ## Reference examples -Please refer to the demos of the MQTT client library in the following locations for reference examples on POSIX and FreeRTOS platforms: - -| Platform | Location | Transport Interface Implementation | -| :-: | :-: | :-: | -| POSIX | [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main/demos/mqtt) | POSIX sockets for TCP/IP and OpenSSL for TLS stack -| FreeRTOS | [FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo) | FreeRTOS+TCP for TCP/IP and mbedTLS for TLS stack | -| FreeRTOS | [FreeRTOS AWS Reference Integrations](https://github.com/aws/amazon-freertos/tree/main/demos/coreMQTT) | Based on Secure Sockets Abstraction | +Please refer to the demos of the MQTT client library in the following locations +for reference examples on POSIX and FreeRTOS platforms: +| Platform | Location | Transport Interface Implementation | +| :------: | :------------------------------------------------------------------------------------------------------------: | :------------------------------------------------: | +| POSIX | [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main/demos/mqtt) | POSIX sockets for TCP/IP and OpenSSL for TLS stack | +| FreeRTOS | [FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo) | FreeRTOS+TCP for TCP/IP and mbedTLS for TLS stack | +| FreeRTOS | [FreeRTOS AWS Reference Integrations](https://github.com/aws/amazon-freertos/tree/main/demos/coreMQTT) | Based on Secure Sockets Abstraction | ## Documentation ### Existing Documentation -For pre-generated documentation, please see the documentation linked in the locations below: +For pre-generated documentation, please see the documentation linked in the +locations below: -| Location | -| :-: | +| Location | +| :------------------------------------------------------------------------------------------------------------------: | | [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C#releases-and-documentation) | -| [FreeRTOS.org](https://freertos.org/Documentation/api-ref/coreMQTT/docs/doxygen/output/html/index.html) | +| [FreeRTOS.org](https://freertos.org/Documentation/api-ref/coreMQTT/docs/doxygen/output/html/index.html) | -Note that the latest included version of coreMQTT may differ across repositories. +Note that the latest included version of coreMQTT may differ across +repositories. ### Generating Documentation The Doxygen references were created using Doxygen version 1.9.2. To generate the -Doxygen pages, please run the following command from the root of this repository: +Doxygen pages, please run the following command from the root of this +repository: ```shell doxygen docs/doxygen/config.doxyfile @@ -162,4 +233,5 @@ doxygen docs/doxygen/config.doxyfile ## Contributing -See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. +See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on +contributing. From fc3c00367c697d4d442695f1ec7c60bc9ed79112 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Tue, 5 Sep 2023 10:26:26 -0700 Subject: [PATCH 09/10] Add in bot formatting action --- .github/workflows/formatting.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/workflows/formatting.yml diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml new file mode 100644 index 000000000..f7141e741 --- /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@v2 + id: check-formatting From 8882791374bb72d0adfb209ec7da6c57604cb799 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Tue, 5 Sep 2023 13:55:41 -0700 Subject: [PATCH 10/10] Update to use merged mainline actions, use checkout@v3 instead of checkout@v2 on all jobs --- .github/workflows/ci.yml | 8 ++++---- .github/workflows/formatting.yml | 2 +- .github/workflows/release.yml | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed11137ed..a08d0ca74 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -76,7 +76,7 @@ jobs: steps: - uses: actions/checkout@v3 - name: Run doxygen build - uses: FreeRTOS/CI-CD-Github-Actions/doxygen@v2 + uses: FreeRTOS/CI-CD-Github-Actions/doxygen@main with: path: ./ @@ -86,7 +86,7 @@ jobs: - name: Clone This Repo uses: actions/checkout@v3 - name: Run spellings check - uses: FreeRTOS/CI-CD-GitHub-Actions/spellings@v2 + uses: FreeRTOS/CI-CD-Github-Actions/spellings@main with: path: ./ @@ -153,7 +153,7 @@ jobs: with: python-version: '3.11.0' - name: Measure sizes - uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@v2 + uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@main with: config: .github/memory_statistics_config.json check_against: docs/doxygen/include/size_table.md @@ -165,7 +165,7 @@ jobs: - name: Check Links env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - uses: FreeRTOS/CI-CD-Github-Actions/link-verifier@v2 + uses: FreeRTOS/CI-CD-Github-Actions/link-verifier@main with: path: ./ diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml index f7141e741..8257addac 100644 --- a/.github/workflows/formatting.yml +++ b/.github/workflows/formatting.yml @@ -19,5 +19,5 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Apply Formatting Fix - uses: FreeRTOS/CI-CD-Github-Actions/formatting-bot@v2 + 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 adae984b7..e4078defc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -22,7 +22,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Check if tag exists run: | git fetch origin @@ -49,7 +49,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: ${{ github.event.inputs.commit_id }} - name: Configure git identity @@ -87,7 +87,7 @@ jobs: - name: Install ZIP tools run: sudo apt-get install zip unzip - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: ${{ github.event.inputs.commit_id }} path: coreMQTT