Open-CMSIS-Pack  Version 1.7.35
Delivery Mechanism for Software Packs
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.sh that does not show any packchk errors and validates the XML of the PDSC file.

Note
XML validation 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:

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). Rehosting implies changing 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 a new <release> tag with an incremented version.
  • Place a copy of this latest <vendor>.<name>.pdsc file at url_B and url_A (the original URL).
  • Add this new PDSC file to an updated <vendor>.<name>.<version>.pack (needs to match the version number in the PDSC file).
  • Copy the new <vendor>.<name>.<version>.pack only to url_B.
  • Copy all previous packs from url_A to url_B (so that they are available at the new location).
  • Inform Arm about the new URL by either:
    • updating the <vendor>.pidx with url_B for this pack or
    • emailing a link to the new PDSC file if your company does not maintain a <vendor>.pidx
Note
  • The PDSC file and all pack versions need to be accessible from the same new URL ("url_B").
  • Arm recommends to keep the url_A alive for at least six months so that users have time to pick up the change. Be aware that users who have not noticed the change might be unable to find pack updates once url_A have become unavailable.

Rename a pack

Sometimes, it is necessary to rename a pack (because the pack vendor and/or its name have changed for example). To ensure that the pack is found by a Pack Index Service and the tools, follow this procedure:

  • Create:
    • a new PDSC file with the updated <name> and/or <vendor>, for example NewVendor.NewName.pdsc. The <version> should start at 1.0.0.
    • a new pack containing the new PDSC file with the corresponding <name> and/or <vendor>, for example NewVendor.NewName.1.0.0.pack.
  • Create:
    • a new version of the old PDSC file (Vendor.Name.pdsc) with a new <release> tag (with an updated version), containing the <deprecated> and <replacement> element. The latter pointing to the "NewVendor.NewName".
    • a new version of the old <vendor>.<name>.<version>.pack file with the PDSC you have created above.
  • Copy:
    • All four files (new PDSC and pack, updated old PDSC and pack) to the URL location.
Note
  • Using this approach, you can only do a one-to-one pack replacement.
  • If you want to create more than one replacement pack for a given source pack, you need to work with requirements.

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: