This document describes a build results archive format which can be used to store the sarif results of a build-and-test procedure.
Once created this archive and its contents should not be modified by any downstream program so that the integrity of the original build and its results can be maintained.
Applications which integrate the data and enhance or elaborate it are recommended to maintain their own data storage for these enhancements.
Archives generated locally should make use of the log subdirectory generated by colcon.
Within the log directory a build_results_archives directory should be created if it does not already exist.
colcon uses the format {build,test}_YYYY-MM-DD_HH-MM-SS however this format is not ISO8601 parse-able and is ambiguously in local time.
Since one intended use case of build results archives is sharing and comparing between builds on different machines (thus potentially in different time zones) the timestamp format used for build result archive filenames is explictly in UTC
The recommended filename is formatted build_results_YYYYMMDDTHHMMSSZ.tar.bz2 where YYYYMMDDTHHMMSSZ is a basic-formatted ISO8601 UTC date and time.
When a new build results archive is created locally, a symlink in the log/build_results_archives subdirectory with the name latest_build_results.tar.bz2 should be updated to link relatively to the just-created build archive.
The archive will take the form of a bzip2 compressed tar file containing the files described below.
./build-results-archive
./build/**/*.sarif
./colcon-build-cmd
./colcon-test-cmd
./processed.sarif
./timestamp
./vcs-export-exact.repos
The individual files are further described:
This is a JSON file containing metadata regarding the current archive.
The file must contain an single top-level JSON object and that object must contain the "version" key with the value of 1.
Future revisions of this format may add additional valid versions.
The build/ subdirectory must contain the unaltered sarif content of the workspace build directory after the end of the latest colcon test run.
This file must contain the full colcon build command described in the colcon logs under the latest_build symlink.
The file, when run as a /bin/sh program or prefixed with the exec shell command in a workspace root should invoke colcon in the local environment using the same arguments as the original build.
This file is identical in behavior to colcon-build-cmd but must describe the test command under the latest_test symlink.
This file is optional but recommended. If it is present, the processed/**/*.sarif files must also be present. If present it should be identical to the colcon-build-cmd file in format but must describe instead the command used to generate the processed sarif files.
This directory is optional but recommended.
If it is present, the process-sarif-cmd file must also be present.
If present, it should contain the processed sarif results otherwise preserving the directory structure of sarif files in the build/ directory.
This file must contain basic-formatted ISO8601 UTC of when the results archive was produced. This timestamp is also present in the generated filename but including it within the archive allows the file to be renamed without losing information. Preserving the timestamp in the filename is recommended since this allows sorting the archives lexicographically without inspecting the archive contents.
This file must contain the output of the command vcs export --exact src as run from the workspace root.
The results of this file will then be suitable to reproduce the workspace sources using vcs import src in a clean workspace.