How to install the µOS++ Tracing Infrastructure

As an xpm package, the most convenient method to integrate the µOS++ Tracing Infrastructure into a project is to add it as a dependency via xpm.

However, as with any source code library, this project may also be integrated into another project in the traditional manner, either by copying the relevant files into the target project, or by linking the entire project as a Git submodule.

xpm packages (xPacks) refresher

xpm packages, abbreviated as xPacks, are general-purpose, language-neutral software packages. They utilise the same format as npm packages, which comprises a collection of files/folders and a package.json file with the package metadata.

xpm can install source and binary packages.

For more details, please refer to the previous explanation on the Getting Started page.

Automated installation

Alongside the source files, this project also includes a package.json file containing the metadata that identifies it as an xpm/npm package, enabling direct installation from GitHub or from the npmjs.com registry as @micro-os-plus/diag-trace.

Prerequisites

The only requirement for an automated installation is a recent xpm, which is a portable Node.js command line application that complements npm with several additional features specific to C/C++ projects.

To install xpm, follow the instructions on the xpm install page.

If already installed, it is always advisable to update it to the latest version with:

npm install --location=global xpm@latest

tip

Although not mandated by xpm, it is also advisable to upgrade npm to the latest version, and node to a reasonably recent version (currently npm requires a node >=20.0).

Local installations

One of the xPack design goals is to allow each project to select the exact versions of the libraries it requires.

Similarly to npm being able to install specific versions of the JavaScript tools into each project, xpm was also designed to be able to install specific versions of the required libraries locally into each project.

Therefore, similarly to the way npm installs the JavaScript packages into node_modules, xpm installs the libraries into xpacks. Here there will be separate folders with the installed packages, for example xpacks/@micro-os-plus/diag-trace.

Initialise the project

Upon initial use, ensure that a package.json file is present in the project root folder.

This may be achieved by executing xpm init in the desired project folder (substitute my-project accordingly):

cd my-project
xpm init

Under the hood

The primary purpose of xpm init is to create a package.json file, if not already present.

In addition to name & version, the minimal package.json must include a property named xpacks, even if empty. This property is mandatory to identify the package as an xpm package.

Installation via xpm

The next step is to install the diag-trace package into the project.

The command to install the latest available version of diag-trace is:

xpm install @micro-os-plus/diag-trace@latest --verbose

To install a specific version, specify it explicitly:

xpm install @micro-os-plus/diag-trace@5.0.0 --verbose

Installation details

The above xpm install command will perform the following:

• identify the desired version of @micro-os-plus/diag-trace, download it into a cache and unpack it into a versioned folder within the user's global xPacks store (if not already present); check the output of the xpm install command for the actual folder used on your platform;
• create a local symbolic link such as xpacks/@micro-os-plus/diag-trace pointing to the versioned folder in the user's global xPacks store
• add @micro-os-plus/diag-trace to package.json as a dependency; this associates a specific version of µOS++ Tracing Infrastructure with the current project (details below).

tip

The installation location may be configured using the XPACKS_STORE_FOLDER environment variable; for more details please refer to the xpm folders page.

Reproducibility and dependencies

To ensure reproducibility, it is essential for each project to always utilise the exact desired versions of the required libraries, regardless of the libraries installed in the system.

To achieve this objective, xpm records all locally installed packages as dependencies in the project package.json file.

The result appears as follows:

  "xpack": {
  "minimumXpmRequired": "0.20.7",
  "dependencies": {
    "@micro-os-plus/diag-trace": {
      "specifier": "5.0.0",
      "local": "link",
      "platforms": "all"
    }
  },
  "devDependencies": {},
  "properties": {},
  "actions": {},
  "buildConfigurations": {}
}

If the package.json is saved in the revision system, the above definition acts as a firm reference to the specific version of µOS++ Tracing Infrastructure.

After cloning the project into a different location, the command xpm install may be used to install all dependencies.

This is particularly useful for CI/CD environments.

Install folder hierarchy

After following the links, the result of an xpm install is a folder hierarchy that includes only the source files of the library, the include folder with the public headers, and the build system files (CMakeLists.txt, meson.build, and xcdl-package.jsonc) at the top level.

