How to contribute to the µOS++ Tracing Infrastructure

This page is designed for developers who intend to contribute new features or resolve bugs within the µOS++ Tracing Infrastructure project and provides documentation on building and testing the package.

The project is written in modern C++ and, for reproducibility reasons, utilises the xPack Framework tools during development.

Prerequisites

@micro-os-plus/diag-trace is an xpm package that provides a C++ source code library; development can be conducted on macOS, GNU/Linux and Windows (although some npm scripts must be executed within a Git Bash terminal).

The prerequisites are:

• git
• node >= 18.0.0
• npm

To execute the native tests with the system tools, a C++ development environment is required. On macOS, install Command Line Tools; on Ubuntu, install build-essential.

For details on installing the prerequisites, please refer to the Prerequisites page.

Obtain project sources

The project is hosted on GitHub:

• https://github.com/micro-os-plus/diag-trace-xpack.git

Branches

This project utilises multiple branches:

• master, not actively used
• xpack, containing the latest stable version (default)
• xpack-development, containing the current development version
• website, containing the current website content; pushes to this branch automatically trigger publication of the main website
• development, containing the current preview website content; pushes to this branch automatically trigger publication of the preview website

All development is conducted in the xpack-development branch, and contributions via Pull Requests should be directed to this branch.

When new releases are published, the xpack-development branch is rebased onto xpack.

To clone the stable branch (xpack), execute the following commands in a terminal (on Windows use the Git Bash console):

rm -rf ~/Work/micro-os-plus/diag-trace-xpack.git && \
mkdir -p ~/Work/micro-os-plus && \
git clone \
  --branch xpack \
  https://github.com/micro-os-plus/diag-trace-xpack.git \
  ~/Work/micro-os-plus/diag-trace-xpack.git

For development purposes, clone the xpack-development branch.

rm -rf ~/Work/micro-os-plus/diag-trace-xpack.git && \
mkdir -p ~/Work/micro-os-plus && \
git clone \
  --branch xpack-development \
  https://github.com/micro-os-plus/diag-trace-xpack.git \
  ~/Work/micro-os-plus/diag-trace-xpack.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/micro-os-plus/diag-trace-xpack.git pull

tip

To contribute Pull Requests, fork the project and ensure the Copy the master branch only is disabled.

Utilise the xpack-development branch and ensure you contribute the Pull Requests back to the xpack-development branch.

Add links for development

During development, it is convenient to maintain a writable instance of the library to enable changes in parallel with the parent project.

To facilitate the use of a writable instance of this library in other projects, add a link from the user's global xPacks store to this local development folder:

xpm link -C ~/Work/micro-os-plus/diag-trace-xpack.git

And in the projects referring it:

xpm link @micro-os-plus/diag-trace

Obtain the writable helper sources (optional, for development purposes)

The project has a dependency on a common helper, which is normally installed as a read-only dependency; for development purposes, to enable modifications to the scripts located within the helper, clone the xpack-development branch and link it to the user's global xPacks store:

rm -rf ~/Work/micro-os-plus/build-helper-xpack.git && \
mkdir -p ~/Work/micro-os-plus && \
git clone \
  --branch xpack-development \
  https://github.com/micro-os-plus/build-helper-xpack.git \
  ~/Work/micro-os-plus/build-helper-xpack.git 

Alternatively, if the repository has already been cloned:

git -C ~/Work/micro-os-plus/build-helper-xpack.git pull

If a writable instance of this library is required in another project, add a link from the user's global xPacks store to it:

xpm link -C ~/Work/micro-os-plus/build-helper-xpack.git

Satisfy dependencies

Navigate to the project folder:

cd ~/Work/xpack/micro-os-plus/diag-trace-xpack.git

and execute the following commands:

npm install
npm --prefix tests install
xpm install -C tests

Language standard compliance

The library is written in modern C++ and should be compiled with -std=c++20.

Code formatting

For formatting style, the library employs a .clang-format configuration file based on the GNU style.

Code formatting is performed using clang-format --style=file, either manually via a script, or automatically through Visual Studio Code, or the Eclipse CppStyle plug-in.

info

Visual Studio Code can directly utilise the .clang-format file within the Format Document command.

tip

Always reformat the source files that have been modified before committing them to the repository.

Tests

The µOS++ testing strategy involves compiling the sources with as many toolchains as possible and executing them on a wide range of platforms.

Host Platforms

The tests may be executed on any of the supported host platforms:

• GNU/Linux (x64 and arm64, GLIBC>=2.28); to execute the native tests, a C++ development environment is required (on Ubuntu install build-essential)
• macOS (>= 11.0); as C++ development environment utilise Command Line Tools
• Windows 7 with the Universal C Runtime (UCRT), Windows 8, Windows 10, Windows 11

