CMSIS-Pack: Publish a Pack

| CMSIS-Pack Version 1.6.3 Delivery Mechanism for Software Packs

- Main Page
- Usage and Description

All Pages
Publish a Pack

There are multiple ways to distribute a software pack:

# Prerequisites

Before you start to distribute a software pack, you need to make sure that it does not contain errors. A good start is an error and warning free run of:

- `gen_pack.bat` script from the Pack Tutorial
- or Bash Script gen_pack.sh that does not show any packChk errors.

Also you should perform an XML schema check, for example using the MDK Pack Installer.

- Right-click on the pack version number and select Schema Check:
- The Output window shows the result. If errors are reported, please make sure to fix them before continuing.

Note
  This is important when the pack should published using a pack index service. The pack importer will ignore all <vendor>.<name>.pdsc files that do fail when checking against the current PACK.xsd schema file and thus your pack will cannot be downloaded.

# Local Installation

The easiest way to distribute a software pack is attaching it to an email or using other means of electronic distribution (for example using a company internal file server). The installation of a software pack is usually triggered by double-clicking the Pack file. The pack management tool is invoked and the Pack is installed on the local machine. After installation, the Pack will be shown in the list of installed packs (tool dependent). If the PDSC file does not contain a valid `<url>` element, a manual installation is required to update a software pack. Otherwise, pack management tools can check for updates on the server or the local machine that is specified by `<url>`.

Local installation and update from URL

Note
  For automatic updates on a local machine, specify the `<url>` using the file URI scheme.

# Web Download

Any web server can be used to host a software pack (specified by the `<url>` element in the PDSC file). At this location, the following files should be present:

1. <vendor>.<name>.pdsc [required]: pack description file.
2. <vendor>.<name>.<version>.pack [required]: pack file where <version> refers to the latest version specified in the PDSC file.
3. <vendor>.pidx [optional]: list with all packs hosted and maintained by the vendor (refer to Package Index File (pidx))

All previous versions listed in the <releases> section of the PDSC file should be present at the `<url>` as well. This allows users to revert updates or to download a previous version of a software pack (for maintenance purposes).

The <vendor>.pidx allows you to publish multiple packs to a Pack Index Service.

# Publish with Pack Index Service

Several companies maintain a Pack Index Server to make packs available within tools or web pages. Once you are ready to deploy packs via such services, you may send the URL of the <vendor>.<name>.pdsc or <vendor>.pidx file to the following email addresses:

- for Arm and Keil tools and web pages email to CMSIS@arm.com
- for IAR tools email to CMSIS@iar.com

The *.pidx file allows you to change pack versions and add packs to your distribution list. All packs that are referenced in the .pidx file will be processed and validated. Only packs that pass the packChk and schema check will become available via web pages and development tools.

For example, Arm uses the pack information to generate a list of available software packs. The following content will be processed in order to generate the web site (https://developer.arm.com/embedded/cmsis/cmsis-packs):

- Version
- Release Notes
- Devices
- Boards
- Examples
- Software Components

Please allow up to seven working days for the process. If the files contain any errors, you will be notified. Otherwise, the information is added to the index server.

# Rehost pack to different URL

Sometimes, it is necessary to rehost a pack (moving a pack from one URL to another). This implies that you need to change the <url> element in the PDSC file. To ensure that the pack is found by a Pack Index Service, follow this procedure:

- Create a new version of the pack: update the <vendor>.<name>.pdsc file with the new URL ("url_B") and make sure to increment the version
- Place a copy of this latest <vendor>.<name>.pdsc at url_B and url_A (the original URL).
- Place a copy of the new <vendor>.<name>.<version>.pack in url_B (only)
- Copy all packs from url_A to url_B
- Inform Arm about the new URL by either
  - update the <vendor>.pidx with url_B for this pack or
  - email a link to the PDSC file if your company does not maintain a <vendor>.pidx

Note
  - PDSC and pack versions need to be accessible from the same new URL
  - You must keep url_A alive as is. But there is no need to maintain/update url_A going forward otherwise users with an old PDSC file will no longer find the pack versions.

# Web Infra-structure

Tool, software, or silicon vendors may provide a web infra-structure that lists packs that are available from multiple vendors. Companies like Arm or IAR provide a Pack Index Service that uses either a <vendor>.<name>.pdsc or a <vendor>.pidx file to obtain the latest pack versions. This information is used to make the packs available in the development tools (via a Pack Installer) and/or to publish information on certain web pages, for example a device list.

The following diagram explains how these services are working behind the scene.

Web infra-structure for pack hosting services

Note
  - The <url> element in <vendor>.<name>.pdsc is the location where these services check for new packs. At this <url> location, an (unversioned) <vendor>.<name>.pdsc file and a (versioned) <vendor>.<name>.<version>.pack must be available.
  - The <url> is the page where the pack is downloaded. This means, if the URL or the PDSC/Pack files become unavailable, users are unable to download the pack.
  - When a new PDSC/Pack file is available, it is important to update the version number, otherwise the Pack Index Service will not recognize that the pack has changed.
  - Previous versions of a (versioned) <vendor>.<name>.<version>.pack should remain available.

Depending on the implementation, the web infra-structure may provide index files with additional information:

- <vendor>.vidx file (Vendor Index File (vidx)) lists pack index locations known by the service. Arm scans these locations every 24 hours to import new packs. If your location is not listed
- https://www.keil.com/pack/index.pidx is a list of all packs that are correctly imported. If a pack does not appear, the pack did not pass the validation process.