Create a Software Pack - Hands-On Example

This repository explains the steps to create a simple software pack using the Open-CMSIS-Pack technology.

The pack contains software from the imaginary "ACME Corp." and shows how to frame a middelware as evaluation and commercial version. The software component itself is available in two flavors: debug (that could have additional test outputs) and release.

NOTE: evaluation and commercial are typically two different packs, but this first hands-on is simple and uses just one pack for it.

Content	Description
gen_pack.sh	Script that builds the pack; refer to prerequisites and usage information for details.
gen_doc.sh	Script that builds the documentation (using Dxoygen). This is an example - other dcoumentation generation mechnisms can be used as well.
check_links.sh	Script that checks all links in the documentation for consistency and availability.
.github/workflows/pack.yaml	GitHub workflow that generates the pack on every commit.
.github/workflows/gh-pages.yaml	GitHub workflow that generates the documentation on the gh-pages branch.

Benefits of Software Pack Delivery

The CMSIS-Pack technology is available in multiple toolchains. Below is a brief history:

• 2008: CMSIS-Core has been introduced and CMSIS has been since then continuously extended.
• 2012: CMSIS-Pack has been started to simplify Product Lifecycle Management (PLM) of Keil MDK and improve overall user experience.
• 2014: CMSIS-Pack is part of Keil MDK for device support, middleware which resulted in higher adoption and lower support.
• 2017: Eclipse version of the CMSIS-Pack system is integrated in Arm DS and IAR toolchains. Sharing packs across toolchains is now possible.
• 2020: Discussions with ST and NXP resulted in the Open-CMSIS-Pack project and the VS Code integration.

Benefits for a Software Vendor

• Connection to users: as software vendor you control distribution to multiple tools and web portals. For the Arm pack system new releases are scanned once per day, making it available to the entire user based. Documentation links in the software pack lets you connect with your users.

• Support business goals: distribute different software variants (eval, lite, full) enables users to seamlessly transition to a commercial offering.

• One way to distribute: for all relevant toolchains as CMSIS supports Arm Compiler, GCC, and IAR. Software scales to many devices when APIs are applied.

• Reduces support efforts: as it is easier for users to integrate software in projects. Product Lifecycle Management simplifies updates and notifies users about outdated configuration files.

To learn more review the session about Generating CMSIS-Packs for Middleware.

Pack Development

The following section explains how to create a pack.

Tool-Environment (Recommended)

• MDK v5.38 with default installation path (C:\Keil_v5)
• CMSIS-Toolbox v1.5.0 or higher (update files in C:\Keil_v5\ARM\ctools)
• VS Code with XML Language Support by Red Hat
• Doxygen v1.9.2

Steps to Create a Software Pack

• Structure your software
  • What are the functional blocks, are these usable separately? If so, consider separate components.
  • What are the interfaces to the device and/or hardware? 
  • Are there existing interfaces in CMSIS? Take a look to CMSIS-Drivers and consider to provide feedback.
  • If not, consider to create an API to separate device from functional parts.
  • You may provide device-specific interfaces as part of your pack but consider a separate pack as the interface could be overwritten or extended with other packs.
  • Create appropriate documentation for the software components.
• Organize and create the file list that will be delivered as Pack
  • Each component can have source code, header and library files, documentation; separate the content logically.
• Create the PDSC file using your favorite editor (we recommend VS Code with XML extension).
• Validate the software pack using the packchk tool.
• Create the software pack using the gen_pack library.

An example middleware is explained in this meeting recording starting at 15:05.

Local Pack Development

1. Clone this repository (as it serves as a getting started example)

2. Register this pack with cpackget via PDSC file using this commands:

   cpackget update-index                    // optional to ensure that pack index is up-to-date
   cpackget add ACME.ACME_Middleware.pdsc   // pack now appears in toolchains, i.e. in MDK
   csolution list packs

3. The content of the pack can now be seen in the Manage Component dialog of uVision.

For changing the PDSC file it is recommended to use VS Code with XML extension, but any editor would work.

After modifications to the PDSC file run packchk; include all packs that are required by your software in the validation:

Using Command Prompt:

packchk ACME.ACME_Middleware.pdsc -i %CMSIS_PACK_ROOT%/ARM/CMSIS/5.9.0/ARM.CMSIS.pdsc

Using Git Bash console:

packchk ACME.ACME_Middleware.pdsc -i $CMSIS_PACK_ROOT/ARM/CMSIS/5.9.0/ARM.CMSIS.pdsc

With CMSIS-Toolbox v1.7.0 the XML schema check is available with packchk, the command may be then extended to:

packchk ACME.ACME_Middleware.pdsc -i $CMSIS_PACK_ROOT/ARM/CMSIS/5.9.0/ARM.CMSIS.pdsc -s /c/Keil_v5/UV4/PACK.xsd

The pack can be created locally in the directory output using Git Bash:

./gen_pack.sh -v

Verify Pack in Tools

To verify the tools such as the VS Code - Keil Studio Desktop extension, install the pack with:

cpackget add ./output/ACME.ACME_Middleware.1.0.0.pack

Notes:

• To continue local pack development, add a new <release> version. During development, semantic version labels to indicate a pre-release may be used as shown below:

  <releases>
    <release version="1.0.1-rc0">
      Further development
    </release>
    <release version="1.0.0" date="2023-04-17">
      Initial version
    </release>
  </releases>

Pack Creation on GitHub

Once changes are committed, GitHub Actions create the pack and the documentation.

Publish Pack

The pack can be hosted on the <url> specified in the *.pdsc file.

Refer to Publish a Pack in the Open-CMSIS-Pack specification for further details.

Issues and Questions

Use Issues on this GitHub to raise questions or submit problems.

Happy Packing!