The metadata used by xPack tools.

Overview

The xPack metadata is a set of JSON definitions intended to assist the xPack tools during the entire project lifetime:

  • creation from templates (device and platform selection, memory map)
  • configuration (application and system part)
  • build (multiple build configurations and tests)
  • debug (device selection, peripheral registers views)

Metadata files

The xPack metadata is stored into several files:

  • package.json: the npm metadata file may also include some xPack specific metadata
  • *xbuild.json: the xPack build related metadata; it is stored into multiple files, located both in the project root, and into different inner folders
  • *xpdsc.json: similar to the CMSIS PDSC, actually only a small subset, with the devices and boards definitions, used by templates and during debug (to locate the SVD files)
  • *xsvd.json: similar to the CMSIS SVD files, with the peripheral register definitions, used during debug

Definitions

JSON Properties

As with any JSON file, the content is basically an object with several properties, represented as "name": <value>. The values may be strings, objects or arrays of other values.

Collections

Traditionally, collections are stored in JSON as arrays, which impose no restrictions on the content or uniqueness.

If object names must be unique, collections of named children can be stored as objects (implemented as maps) with names as keys and children objects as values.

To simplify usage, except named children, collections cannot have other properties.

Lower case names

All object and properties names must be composed from letters, hyphens, or digits. When used to create paths, case is not significative and all letters are internally converted to lower case.

Paths

All paths use the POSIX syntax, with / separators.

Macros

In certain places, strings may contain macros, with a syntax inspired by the Liquid templates:

"name": "{{ expression }}"

where expression can be a name or a qualified name, like test.name.

JSON Files

JSON is a lightweight data-interchange format introduced by JavaScript.

As usual with JSON files, the definitions are organised as a hierarchy of object with properties with values.

The values can be:

  • scalar (strings, numbers, boolean)
  • arrays of properties ([ "Ford", "BMW", "Fiat" ])
  • objects, as maps of properties ({ "name":"John", "age":30, "car":null }).

Common definitions

The schemaVersion property

The schemaVersion is used by parsers to dinamically adapt to different file format versions; changes in the schema or in the semantics should be reflected in a different version.

The schemaVersion property is mandatory for all *xbuild.json files. A recent version of the xPack aware tools should be prepared to parse all older version of the *xbuild.json files. When asked to process a newer, possibly incompatible, version of an *xbuild.json file, the tools that do not reconise that version should throw an error.

The version is also used to select a JSON schema during validation.

Example:

{
  "schemaVersion": "0.3.0"
}

The license property

The license is a short identifier, defined by SPDX.

Example:

{
  "license": "MIT"
}

The copyright is a short string, with the name of the copyright owner.

Example:

{
  "copyright": "© 2021 Liviu Ionescu"
}