[cbuild-pack.yml] Document cbuild-pack.yml

[slhultgren]

Document cbuild-pack.yml introduced in PR Open-CMSIS-Pack/devtools#1143

Fixes Open-CMSIS-Pack/devtools#1122

Contributed by STMicroelectronics

Easiest way to read it is by looking at the rendered form https://github.com/slhultgren/cmsis-toolbox/blob/pr/shu-cbuild-pack-documentation/docs/YML-CBuild-Format.md#pack-locking

[slhultgren]

Updated the PR with a bit more clarification on when the cbuild-pack.yml is used and updated:
Easiest to read is here: https://github.com/slhultgren/cmsis-toolbox/blob/pr/shu-cbuild-pack-documentation/docs/YML-CBuild-Format.md#pack-locking

[jkrech]

@slhultgren thanks a lot for adding detail to the documentation regarding the reading and writing of the cbuild-pack.yml file and which csolution commands are affected, as well as the maintenance of entries.
Could you please confirm that the cbuild-pack.yml does not contain any kind of history information anymore and therefore there is no need for a command for cleaning up.

We are frequently discussing the aspect of "backward compatibility". With the introduction of the cbuild-pack.yml the previous behavior is changed such that after installing an updated pack version used by a csolution which does not fix the pack version, the newly installed pack version will not be used.

My request is to add a command line option for both cbuild and csolution that allows to enable/disable the use of cbuild-pack.yml.

For strict backward compatibility the cbuild-pack.yml would be disabled by default and require

   -P --pack-lock-on            Lock pack versions using *.cbuild-pack.yml

We could consider an explicit entry in the csolution.yml file similar to enabling the use of cdefault.yml

solution:
  cdefault:
  cbuild-pack:
  ...

Storing this information in the solution, would allow the csolution tool to throw a warning/error if a solution is processed but no <solution>.cbuild-pack.yml is present (e.g. it was forgotten to be included in an example shipped in a pack)

[ReinhardKeil]

@slhultgren thanks for documenting the feature.

I agree with @jkrech to add a option for enabling this feature.

[ReinhardKeil]

I believe just one option is enough. By default the file *.cbuild-pack.yml is written and records all packs including versions that are used by the project files (*.csolution.yml, *.cproject.yml, *.clayer.yml).

Option:
-P, --pack-lock Use *.cbuild-pack.yml as input file to lock software pack usage.

The option --pack-lock reports an error when the file *.cbuild-pack.yml does not exist, or when there are different packs requested by the project files.

[jkrech]

Looks good to me.
Extensions like command line options to be added in separate PR.