Skip to content

The CMSIS PACK Root Directory

Jump to bottom
Joachim Krech edited this page Nov 8, 2022 · 8 revisions

The CMSIS-Pack Root Directory

Conventions:

  • Pack filenames follow the pattern <vendor>.<name>.<version>.pack.
  • The pack's directory structure contains only a single Package Description File (*.pdsc).
  • The Package Description File must be located either:
    • in the root directory of the archive
    • in an immediate sub-directory of the root directory of the archive. This also requires that the archive only has a single immediate sub-directory
  • The Package Description File uses the exact same <vendor> and <name> as the pack: <vendor>.<name>.pdsc
  • The <vendor>.<name>.pdsc contains the exactly matching strings in the corresponding XML elements <vendor>, <name>, <version>.
  • The <version> is matching the semantic version specified by the version attribute of the first <release> tag in the <releases> section of the <vendor>.<name>.pdsc.

Mandatory Directory Structure

Installed Packs are located in $CMSIS_PACK_ROOT in a sub-directory structure with 3 levels:

  1. <vendor>
  2. <name>
  3. <version>

All files and directories shall be 'read-only' in order to prevent users from editing the pack's content

Mandatory 'Local Repository Packs'

As an alternative to installed packs, references to Package Description Files on the local filesystem can be added to the local repository index file stored in:

  • $CMSIS_PACK_ROOT/.Local/local_repository.pidx
  • This file needs to comply with the PackIndex.xsd schema file. The version attribute can be set to 0.0.0 as it cannot be relied on (see below).
  • Packs stored outside of the $CMSIS_PACK_ROOT are expected to be writable. All tools must always explicitly read the version from the referenced <vendor>.<name>.pdsc as this might get edited at any time. Therefore the version attribute in the local_repository.pidx file is ignored.
  • If the same pack version is both installed as well as specified via the local_repository.pidx, the pack version from the local_repository takes precedence. The introduction of the local_repository.pidx does not change how by default the latest 'installed' pack version is used by the tools. In order for the tools to make use the pack version from the local_repository.pidx is to either a) ensure that the local_repository pack version has the highest version or b) specify the pack version referenced by the local_repository explicitly in the project description.

Optional timestamp file for last update

Whenever the set of installed packs got changed or the local_repository.pidx file got edited, the empty file pack.idx is touched (the timestamp of the file gets updated). This file may be watched by tools to reread the installed packs, as pack versions may have been added or removed.

Optional Package Description cache for a public index

Introduction:

Publicly available packs are listed by package index files. One such maintained index file is here https://www.keil.com/pack/index.pidx. The process for installing a pack with the ID <vendor>.<name>.<version> requires the following steps need to be performed:

  1. download the index.pidx to be used
  2. search for a <pdsc> tag with matching vendor and name attribute
  3. download the package description file constructing the url from the attributes 'url','vendor'.'name'.pdsc
  4. read the <vendor>.<name>.pdsc file's <releases> section to find the <release> tag with a 'version' attribute matching the requested pack version.
  5. if the matching <release> tag contains an attribute 'url' download the request pack from the specified location and store that file as <vendor>.<name>.<version>.pack. Otherwise download the pack constructing the url from the <url> element followed by <vendor>.<name>.<version>.pack.
  6. extract the downloaded zip compliant archive to $CMSIS_PACK_ROOT/<vendor>/<name>/<version>

Caching public pack information:

The following description covers the implementation of the cache as it is implemented by cpackget, MDK packinstaller and CMSIS Eclipse pack manage. In order for different tools to share the cache information in a common CMSIS_PACK_ROOT directory, files shall be located in the directory $CMSIS_PACK_ROOT/.Web

This directory contains:

  • index.pidx
  • a copy of all package description files (<vendor>.<name>.pdsc) listed in the index.pidx file

Note: For the https://www.keil.com/pack/index.pidx a copy of all listed pdsc files can be downloaded replacing the attribute from the index.pidx with url="https://www.keil.com/pack/" for reliable and fast download.

The update process is:

  1. unconditionally download the index.pidx file
  2. the 'version' attribute of the <pdsc> element shall be used to check whether there is a 'newer' version of the package description available than already stored in the cache. If that is the case the corresponding package description file is downloaded.
  3. if a package description file is no longer listed in the index.pidx file, the corresponding package description file shall be removed.

Optional Caching downloaded packs:

The following description details the cache of downloaded packs as it is implemented by cpackget, MDK packinstaller and CMSIS Eclipse pack manage. In order for different tools to share the cached files in a common CMSIS_PACK_ROOT directory, these shall be located in the directory $CMSIS_PACK_ROOT/.Download

Every time a pack is downloaded successfully, it is stored in the .Download directory. In addition a versioned copy of the pdsc file contained in the pack version is stored side by side.

$CMSIS_PACK_ROOT/.Download/<vendor>.<name>.<version>.pack
$CMSIS_PACK_ROOT/.Download/<vendor>.<name>.<version>.pdsc

The pack installer tool shall check whether a pack version is already available in the .Download directory before attempting to download it.

If the installation of a pack version is gated by a license (<license> tag in the package description file), the extracted license can be found here as well:

$CMSIS_PACK_ROOT/.Download/<vendor>.<name>.<version>.lic.<ext>

Where <ext> depends on the file extension specified in the <license> tag.

Pack installer shall provide commands for removing files from the .Download/ directory. Deleting files from this directory or even having no .Download/ directory must not lead to any operations failing.

Clone this wiki locally