From 5051b09e2d416b1253bca5def9828085cf3e82b8 Mon Sep 17 00:00:00 2001 From: xalbertoisorna Date: Thu, 21 May 2026 16:55:18 +0100 Subject: [PATCH 1/9] Add vx4 and prepare release 0.2.7 --- .gitignore | 3 +- CHANGELOG.rst | 4 +- Jenkinsfile | 158 ++++++++++++++++---------- LICENSE.rst | 84 ++++++++++++++ README.rst | 64 +++++++++++ doc/Doxyfile.inc | 5 + doc/exclude_patterns.inc | 8 ++ doc/rst/lib_unity.rst | 74 ++++++++++++ examples/basic/CMakeLists.txt | 15 +++ examples/basic/src/main.c | 17 +++ examples/basic/src/test_basic.c | 33 ++++++ examples/uut_and_tests/CMakeLists.txt | 2 +- lib_unity/lib_build_info.cmake | 2 +- settings.yml | 27 +++++ 14 files changed, 428 insertions(+), 68 deletions(-) create mode 100644 LICENSE.rst create mode 100644 README.rst create mode 100644 doc/Doxyfile.inc create mode 100644 doc/exclude_patterns.inc create mode 100644 doc/rst/lib_unity.rst create mode 100644 examples/basic/CMakeLists.txt create mode 100644 examples/basic/src/main.c create mode 100644 examples/basic/src/test_basic.c create mode 100644 settings.yml diff --git a/.gitignore b/.gitignore index 196ccb9..84191e9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ __pycache__/ build/ bin/ - +_build/ +dist/ .venv*/ diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 46c72d9..df31b15 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,8 +1,8 @@ lib_unity change log ==================== -UNRELEASED ----------- +2.7.0 +----- * ADDED: Initial upport for vx4 builds. * CHANGED: Tools version to 15.3.1. diff --git a/Jenkinsfile b/Jenkinsfile index c71f47c..8f3c415 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -3,6 +3,12 @@ @Library('xmos_jenkins_shared_library@v0.52.0') _ getApproval() + +def getRepoNameFromScm() { + def (server, user, repo) = extractFromScmUrl() + return repo +} + pipeline { agent none @@ -13,9 +19,14 @@ pipeline { defaultValue: '15.3.1', description: 'XTC tools version' ) + string( + name: 'TOOLS_VX4_VERSION', + defaultValue: '-j --repo arch_vx_slipgate -b develop -a XTC 1184', + description: 'XTC Slipgate tools version' + ) string( name: 'XMOSDOC_VERSION', - defaultValue: 'v8.2.0', + defaultValue: 'v8.1.0', description: 'xmosdoc version' ) } @@ -28,80 +39,101 @@ pipeline { stages { stage('🏗️ Build and test') { - agent { - label 'x86_64 && linux && documentation' - } - - stages { - stage('Checkout') { - steps { - - println "Stage running on ${env.NODE_NAME}" - - script { - def (server, user, repo) = extractFromScmUrl() - env.REPO_NAME = repo + parallel { + stage('Target (XS3)') { + agent { label 'x86_64 && linux && documentation' } + stages { + stage('Checkout') { + steps { + println "Stage running on ${env.NODE_NAME}" + script {env.REPO_NAME = getRepoNameFromScm()} + dir(REPO_NAME){ + checkoutScmShallow() + sh "git submodule update --init --recursive" + createVenv(reqFile: "requirements.txt") + } + } } - dir(REPO_NAME){ - checkoutScmShallow() - sh "git submodule update --init --recursive" - createVenv(reqFile: "requirements.txt") + stage('Examples build') { + steps { + dir("${REPO_NAME}/examples") { + withTools(params.TOOLS_VERSION) { + xcoreBuild() + } + } + } } - } - } - stage('Examples build') { - steps { - dir("${REPO_NAME}/examples") { - xcoreBuild() + stage('Repo checks') { + steps { + warnError("Repo checks failed") + { + runRepoChecks("${WORKSPACE}/${REPO_NAME}") + } + } } - } - } - - // TODO: add checks - // stage('Repo checks') { - // steps { - // warnError("Repo checks failed") - // { - // runRepoChecks("${WORKSPACE}/${REPO_NAME}") - // } - // } - // } - // TODO: add docs - // stage('Doc build') { - // steps { - // dir(REPO_NAME) { - // buildDocs() - // } - // } - // } + stage('Doc build') { + steps { + dir(REPO_NAME) { + buildDocs() + } + } + } - stage('Tests') { - steps { - dir("${REPO_NAME}/examples/uut_and_tests") { - withTools(params.TOOLS_VERSION) { - withVenv { - runPytest() + stage('Tests') { + steps { + dir("${REPO_NAME}/examples/uut_and_tests") { + withTools(params.TOOLS_VERSION) { + withVenv { + runPytest() + } + } } } } - } - } - stage("Archive sandbox") { - steps { - archiveSandbox(REPO_NAME) + stage("Archive sandbox") { + steps { + archiveSandbox(REPO_NAME) + } + } + } // stages + post { + cleanup { + xcoreCleanSandbox() + } } - } - } // stages - post { - cleanup { - xcoreCleanSandbox() - } - } - } // stage 'Build and test' + } // XS3 + + stage('Target (VX4)') { + agent { label 'vx4' } + stages { + stage("Checkout and Build") { + steps { + script {env.REPO_NAME = getRepoNameFromScm()} + dir(REPO_NAME){ + checkoutScmShallow() + sh "git submodule update --init --recursive" + createVenv(reqFile: "requirements.txt") + dir("examples") { + withTools(params.TOOLS_VX4_VERSION) { + xcoreBuild(toolsVersion: params.TOOLS_VX4_VERSION) + } + } + } // dir(REPO_NAME) + } // steps + } // stage("Checkout and Build") + } // stages + post { + cleanup { + xcoreCleanSandbox() + } + } // post + } // VX4 + } // parallel + } // stage('Build and test') stage('🚀 Release') { when { diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 0000000..ca48f20 --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,84 @@ +******************************* +XMOS PUBLIC LICENCE: Version 1 +******************************* + +Subject to the conditions and limitations below, permission is hereby granted by XMOS LIMITED (“XMOS”), free of charge, to any person or entity obtaining a copy of the XMOS Software. + +**1. Definitions** + +**“Applicable Patent Rights”** means: (a) where XMOS is the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to XMOS and (ii) that cover subject matter contained in the Software, but only to the extent it is necessary to use, reproduce or distribute the Software without infringement; and (b) where you are the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to you and (ii) that cover the subject matter contained in your Derivatives, taken alone or in combination with the Software. + +**“Compiled Code”** means any compiled, binary, machine readable or executable version of the Source Code. + +**“Contributor”** means any person or entity that creates or contributes to the creation of Derivatives. + +**“Derivatives”** means any addition to, deletion from and/or change to the substance, structure of the Software, any previous Derivatives, the combination of the Derivatives and the Software and/or any respective portions thereof. + +**“Source Code”** means the human readable code that is suitable for making modifications but excluding any Compiled Code. + +**“Software”** means the software and associated documentation files which XMOS makes available and which contain a notice identifying the software as original XMOS software and referring to the software being subject to the terms of this XMOS Public Licence. + +This Licence refers to XMOS Software and does not relate to any XMOS hardware or devices which are protected by intellectual property rights (including patent and trade marks) which may be sold to you under a separate agreement. + + +**2. Licence** + +**Permitted Uses, Conditions and Restrictions.** Subject to the conditions below, XMOS grants you a worldwide, royalty free, non-exclusive licence, to the extent of any Patent Rights to do the following: + +2.1 **Unmodified Software.** You may use, copy, display, publish, distribute and make available unmodified copies of the Software: + +2.1.1 for personal or academic, non-commercial purposes; or + +2.1.2 for commercial purposes provided the Software is at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.1.1 and 2.1.2): + +(a) you must retain and reproduce in all copies of the Software the copyright and proprietary notices and disclaimers of XMOS as they appear in the Software, and keep intact all notices and disclaimers in the Software files that refer to this Licence; and + +(b) you must include a copy of this Licence with every copy of the Software and documentation you publish, distribute and make available and you may not offer or impose any terms on such Software that alter or restrict this Licence or the intent of such Licence, except as permitted below (Additional Terms). + +The licence above does not include any Compiled Code which XMOS may make available under a separate support and licence agreement. + +2.2 **Derivatives.** You may create and modify Derivatives and use, copy, display, publish, distribute and make available Derivatives: + +2.2.1 for personal or academic, non-commercial purposes; or + +2.2.2 for commercial purposes, provided the Derivatives are at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.2.1 and 2.2.2): + +(a) you must comply with the terms of clause 2.1 with respect to the Derivatives; + +(b) you must copy (to the extent it doesn’t already exist) the notice below in each file of the Derivatives, and ensure all the modified files carry prominent notices stating that you have changed the files and the date of any change; and + +(c) if you sublicence, distribute or otherwise make the Software and/or the Derivatives available for commercial purposes, you must provide that the Software and Derivatives are at all times used on a device designed, licensed or developed by XMOS. + +Without limitation to these terms and clause 3 below, the Source Code and Compiled Code to your Derivatives may at your discretion (but without obligation) be released, copied, displayed, published, distributed and made available; and if you elect to do so, it must be under the terms of this Licence including the terms of the licence at clauses 2.2.1, 2.2.2 and clause 3 below. + +2.3 **Distribution of Executable Versions.** If you distribute or make available Derivatives, you must include a prominent notice in the code itself as well as in all related documentation, stating that the Source Code of the Software from which the Derivatives are based is available under the terms of this Licence, with information on how and where to obtain such Source Code. + +**3. Your Grant of Rights.** In consideration and as a condition to this Licence, you grant to any person or entity receiving or distributing any Derivatives, a non-exclusive, royalty free, perpetual, irrevocable license under your Applicable Patent Rights and all other intellectual property rights owned or controlled by you, to use, copy, display, publish, distribute and make available your Derivatives of the same scope and extent as XMOS’s licence under clause 2.2 above. + +**4. Combined Products.** You may create a combined product by combining Software, Derivatives and other code not covered by this Licence as a single application or product. In such instance, you must comply with the requirements of this Licence for any portion of the Software and/or Derivatives. + +**5. Additional Terms.** You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations and/or other rights consistent with the term of this Licence (“Additional Terms”) to any legitimate recipients of the Software and/or Derivatives. The terms on which you provide such Additional Terms are on your sole responsibility and you shall indemnify, defend and hold XMOS harmless against any claims asserted against XMOS. + +**6. New Versions.** XMOS may publish revised and/or new versions of this Licence from time to time to accommodate changes to the Licence terms, new versions, updates and bug fixes of the Software. Each version will be given a distinguishing version number. Once Software has been published under a particular version of this Licence, you may continue to use it under the terms of that version. You may also choose to use the latest version of the Software under any subsequent version published by XMOS. Only XMOS shall have the right to modify these terms. + +**7. IPR and Ownership** +Any rights, including all intellectual property rights and all trademarks not expressly granted herein are reserved in full by the authors or copyright holders. Any requests for additional permissions by XMOS including any rights to use XMOS trademarks, should be made (without obligation) to XMOS at **support@xmos.com** + +Nothing herein shall limit any rights that XMOS is otherwise entitled to under the doctrines of patent exhaustion, implied license, or legal estoppel. Neither the name of the authors, the copyright holders or any contributors may be used to endorse or promote any Derivatives from this Software without specific written permission. Any attempt to deal with the Software which does not comply with this Licence shall be void and shall automatically terminate any rights granted under this licence (including any licence of any intellectual property rights granted herein). +Subject to the licences granted under this Licence any Contributor retains all rights, title and interest in and to any Derivatives made by Contributor subject to the underlying rights of XMOS in the Software. XMOS shall retain all rights, title and interest in the Software and any Derivatives made by XMOS (“XMOS Derivatives”). XMOS Derivatives will not automatically be subject to this Licence and XMOS shall be entitled to licence such rights on any terms (without obligation) as it sees fit. + +**8. Termination** + +8.1 This Licence will automatically terminate immediately, without notice to you, if: + +(a) you fail to comply with the terms of this Licence; and/or + +(b) you directly or indirectly commence any action for patent or intellectual property right infringement against XMOS, or any parent, group, affiliate or subsidiary of XMOS; provided XMOS did not first commence an action or patent infringement against you in that instance; and/or + +(c) the terms of this Licence are held by any court of competent jurisdiction to be unenforceable in whole or in part. + +**9. Critical Applications.** Unless XMOS has agreed in writing with you an agreement specifically governing use of the Goods in military, aerospace, automotive or medically related functions (collectively and individually hereinafter referred to as "Special Use"), any permitted use of the Software excludes Special Use. Notwithstanding any agreement between XMOS and you for Special Use, Special Use shall be at your own risk, and you shall fully indemnify XMOS against any damages, losses, costs and claims (direct and indirect) arising out of any Special Use. + +**10. NO WARRANTY OR SUPPORT.** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL XMOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, WARRANTY, CIVIL TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE INCLUDING GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOT WITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE. IN SOME JURISDICTIONS PARTIES ARE UNABLE TO LIMIT LIABILTY IN THIS WAY, IF THIS APPLIES TO YOUR JURISDICTION THIS LIABILITY CLAUSE ABOVE MAY NOT APPLY. NOTWITHSTANDING THE ABOVE, IN NO EVENT SHALL XMOS’s TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSS OR OTHERWISE EXCEED $50. + +**11. Governing Law and Jurisdiction.** This Licence constitutes the entire agreement between the parties with respect to the subject matter hereof. The Licence shall be governed by the laws of England and the conflict of laws and UN Convention on Contracts for the International Sale of Goods, shall not apply. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..60063a5 --- /dev/null +++ b/README.rst @@ -0,0 +1,64 @@ +:orphan: + +############################## +lib_unity: Template library +############################## + +:vendor: XMOS +:version: 2.7.0 +:scope: General Use +:description: A test framework for C, adapted from the Unity test framework +:category: General Purpose +:keywords: +:devices: xcore-200, xcore.ai + +******* +Summary +******* + +lib_unity is a small utility library that adapts the Unity unit test framework for use with the +xcommon_cmake-based XMOS build system. + +******** +Features +******** + +* xcommon_cmake support. +* LIB_UNITY_AUTO_TEST_RUNNER option for automatically generating test runners. + +************ +Known issues +************ + +* None + +**************** +Development repo +**************** + +* `lib_unity `_ (https://www.github.com/xmos/lib_unity) + +************** +Required tools +************** + +* XMOS XTC Tools: 15.3.1 + +********************************* +Required libraries (dependencies) +********************************* + +* Unity test framework (included as a submodule) + +************************* +Related application notes +************************* + +* None + +******* +Support +******* + +This package is supported by XMOS Ltd. Issues can be raised against the software at +`www.xmos.com/support `_ or using GitHub `issues `_. diff --git a/doc/Doxyfile.inc b/doc/Doxyfile.inc new file mode 100644 index 0000000..5a36389 --- /dev/null +++ b/doc/Doxyfile.inc @@ -0,0 +1,5 @@ +# This file provides overrides to the Doxyfile configuration + +PROJECT_NAME = lib_unity +PROJECT_BRIEF = "Unity library" +PREDEFINED = C_API= EXTERN_C= slave= __DOXYGEN__=1 diff --git a/doc/exclude_patterns.inc b/doc/exclude_patterns.inc new file mode 100644 index 0000000..f50ad3a --- /dev/null +++ b/doc/exclude_patterns.inc @@ -0,0 +1,8 @@ +/build/*build*/**/*.rst +/build/*build*/**/*.md +**/.venv/**/*.md +**/.venv/**/*.rst +lib_unity/Unity/* +CHANGELOG.rst +LICENSE.rst +*.md diff --git a/doc/rst/lib_unity.rst b/doc/rst/lib_unity.rst new file mode 100644 index 0000000..2b1312e --- /dev/null +++ b/doc/rst/lib_unity.rst @@ -0,0 +1,74 @@ +lib_unity +========= + +.. warning:: This documentation is a work in progress. + +Overview +-------- + +lib_unity is a small utility library that adapts the Unity unit test framework for use with the +xcommon_cmake-based XMOS build system. + +For more information about the Unity test framework, see the upstream project: + +https://github.com/ThrowTheSwitch/Unity/blob/master/docs/UnityGettingStartedGuide.md + +How to use +---------- + +To use this library in an xcommon_cmake project, add the module to your application's +`APP_DEPENDENT_MODULES` list in `CMakeLists.txt`, for example: + +.. code-block:: cmake + + set(APP_DEPENDENT_MODULES "lib_unity") + +.. note:: Dependent modules should be pinned to release versions where possible; otherwise the + latest commit on the `develop` branch will be used. See the xcommon-cmake documentation for + dependency management details. + +Example +------- + +The repository includes a small example in `examples/basic` that demonstrates a minimal Unity +test group and a simple test runner. + +A brief excerpt from the tests (examples/basic/src/test_basic.c): + +.. literalinclude:: ../../examples/basic/src/test_basic.c + :language: c + :start-after: #include "unity.h" + +And the corresponding test runner (examples/basic/src/main.c): + +.. literalinclude:: ../../examples/basic/src/main.c + :language: c + :start-after: #include "unity_fixture.h" + +How to build the example +------------------------ + +From the repository root, go to the example directory and run cmake and xmake: + +.. code-block:: console + + cd examples/basic + cmake -G "Unix Makefiles" -B build + xmake -C build + +How to run the example +---------------------- + +Run the generated binary with xsim: + +.. code-block:: console + + xsim bin/test_basic.xe + +Expected output +--------------- + +.. code-block:: console + + 3 Tests 0 Failures 0 Ignored + OK diff --git a/examples/basic/CMakeLists.txt b/examples/basic/CMakeLists.txt new file mode 100644 index 0000000..1d6ea31 --- /dev/null +++ b/examples/basic/CMakeLists.txt @@ -0,0 +1,15 @@ +cmake_minimum_required(VERSION 3.21) +include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake) +project(test_basic) + +set(APP_HW_TARGET XK-EVK-XU316) + +set(APP_INCLUDES src) + +set(APP_COMPILER_FLAGS -g) + +set (APP_DEPENDENT_MODULES "lib_unity") + +set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../..) + +XMOS_REGISTER_APP() diff --git a/examples/basic/src/main.c b/examples/basic/src/main.c new file mode 100644 index 0000000..36e7274 --- /dev/null +++ b/examples/basic/src/main.c @@ -0,0 +1,17 @@ +// Copyright 2020-2026 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +#include + +#include "unity_fixture.h" + +int main(int argc, const char* argv[]) +{ + UnityGetCommandLineOptions(argc, argv); + UnityBegin(argv[0]); + + printf("\n\n"); + + RUN_TEST_GROUP(test_basic); + return UNITY_END(); +} diff --git a/examples/basic/src/test_basic.c b/examples/basic/src/test_basic.c new file mode 100644 index 0000000..c56a531 --- /dev/null +++ b/examples/basic/src/test_basic.c @@ -0,0 +1,33 @@ +// Copyright 2026 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +#include "unity.h" +#include "unity_fixture.h" +#include + +TEST_GROUP_RUNNER(test_basic) { + RUN_TEST_CASE(test_basic, sum_test); + RUN_TEST_CASE(test_basic, div_test); + RUN_TEST_CASE(test_basic, sinf_test); +} + +TEST_GROUP(test_basic); +TEST_SETUP(test_basic) {/*Optional setup*/} +TEST_TEAR_DOWN(test_basic) {/*Optional cleanup*/} + +TEST(test_basic, sum_test) { + int result = 2 + 3; + TEST_ASSERT_EQUAL_INT(5, result); +} + +TEST(test_basic, div_test) { + int result = 20 / 4; + TEST_ASSERT_EQUAL_INT(5, result); +} + +TEST(test_basic, sinf_test) { + const float pi = 3.14159265f; + float angle = pi / 2.0f; + float result = sinf(angle); + TEST_ASSERT_FLOAT_WITHIN(0.0001f, 1.0f, result); +} diff --git a/examples/uut_and_tests/CMakeLists.txt b/examples/uut_and_tests/CMakeLists.txt index d462652..4c4a730 100644 --- a/examples/uut_and_tests/CMakeLists.txt +++ b/examples/uut_and_tests/CMakeLists.txt @@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.21) include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake) project(unit_test) -set(APP_HW_TARGET XCORE-AI-EXPLORER) +set(APP_HW_TARGET XK-EVK-XU316) set(XMOS_SANDBOX_DIR ${CMAKE_SOURCE_DIR}/../../..) set(APP_DEPENDENT_MODULES lib_unity) diff --git a/lib_unity/lib_build_info.cmake b/lib_unity/lib_build_info.cmake index 9f5cb49..d02649e 100644 --- a/lib_unity/lib_build_info.cmake +++ b/lib_unity/lib_build_info.cmake @@ -1,5 +1,5 @@ set(LIB_NAME lib_unity) -set(LIB_VERSION 2.6.1) +set(LIB_VERSION 2.7.0) set(LIB_INCLUDES Unity/src) set(LIB_C_SRCS Unity/src/unity.c) set(LIB_DEPENDENT_MODULES "") diff --git a/settings.yml b/settings.yml new file mode 100644 index 0000000..5fe91dc --- /dev/null +++ b/settings.yml @@ -0,0 +1,27 @@ +# This file relates to internal XMOS infrastructure and should be ignored by external users +--- +lib_name: lib_unity +project: '{{lib_name}}' +title: '{{lib_name}}: Unity library' +version: 2.7.0 + +documentation: + exclude_patterns_path: doc/exclude_patterns.inc + root_doc: doc/rst/lib_unity.rst + linkcheck_ignore_regex: [''] + latex_toc_depth: 3 + latex_secnum_depth: 3 + cognidox_part_number: XM-015644-UG + doxygen_projects: + lib_unity: + doxyfile_path: doc/Doxyfile.inc + pdfs: + doc/rst/lib_unity.rst: + pdf_title: '{{title}}' + pdf_filename: '{{lib_name}}_v{{version}}' + README.rst: + pdf_title: '{{title}} (README)' + pdf_filename: '{{lib_name}}_v{{version}}_readme' + pdf_short: yes +software: + cognidox_part_number: XM-015645-SM From c9bc1f506e4a7cfd69bcbb8d38350ba69781b261 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Thu, 21 May 2026 17:01:55 +0100 Subject: [PATCH 2/9] Update documentation for lib_unity: enhance usage instructions and examples --- doc/rst/lib_unity.rst | 52 ++++++++++++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/doc/rst/lib_unity.rst b/doc/rst/lib_unity.rst index 2b1312e..4ad21d7 100644 --- a/doc/rst/lib_unity.rst +++ b/doc/rst/lib_unity.rst @@ -6,40 +6,55 @@ lib_unity Overview -------- -lib_unity is a small utility library that adapts the Unity unit test framework for use with the -xcommon_cmake-based XMOS build system. +``lib_unity`` is a small utility library that adapts the `Unity unit test framework +`_ for use with the ``xcommon_cmake`` based XMOS build +system. It provides the necessary CMake integration to compile and link Unity into your XCore +application, along with helper fixtures for structuring test groups and a test runner. -For more information about the Unity test framework, see the upstream project: +Compatibility +------------- -https://github.com/ThrowTheSwitch/Unity/blob/master/docs/UnityGettingStartedGuide.md +- **Toolchain:** XMOS XTC Tools 15.3.1 or later +- **Unity version:** 2.6.0 (vendored) +- **Build system:** xcommon_cmake How to use ---------- -To use this library in an xcommon_cmake project, add the module to your application's -`APP_DEPENDENT_MODULES` list in `CMakeLists.txt`, for example: +Add ``lib_unity`` to your application's ``APP_DEPENDENT_MODULES`` list in ``CMakeLists.txt``: .. code-block:: cmake set(APP_DEPENDENT_MODULES "lib_unity") -.. note:: Dependent modules should be pinned to release versions where possible; otherwise the - latest commit on the `develop` branch will be used. See the xcommon-cmake documentation for - dependency management details. +Pin the dependency to a release tag where possible. If no version is specified, xcommon_cmake will +use the latest commit on the ``develop`` branch. + +See the `xcommon_cmake documentation `_ for +dependency management details. + +What the library provides +~~~~~~~~~~~~~~~~~~~~~~~~~ + +After adding the module, your application gains: + +- The Unity and Unity Fixture headers (``unity.h``, ``unity_fixture.h``) +- A CMake target that compiles and links the Unity source files automatically +- No additional configuration is required; Unity's default settings are used Example ------- -The repository includes a small example in `examples/basic` that demonstrates a minimal Unity -test group and a simple test runner. +The repository includes a minimal working example in ``examples/basic`` that demonstrates a test +group and a test runner using the Unity Fixture API. -A brief excerpt from the tests (examples/basic/src/test_basic.c): +Test file (``examples/basic/src/test_basic.c``): .. literalinclude:: ../../examples/basic/src/test_basic.c :language: c :start-after: #include "unity.h" -And the corresponding test runner (examples/basic/src/main.c): +Test runner (``examples/basic/src/main.c``): .. literalinclude:: ../../examples/basic/src/main.c :language: c @@ -48,26 +63,31 @@ And the corresponding test runner (examples/basic/src/main.c): How to build the example ------------------------ -From the repository root, go to the example directory and run cmake and xmake: +From the repository root, navigate to the example directory and run CMake followed by ``xmake``: .. code-block:: console cd examples/basic - cmake -G "Unix Makefiles" -B build + cmake -B build -G "Unix Makefiles" xmake -C build How to run the example ---------------------- -Run the generated binary with xsim: +Simulate the test binary using ``xsim``: .. code-block:: console xsim bin/test_basic.xe +.. note:: Running on hardware is outside the scope of this example. To run on a development board, + use ``xrun`` with an appropriate target adapter. + Expected output --------------- +A passing test run produces: + .. code-block:: console 3 Tests 0 Failures 0 Ignored From 07615fb862ecf96f773ede3b8dc8220607787ab2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Fri, 22 May 2026 09:32:51 +0100 Subject: [PATCH 3/9] Update submodule Unity to tag v2.6.1 and modify changelog --- .gitmodules | 1 - CHANGELOG.rst | 3 ++- lib_unity/Unity | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitmodules b/.gitmodules index e5f6fa6..a4eb799 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,3 @@ [submodule "lib_unity/Unity"] path = lib_unity/Unity url = https://github.com/ThrowTheSwitch/Unity - branch = master diff --git a/CHANGELOG.rst b/CHANGELOG.rst index df31b15..2db34de 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -6,7 +6,8 @@ lib_unity change log * ADDED: Initial upport for vx4 builds. * CHANGED: Tools version to 15.3.1. - + * CHANGED: submodule of upstream Unity to tag v2.6.1 + 2.6.1 ----- diff --git a/lib_unity/Unity b/lib_unity/Unity index 860062d..cbcd08f 160000 --- a/lib_unity/Unity +++ b/lib_unity/Unity @@ -1 +1 @@ -Subproject commit 860062d51b2e8a75d150337b63ca2a472840d13c +Subproject commit cbcd08fa7de711053a3deec6339ee89cad5d2697 From ef7533a5be3cb99b5d54c34201d7e0a7f955b10d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Fri, 22 May 2026 09:42:44 +0100 Subject: [PATCH 4/9] Update documentation: refine compatibility section and enhance usage instructions --- doc/rst/lib_unity.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/rst/lib_unity.rst b/doc/rst/lib_unity.rst index 4ad21d7..c53979d 100644 --- a/doc/rst/lib_unity.rst +++ b/doc/rst/lib_unity.rst @@ -15,7 +15,6 @@ Compatibility ------------- - **Toolchain:** XMOS XTC Tools 15.3.1 or later -- **Unity version:** 2.6.0 (vendored) - **Build system:** xcommon_cmake How to use @@ -33,8 +32,8 @@ use the latest commit on the ``develop`` branch. See the `xcommon_cmake documentation `_ for dependency management details. -What the library provides -~~~~~~~~~~~~~~~~~~~~~~~~~ +Features +~~~~~~~~ After adding the module, your application gains: @@ -63,7 +62,7 @@ Test runner (``examples/basic/src/main.c``): How to build the example ------------------------ -From the repository root, navigate to the example directory and run CMake followed by ``xmake``: +To build the example, run the following commands from the root of the repository: .. code-block:: console @@ -74,14 +73,17 @@ From the repository root, navigate to the example directory and run CMake follow How to run the example ---------------------- -Simulate the test binary using ``xsim``: +Once compiled, to run the example on the simulator, use: .. code-block:: console xsim bin/test_basic.xe -.. note:: Running on hardware is outside the scope of this example. To run on a development board, - use ``xrun`` with an appropriate target adapter. +Or on hardware: + +.. code-block:: console + + xrun bin/test_basic.xe Expected output --------------- From e69a42eee0a84ac9ec8f2340aac10e33c6bd4c3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Fri, 22 May 2026 09:51:58 +0100 Subject: [PATCH 5/9] Fix formatting in CHANGELOG.rst by removing extra whitespace --- CHANGELOG.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2db34de..cce0ad8 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -7,7 +7,7 @@ lib_unity change log * ADDED: Initial upport for vx4 builds. * CHANGED: Tools version to 15.3.1. * CHANGED: submodule of upstream Unity to tag v2.6.1 - + 2.6.1 ----- From 13962e8a2e241963086e0544edc22d2f1fcbd680 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Fri, 22 May 2026 10:43:51 +0100 Subject: [PATCH 6/9] Update CMakeLists.txt to define supported hardware targets and add validation --- examples/basic/CMakeLists.txt | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/examples/basic/CMakeLists.txt b/examples/basic/CMakeLists.txt index 1d6ea31..308568d 100644 --- a/examples/basic/CMakeLists.txt +++ b/examples/basic/CMakeLists.txt @@ -2,14 +2,22 @@ cmake_minimum_required(VERSION 3.21) include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake) project(test_basic) -set(APP_HW_TARGET XK-EVK-XU316) +set(SUPPORTED_TARGETS "XK-EVK-XU316;XK-EVK-XU416") + +if(NOT DEFINED APP_HW_TARGET) + set(APP_HW_TARGET XK-EVK-XU316) +endif() set(APP_INCLUDES src) set(APP_COMPILER_FLAGS -g) -set (APP_DEPENDENT_MODULES "lib_unity") +set(APP_DEPENDENT_MODULES "lib_unity") set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../..) +if(NOT APP_HW_TARGET IN_LIST SUPPORTED_TARGETS) + message(FATAL_ERROR "Unsupported target ${APP_HW_TARGET}.") +endif() + XMOS_REGISTER_APP() From 6efa69499e822e203ef0cfb1e6ad37804b65c274 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Fri, 22 May 2026 11:27:18 +0100 Subject: [PATCH 7/9] Refactor Jenkinsfile and CMakeLists.txt --- Jenkinsfile | 23 +++++++++++++++-------- examples/uut_and_tests/CMakeLists.txt | 10 +++++++++- lib_unity/lib_build_info.cmake | 23 ++++++++++++++--------- lib_unity/unity_helper.c | 2 ++ 4 files changed, 40 insertions(+), 18 deletions(-) diff --git a/Jenkinsfile b/Jenkinsfile index 8f3c415..9220616 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -15,7 +15,7 @@ pipeline { parameters { string( - name: 'TOOLS_VERSION', + name: 'TOOLS_XS3_VERSION', defaultValue: '15.3.1', description: 'XTC tools version' ) @@ -58,9 +58,7 @@ pipeline { stage('Examples build') { steps { dir("${REPO_NAME}/examples") { - withTools(params.TOOLS_VERSION) { - xcoreBuild() - } + xcoreBuild(toolsVersion: params.TOOLS_XS3_VERSION) } } } @@ -85,7 +83,7 @@ pipeline { stage('Tests') { steps { dir("${REPO_NAME}/examples/uut_and_tests") { - withTools(params.TOOLS_VERSION) { + withTools(params.TOOLS_XS3_VERSION) { withVenv { runPytest() } @@ -118,13 +116,22 @@ pipeline { sh "git submodule update --init --recursive" createVenv(reqFile: "requirements.txt") dir("examples") { - withTools(params.TOOLS_VX4_VERSION) { - xcoreBuild(toolsVersion: params.TOOLS_VX4_VERSION) - } + xcoreBuild(toolsVersion: params.TOOLS_VX4_VERSION) } } // dir(REPO_NAME) } // steps } // stage("Checkout and Build") + stage("tests") { + steps { + dir("${REPO_NAME}/examples/uut_and_tests") { + withTools(params.TOOLS_VX4_VERSION) { + withVenv { + runPytest() + } + } + } + } + } } // stages post { cleanup { diff --git a/examples/uut_and_tests/CMakeLists.txt b/examples/uut_and_tests/CMakeLists.txt index 4c4a730..8307bd5 100644 --- a/examples/uut_and_tests/CMakeLists.txt +++ b/examples/uut_and_tests/CMakeLists.txt @@ -3,7 +3,15 @@ cmake_minimum_required(VERSION 3.21) include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake) project(unit_test) -set(APP_HW_TARGET XK-EVK-XU316) +set(SUPPORTED_TARGETS "XK-EVK-XU316;XK-EVK-XU416") + +if(NOT DEFINED APP_HW_TARGET) + set(APP_HW_TARGET XK-EVK-XU316) +endif() +if(NOT APP_HW_TARGET IN_LIST SUPPORTED_TARGETS) + message(FATAL_ERROR "Unsupported target ${APP_HW_TARGET}.") +endif() + set(XMOS_SANDBOX_DIR ${CMAKE_SOURCE_DIR}/../../..) set(APP_DEPENDENT_MODULES lib_unity) diff --git a/lib_unity/lib_build_info.cmake b/lib_unity/lib_build_info.cmake index d02649e..497d4d3 100644 --- a/lib_unity/lib_build_info.cmake +++ b/lib_unity/lib_build_info.cmake @@ -4,36 +4,41 @@ set(LIB_INCLUDES Unity/src) set(LIB_C_SRCS Unity/src/unity.c) set(LIB_DEPENDENT_MODULES "") -# conditional depending on target +# cmake options +option(LIB_UNITY_USE_FIXTURE "Include unity memory and fixtures extras" ON) +option(LIB_UNITY_USE_MEMORY "Include unity memory and memorys extras" ON) +option(LIB_UNITY_AUTO_TEST_RUNNER "Enable to generate a test runner for each build config" OFF) + +# compiler flags (based on target) if(APP_BUILD_ARCH STREQUAL "xs3a") # xs3 set(WNO_FPTR -Wno-xcore-fptrgroup) elseif(APP_BUILD_ARCH STREQUAL "vx4b") # vx4 set(WNO_FPTR -Wno-fptrgroup) - list(APPEND LIB_C_SRCS unity_helper.c) else() # native set(WNO_FPTR "") endif() - - set(LIB_COMPILER_FLAGS -Os ${WNO_FPTR}) -option(LIB_UNITY_USE_FIXTURE "Include unity memory and fixtures extras" ON) +# conditional sources and includes if(LIB_UNITY_USE_FIXTURE) list(APPEND LIB_INCLUDES Unity/extras/fixture/src) list(APPEND LIB_C_SRCS Unity/extras/fixture/src/unity_fixture.c) endif() -option(LIB_UNITY_USE_MEMORY "Include unity memory and memorys extras" ON) if(LIB_UNITY_USE_MEMORY) list(APPEND LIB_INCLUDES Unity/extras/memory/src) list(APPEND LIB_C_SRCS Unity/extras/memory/src/unity_memory.c) endif() +if(APP_BUILD_ARCH STREQUAL "vx4b") + list(APPEND LIB_C_SRCS unity_helper.c) + if(LIB_UNITY_AUTO_TEST_RUNNER) + list(APPEND LIB_COMPILER_FLAGS -DLIB_UNITY_AUTO_TEST_RUNNER) + endif() +endif() + XMOS_REGISTER_MODULE() -option(LIB_UNITY_AUTO_TEST_RUNNER - "Enable to generate a test runner for each build config" - OFF) if(LIB_UNITY_AUTO_TEST_RUNNER) find_program(RUBY_EXE ruby REQUIRED) diff --git a/lib_unity/unity_helper.c b/lib_unity/unity_helper.c index 4dbf676..d0d0d72 100644 --- a/lib_unity/unity_helper.c +++ b/lib_unity/unity_helper.c @@ -19,6 +19,8 @@ asm(".resource_list_empty " #FN ", \"parallel_callees\""); \ asm(".resource_const " #FN ", \"stack_frame_bytes\", " UNITY_STRINGIFY(BYTES)) +#ifndef LIB_UNITY_AUTO_TEST_RUNNER UNITY_STACKFUNCTION(UnityTestRunner, UNITY_TEST_RUNNER_STACK_SIZE); +#endif #endif // defined(__VX4B__) From 0aea6b901a65719be1acd4f194beab9854aa5a4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Fri, 22 May 2026 11:33:39 +0100 Subject: [PATCH 8/9] Refactor Jenkinsfile: move getApproval() call, update VX4 agent label formatting, and enhance xcoreBuild options --- Jenkinsfile | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/Jenkinsfile b/Jenkinsfile index 9220616..f0ffdc0 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -2,15 +2,13 @@ @Library('xmos_jenkins_shared_library@v0.52.0') _ -getApproval() - def getRepoNameFromScm() { def (server, user, repo) = extractFromScmUrl() return repo } +getApproval() pipeline { - agent none parameters { @@ -106,7 +104,7 @@ pipeline { } // XS3 stage('Target (VX4)') { - agent { label 'vx4' } + agent {label "vx4"} stages { stage("Checkout and Build") { steps { @@ -116,22 +114,14 @@ pipeline { sh "git submodule update --init --recursive" createVenv(reqFile: "requirements.txt") dir("examples") { - xcoreBuild(toolsVersion: params.TOOLS_VX4_VERSION) + xcoreBuild( + toolsVersion: params.TOOLS_VX4_VERSION, + cmakeOpts: '-DAPP_HW_TARGET=XK-EVK-XU416' + ) } } // dir(REPO_NAME) } // steps } // stage("Checkout and Build") - stage("tests") { - steps { - dir("${REPO_NAME}/examples/uut_and_tests") { - withTools(params.TOOLS_VX4_VERSION) { - withVenv { - runPytest() - } - } - } - } - } } // stages post { cleanup { From 867cc82c392239fdff274ac7dc8820f3630b132a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?xalbertoisorna=E2=80=9D?= Date: Fri, 22 May 2026 11:40:21 +0100 Subject: [PATCH 9/9] Remove conditional compilation for LIB_UNITY_AUTO_TEST_RUNNER in build files --- lib_unity/lib_build_info.cmake | 3 --- lib_unity/unity_helper.c | 2 -- 2 files changed, 5 deletions(-) diff --git a/lib_unity/lib_build_info.cmake b/lib_unity/lib_build_info.cmake index 497d4d3..01599c6 100644 --- a/lib_unity/lib_build_info.cmake +++ b/lib_unity/lib_build_info.cmake @@ -32,9 +32,6 @@ endif() if(APP_BUILD_ARCH STREQUAL "vx4b") list(APPEND LIB_C_SRCS unity_helper.c) - if(LIB_UNITY_AUTO_TEST_RUNNER) - list(APPEND LIB_COMPILER_FLAGS -DLIB_UNITY_AUTO_TEST_RUNNER) - endif() endif() XMOS_REGISTER_MODULE() diff --git a/lib_unity/unity_helper.c b/lib_unity/unity_helper.c index d0d0d72..4dbf676 100644 --- a/lib_unity/unity_helper.c +++ b/lib_unity/unity_helper.c @@ -19,8 +19,6 @@ asm(".resource_list_empty " #FN ", \"parallel_callees\""); \ asm(".resource_const " #FN ", \"stack_frame_bytes\", " UNITY_STRINGIFY(BYTES)) -#ifndef LIB_UNITY_AUTO_TEST_RUNNER UNITY_STACKFUNCTION(UnityTestRunner, UNITY_TEST_RUNNER_STACK_SIZE); -#endif #endif // defined(__VX4B__)