/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page createPackPublish Publish a Pack
There are multiple ways to distribute a software pack:

\section cp_prerequisites 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:
  - \c gen_pack.bat script from the \ref PackTutorials
  - or \ref bash_script that does not show any \ref 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 <b>Schema Check</b>: \n
  \image html schema_check.png

- The \b Output window shows the result. If errors are reported, please make sure to fix them before continuing.\n
  \image html schema_check_output.png

\note This is important when the pack should published using a \ref cp_KeilComPack "pack index service". The pack
  importer will ignore all \elem{vendor}.\elem{name}.pdsc files that do fail when checking against the current PACK.xsd schema file
  and thus your pack will cannot be downloaded.


\section cp_LocalInstallation 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 \c \<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 \c \<url\>.

\image html LocalInstallation.png "Local installation and update from URL"

\note For automatic updates on a local machine, specify the \c \<url\> using the
<a href="https://en.wikipedia.org/wiki/File_URI_scheme" target="_blank">file URI scheme</a>.


\section cp_WebDownload Web Download

Any web server can be used to host a software pack (specified by the \c \<url\> element in the PDSC file). At this location,
the following files should be present:
-# \elem{vendor}.\elem{name}.pdsc [required]: pack description file.
-# \elem{vendor}.\elem{name}.\elem{version}.pack [required]: pack file where \elem{version} refers to the latest version
   specified in the PDSC file.
-# \elem{vendor}.pidx [optional]: list with all packs hosted and maintained by the vendor (refer to \ref pidxFile)

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

The \elem{vendor}.pidx allows you to publish multiple packs to a \ref cp_KeilComPack "Pack Index Service".

\section cp_KeilComPack 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 \elem{vendor}.\elem{name}.pdsc or \elem{vendor}.pidx file to the following email addresses:

- for Arm and Keil tools and web pages email to <a href="mailto:CMSIS@arm.com">CMSIS@arm.com</a>
- for IAR tools email to <a href="mailto:CMSIS@arm.com">CMSIS@iar.com</a>

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. <b>Only packs that pass the \ref packChk and schema check</b> 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
(<a href="https://developer.arm.com/embedded/cmsis/cmsis-packs" target="_blank">https://developer.arm.com/embedded/cmsis/cmsis-packs</a>):
- 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.

\section cp_PackRehosting 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 \ref cp_KeilComPack "Pack Index Service", follow this procedure:
- Create a new version of the pack: update the \elem{vendor}.\elem{name}.pdsc file with the new URL ("url_B") and make sure to increment the version
- Place a copy of this latest \elem{vendor}.\elem{name}.pdsc at url_B and url_A (the original URL).
- Place a copy of the new \elem{vendor}.\elem{name}.\elem{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 \elem{vendor}.pidx with url_B for this pack \em or
  - email a link to the PDSC file if your company does not maintain a \elem{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.

\section cp_HowWebDownloadWorks 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 \ref cp_KeilComPack "Pack Index Service" that uses either a \elem{vendor}.\elem{name}.pdsc or a
\elem{vendor}.pidx file to obtain the latest pack versions.  This information is used to make the packs available in the development tools (via a <b><a href="https://www.keil.com/mdk5/packinstaller/">Pack Installer</a></b>) and/or to publish information on certain web pages, for example a <b><a href="https://developer.arm.com/embedded/cmsis/cmsis-packs/devices" target="_blank">device list</a></b>.

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

\image html WebInstallation.png "Web infra-structure for pack hosting services"

\note
- The \<url\> element in \elem{vendor}.\elem{name}.pdsc is the location where these services check for new packs. At this \<url\> location, an (unversioned) \elem{vendor}.\elem{name}.pdsc file
  and a (versioned) \elem{vendor}.\elem{name}.\elem{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 \ref cp_KeilComPack "Pack Index Service" will not recognize that the pack has changed.
- Previous versions of a (versioned) \elem{vendor}.\elem{name}.\elem{version}.pack should remain available.

Depending on the implementation, the web infra-structure may provide index files with additional information:
 - \elem{vendor}.vidx file (\ref vidxFile) 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 \ref cp_prerequisites "validation process".

*/