% tree -l
.
├── CHANGELOG.md
├── CMakeLists.txt
├── include
│   └── micro-os-plus
│       └── diag
│           ├── inlines
│           │   ├── trace-c-api-inlines.h
│           │   └── trace-cpp-api-inlines.h
│           ├── trace-c-api.h
│           ├── trace-cpp-api.h
│           └── trace.h
├── LICENSE
├── meson.build
├── package.json
├── README.md
├── src
│   ├── trace-c-api.cpp
│   └── trace-cpp-api.cpp
└── xcdl-package.jsonc

6 directories, 14 files

The original Git repository contains hundreds of additional files, such as the website files and the multi-platform tests; therefore, the installed package is a much smaller subset of the original project and is recommended.

Uninstall

The xpm packages do not utilise any form of system installer; instead they are distributed as portable archives; therefore they do not require the execution of any uninstaller; simply removing the links and possibly the user's global xPacks store folder and the user xPack cache folder is sufficient.

To remove the links created by xpm in the current project, navigate to the project folder:

cd my-project

and request xpm to uninstall the package:

xpm uninstall @micro-os-plus/diag-trace --verbose

To completely remove the package from the user's global xPacks store:

xpm uninstall --global @micro-os-plus/diag-trace --verbose

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.

Installation via npm

The package may also be installed with npm or related tools, but the features specific to C/C++ projects will not be available; therefore, at least for consistency reasons, it is recommended to utilise xpm.

Manual installation

Copy files

The traditional method of utilising source libraries is to copy them into the user's project.

The obvious advantage is simplicity, but the disadvantage is that the library becomes part of the project, and any improvements or bug fixes must be manually copied into the project.

Add as a Git submodule

Another common solution is to add the entire project as a Git submodule, for example beneath an xpacks folder:

cd my-project
git init # Unless already a Git project
mkdir -p xpacks

git submodule add https://github.com/micro-os-plus/diag-trace-xpack.git \
  xpacks/@micro-os-plus/diag-trace

info

Note that linking the project as a submodule brings the entire project, with tests and documentation, not only the source files.

Installing via xpm filters the content, and only the relevant files are brought into the project.

Build & integration info

The project is written in C++, and it is expected to be used in C++ projects.

The source code has been compiled natively with GCC and LLVM/clang, and cross-compiled on embedded Arm and RISC-V targets, ensuring it is free from warnings.

To facilitate the integration of this library into user projects, pre-made CMake and meson configuration files are provided (see below).

For other build systems, please refer to the details provided below.

Include folders

The following folders should be passed to the compiler during the build:

• include

The header files to be included in user projects are:

#include <micro-os-plus/diag-trace.h>

Source files

The source files to be added to user projects are:

• src/trace-c-api.cpp
• src/trace-cpp-api.cpp

Preprocessor definitions

There are several preprocessor definitions used to configure the build:

• MICRO_OS_PLUS_DIAG_TRACE_ENABLED - to include the trace calls
• MICRO_OS_PLUS_DIAG_TRACE_PRINTF_BUFFER_ARRAY_SIZE_INTEGER - the size in bytes of the stack buffer used by vsnprintf() to store the diagnostics line (default 200)

Compiler options

The following options must be passed to the compiler and linker:

• -std=c++20 or higher for C++ sources
• -std=c11 for C sources

Dependencies

The library has the following dependencies:

• none

CMake

To integrate the diag-trace library into a CMake application, add the folder where this project is located to the build:

add_subdirectory("xpacks/@micro-os-plus/diag-trace")

The result is an interface library that may be added as an application dependency with:

target_link_libraries(your-target PRIVATE

  micro-os-plus::diag-trace
)

Meson Build

To integrate the diag-trace library into a meson application, add the folder where this project is located to the build:

subdir('xpacks/@micro-os-plus/diag-trace')

The result is a dependency object that may be added to an application with:

exe = executable(
  your-target,
  link_with: [
    # Nothing, not static.
  ],
  dependencies: [
    micro_os_plus_diag_trace_dependency,
  ]
)

Status

The diag-trace library is fully functional, and it is used in the µOS++ framework.

Testing

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.