diff --git a/examples/chef/README.md b/examples/chef/README.md index 0ccd51193bae73..43b1e744608f84 100644 --- a/examples/chef/README.md +++ b/examples/chef/README.md @@ -58,3 +58,48 @@ Run `chef.py -h` to see the available commands 3. Click on `Save As` and save the file with the name of your new device type into the `devices` folder. This device is now available for the script. See `chef.py -h` for a list of devices available. + +## CI + +### zzz_generated + +To eliminate a dependnecy on ZAP in CI jobs, all chef examples found in `examples/chef/devices` must have their output from the ZAP tool cached in `examples/chef/zzz_generated`. + +To generate the cache, one may execute chef with the option `--generate_zzz`. This will run ZAP for all devices in `examples/chef/devices` and place the output into the appropriate directory structure. + +Other than the output from the ZAP tool, the cache directory contains two additional files for each device: +- `INPUTMD5.txt` contains the md5 hex digest of the ZAP file used to generate the directory. +- `ZAPSHA.txt` contains the commit of ZAP in the user's tree when the directory was generated. + +``` +zzz_generated/ +└── lighting-app + ├── INPUTMD5.txt + ├── zap-generated + │   ├── access.h + │   ├── af-gen-event.h + │   └── ... + └── ZAPSHA.txt +``` + +These additional files will be used by the CI jobs to validate whether the cache must be regenerated i.e. regeneration is needed when ZAP or the input ZAP files change. + +### Workflow + +All CI jobs for chef can be found in `.github/workflows/chef.yaml`. + +#### Validate + +The workflow begins by calling chef with `--validate_zzz`. + +`--validate_zzz` will recalculate the current ZAP commit and the md5 of all example ZAP files and compare with what is committed to `zzz_generated`. + +If the validation job fails, it will provide instructions to repair `zzz_generated` and no builds will run. + +#### Build + +Once the validation job is complete, there is a separate job for each platform, which run in parallel. + +These jobs use a platform-specific image with base `chip-build`. + +The build jobs call chef with the options `--ci -t `. The `--ci` flag will build all examples for the specified platform and for all devices specified in `_CI_ALLOW_LIST` defined in `chef.py` (so long as these devices are also in `/devices`).