diff --git a/docs/tipsandtricks.md b/docs/tipsandtricks.md index 9189b69..892d674 100644 --- a/docs/tipsandtricks.md +++ b/docs/tipsandtricks.md @@ -2,6 +2,88 @@ This chapter contains useful information to help you solve specific issues. +## Archive a project + +For a completed Open-CMSIS-Pack project using CMSIS-Toolbox and the CMSIS Solution project format, you should archive +everything necessary to rebuild, debug, verify, and maintain the firmware independently of the original development +environment. + +### What should be archived + +| Artifact | Examples | Recommendation | +| ---------------------------- | ------------------------------------------------------ | --------------------------------------------------------- | +| CMSIS solution configuration | `*.csolution.yml` | Mandatory | +| CMSIS project configuration | `*.cproject.yml` | Mandatory | +| Build configurations | `*.cbuild.yml`, `*.cbuild-idx.yml` | Archive the resolved configurations | +| Source code | `*.c`, `*.cpp`, `*.h`, assembly | Mandatory | +| Linker configuration | Scatter files, linker scripts | Mandatory | +| RTE configuration | `RTE/`, `RTE_Components.h`, configured component files | Mandatory | +| Generator configuration | `*.cgen.yml`, generator inputs and outputs | Archive when applicable | +| CMSIS-Pack dependencies | DFPs, BSPs, software component packs | Archive exact `.pack` versions | +| Pack lock information | `*.cbuild-pack.yml` | Mandatory for dependency traceability | +| Compiler and build tools | Arm Compiler, GCC, LLVM, CMSIS-Toolbox | Record exact versions; preserve installers where possible | +| Generated firmware | `*.elf`, `*.hex`, `*.bin` | Mandatory for released firmware | +| Debug information | ELF with DWARF, map files | Strongly recommended | +| Test and validation results | Test reports, coverage, analysis results | Mandatory for formal releases | +| Documentation | README, requirements, release notes | Strongly recommended | +| Version-control metadata | Git commit, tag, submodule revisions | Mandatory | + +!!! Note + Files such as `*.cbuild.yml` and `*.cbuild-idx.yml` are generated by CMSIS-Toolbox. They are + useful as records of the resolved build configuration, but they are not substitutes for the original solution and + project definitions. + +### Preserve the complete dependency chain + +A CMSIS project may depend on software components from multiple vendors. Merely preserving their names and version +numbers is insufficient if the original pack repositories become unavailable. + +For long-term reproducibility, preserve: + +- The exact CMSIS-Pack archives (`.pack`) used in the build, including transitive dependencies. +- The compiler version and relevant toolchain binaries or installers. +- The CMSIS-Toolbox version, including `cbuild`, `csolution`, and associated utilities. +- Any external code generators, their configurations, and required runtime dependencies. +- Custom scripts, environment settings, and CI/CD configuration. + +For commercial compilers, licensing and redistribution restrictions may prevent archiving a fully portable toolchain. +At minimum, preserve the version, build identification, installation source, and license requirements. + +### Recommended archive structure + +It is good practice to separate the editable project, its dependencies, and the release evidence: + +📁 MyFirmware-1.0.0/ +╠ 📁 project/ — Source code, solution files, layers, RTE configuration +╠ 📁 packs/ — Exact `.pack` dependencies +╠ 📁 toolchain/ — Tool versions, manifests, installers where permitted +╠ 📁 firmware/ — ELF, HEX, BIN and map files +╠ 📁 verification/ — Test reports, analysis results, build logs +╠ 📁 documentation/ — Release notes, build instructions, SBOM +╚ 📄 manifest.yml — Versions, hashes, Git revision, build environment + +Include a SHA-256 checksum for each released binary and ideally for all archived dependencies. + +### Verify that the archive is reproducible + +Before declaring the archive complete, rebuild the firmware in a clean environment. + +CMSIS-Toolbox supports the `--frozen-packs` option, which checks the pack dependencies against `*.cbuild-pack.yml` and +prevents unintended changes to the resolved pack set. + +```sh +cbuild MyFirmware.csolution.yml \ + --frozen-packs \ + --rebuild +``` + +This command assumes that all required packs and toolchains are already installed. It does not itself guarantee +bit-for-bit identical binaries. For that, compare the resulting firmware with the archived release and investigate +differences caused by timestamps, build paths, compiler settings, or other nondeterministic inputs. + +!!! Note + It is recommended to commit the solution inputs, all RTE files, and `*.cbuild-pack.yml` to version control. + ## Create vcpkg configuration file If your solution does not contain a `vcpkg-configuration.json` file, click on