Target Platforms

The supported target test platforms are:

• platforms/native - execute the test applications as native processes on the development machine
• platforms/qemu-cortex-m0 - execute the tests as fully semihosted Cortex-M0 applications on a QEMU mps2-an385 emulated board (an Arm Cortex-M3 development board)
• platforms/qemu-cortex-m3 - execute the tests as fully semihosted Cortex-M3 applications on a QEMU mps2-an385 emulated board (an Arm Cortex-M3 development board)
• platforms/qemu-cortex-m4f - execute the tests as fully semihosted Cortex-M4 applications on a QEMU mps2-an386 emulated board (an Arm Cortex-M4 development board)
• platforms/qemu-cortex-m7f - execute the tests as fully semihosted Cortex-M7 applications on a QEMU mps2-an500 emulated board (an Arm Cortex-M7 development board)
• platforms/qemu-cortex-a15 - execute the tests as fully semihosted Cortex-A15 applications on a QEMU virt emulated board
• platforms/qemu-cortex-a72 - execute the tests as fully semihosted Cortex-A72 (64-bit) applications on a QEMU virt emulated board
• platforms/qemu-riscv-rv32imac - execute the tests as fully semihosted RISC-V RV32IMAC applications on a QEMU virt emulated board
• platforms/qemu-riscv-rv64imafdc - execute the tests as fully semihosted RISC-V RV64IMAFDC applications on a QEMU virt emulated board

The build configurations utilise exactly the same source files on all platforms, without changes.

Semihosting

On embedded platforms, the applications interact with the host via the Arm semihosting mechanism.

Toolchains

To enhance source code portability, the builds are repeatedly conducted utilising various toolchains, including multiple versions of the same toolchain.

The following toolchains are utilised:

• gcc (native)
• clang (native)
• arm-none-eabi-gcc (Cortex-M, AArch32)
• aarch64-none-elf-gcc (AArch64)
• risc-none-elf-gcc (RISC-V 32/64)

Tests details

> xpm run test --config native-cmake-sys-release
> ctest -V --test-dir build/native-cmake-sys-release
Internal ctest changing into directory: /Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release
UpdateCTestConfiguration  from :/Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/DartConfiguration.tcl
UpdateCTestConfiguration  from :/Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/DartConfiguration.tcl
Test project /Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release
Constructing a list of tests
Done constructing a list of tests
Updating test list for fixtures
Added 0 tests to meet fixture requirements
Checking test dependency graph...
Checking test dependency graph end

sample-test

The sample/src/main.cpp file is a straightforward application designed to demonstrate how to utilise some of the primitives available in the library.

A typical run looks like:

test 3
    Start 3: sample-test

3: Test command: /Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/platform-bin/sample-test "one" "two"
3: Working Directory: /Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/platform-bin
3: Test timeout computed to be: 10000000
3: micro_os_plus::trace::initialise()
3: micro_os_plus::trace::initialise()
3: main(argc=3, argv=["/Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/platform-bin/sample-test", "one", "two"])
3: Hello C++ World!
3: one line
3: *
3: micro_os_plus::trace::initialise()
3: main(argc=3, argv=["/Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/platform-bin/sample-test", "one", "two"])
3: Hello C World!
3: one line
3: *
3/4 Test #3: sample-test ......................   Passed    0.00 sec

unit-test

The unit/src/main.cpp file is an exhaustive test designed to validate that all the library functions operate as expected.

A typical run looks like:

test 4
    Start 4: unit-test

4: Test command: /Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/platform-bin/unit-test
4: Working Directory: /Users/ilg/MyProjects/micro-os-plus.github/xPacks/diag-trace-xpack.git/tests/build/native-cmake-sys-release/platform-bin
4: Test timeout computed to be: 10000000
4: micro_os_plus::trace::initialise()
4: 
4: # Running: unit-test
4: # Built with clang Apple LLVM 17.0.0 (clang-1700.6.4.2), with exceptions, with MICRO_OS_PLUS_TRACE
4: TAP version 14
4: # Subtest: diag::trace
4: 
4:     # Subtest: Check trace_testing::initialise
4:         1..0
4:     ok 1 - Check trace_testing::initialise # { passed, 4 checks }
4: 
4:     # Subtest: Check trace_testing::putchar
4:         1..0
4:     ok 2 - Check trace_testing::putchar # { passed, 2 checks }
4: 
4:     # Subtest: Check trace_testing::puts
4:         1..0
4:     ok 3 - Check trace_testing::puts # { passed, 3 checks }
4: 
4:     # Subtest: Check trace_testing::printf
4:         1..0
4:     ok 4 - Check trace_testing::printf # { passed, 5 checks }
4: 
4:     # Subtest: Check trace_testing::dump_args
4:         1..0
4:     ok 5 - Check trace_testing::dump_args # { passed, 4 checks }
4: 
4:     # Subtest: Check trace_testing::flush
4:         1..0
4:     ok 6 - Check trace_testing::flush # { passed, 1 check }
4: 
4:     1..6
4: ok 1 - diag::trace # { passed, 19 checks in 6 test cases, time: 0.125 ms }
4: 
4: 1..1
4: # { total: 19 checks passed, 0 failed, in 6 test cases, 1 test suite, time: 0.211 ms }
4/4 Test #4: unit-test ........................   Passed    0.01 sec

Manual tests

There are predefined xpm actions available to manually execute various tests on the local development machine.

It is recommended to commence by performing some clean-ups (not necessary following the initial git clone):

npm --prefix ~/Work/micro-os-plus/diag-trace-xpack.git/tests install
xpm run deep-clean -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests

tip

During the initial execution, the installation step may require a considerable amount of time, as it needs to download the toolchain archives, which can be relatively large, up to several hundred megabytes.

To execute the tests with the system compiler (usually not available on Windows):

xpm run install -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests
xpm run test -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests

To execute a selection of tests with the latest versions of toolchains:

xpm run install-selected -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests
xpm run test-selected -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests

To execute all tests with the latest versions of toolchains:

xpm run install-latest -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests
xpm run test-latest -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests

To execute all tests with all toolchain versions:

xpm run install-all -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests
xpm run test-all -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests

Clean-ups

Executing all tests may require several gigabytes of space.

To clean up the tests folder, utilise:

npm --prefix ~/Work/micro-os-plus/diag-trace-xpack.git/tests install
xpm run deep-clean -C ~/Work/micro-os-plus/diag-trace-xpack.git/tests

A considerable amount of space may also be utilised by the toolchains. When no longer required, they can be removed with xpm uninstall.

xpm clean-ups

For a comprehensive clean-up, please note that xpm utilises only two folders:

Windows

• %APPDATA%\Roaming\xPacks
• %APPDATA%\Local\Caches\xPacks

macOS

• ${HOME}/Library/xPacks
• ${HOME}/Library/Caches/xPacks

GNU/Linux

• ${HOME}/.local/xPacks
• ${HOME}/.cache/xPacks

They can be removed at any time and space reclaimed; xpm will recreate them during new installations.

However, projects linking to the user's global xPacks store will fail with broken paths.

Continuous Integration (CI)

The library is subject to continuous integration (CI) testing with every push utilising GitHub Actions. This ensures compatibility and stability across Ubuntu, macOS, and Windows operating systems.

Testing is conducted on both 32-bit and 64-bit bare-metal platforms, including Arm Cortex-M0, Cortex-M3, Cortex-M4F, Cortex-M7F, Cortex-A15, Cortex-A72, RISC-V RV32IMAC, and RV64IMAFDC. Additionally, native testing is performed utilising GCC and LLVM/clang compilers, ensuring comprehensive validation across various environments.

The website

The project includes the source files for its website. The main pages are generated with Docusaurus, and the reference pages are generated with Doxygen.

Regenerate the Doxygen pages

Execute the generate-website-doxygen npm script:

npm --prefix ~/Work/micro-os-plus/diag-trace-xpack.git/website run generate-website-doxygen

At present, the doxygen programme must be installed on the host, as it is not available as an xpm dependency.

With the current configuration, the static HTML pages are generated within the website/static/doxygen folder and converted to docusaurus markdown in docs/api.

Prepare the website

The documentation site is built using Docusaurus and published on the project GitHub Pages.

• Switch to the xpack-development branch
• Execute the website-generate-commons npm script in the website/package.json

  npm --prefix ~/Work/micro-os-plus/diag-trace-xpack.git/website run website-generate-commons

• Commit all changes

Build the static website locally

Validate the website content by performing a local build using the npm build script:

npm --prefix ~/Work/micro-os-plus/diag-trace-xpack.git/website run build

Resolve any broken links that may be identified during the build process.

Start the local web server

Execute the npm script clear followed by start in the website sub-project, or execute the following within the project folder:

npm --prefix ~/Work/micro-os-plus/diag-trace-xpack.git/website run clear
npm --prefix ~/Work/micro-os-plus/diag-trace-xpack.git/website run start

Navigate to the Maintainer Info page, the Start the local web server section.