# Chef Build Conventions ## Overview It is convenient to follow some naming and build conventions for Chef tool due to the large volume of sample apps that may be created and the ambiguity that may result from arbitrary names. There are three components to the convention proposed here: 1. The naming convention for the sample matter device and clusters (referred to here as the `sample app`). 2. The naming convention to use for the build files which will be flashed on the devices. 3. The usage of metadata files that shall accompany build files to provide more detailed information about builds. The convention proposed here should be adopted by the zap files provided in `examples/chef/devices` and the builds generated from Chef tool in CI. ## Limitations The largest filename that can be used on MacOS and Linux is 255 characters. If a sample app name would exceed this limit by following this convention, then the sample app should be given an arbitrary name. This limitation is called out, but, with the given naming conventions, this should rarely happen. ## Convention ### Sample App Naming Convention Sample apps should be named by concatenating the name of all endpoints in the order of their index. Endpoint names are separated by underscores (`_`) and a 10 character hash[^hash_note] of the sample app metadata is appended to the end. Valid sample app names conform to the following format: ``` __ ``` For example, here are some valid names: ``` rootnode_extendedcolorlight_H1l9gnQDYl rootnode_speaker_8qRQaEj0Hy rootnode_lightsensor_L6dEbmVDah rootnode_dimmablelight_rWsDiwzw2t rootnode_pressuresensor_03quf7tPOL rootnode_flowsensor_ixbAboycie rootnode_windowcovering_b9QoiScjOq rootnode_doorlock_d5wtU7sjFR rootnode_thermostat_KuQYArmwl7 rootnode_dimmablelight_7pNE3GVarn rootnode_temperaturesensor_i0wGnDVUAc rootnode_occupancysensor_wyGeQSokNp rootnode_humiditysensor_pv0comNKyT bridgednode_temperaturesensor_onofflight_onoffpluginunit_MI9DSdkH8H ``` [^hash_note]: The 10 character hash is a base64 encoding of the md5 hash generated by digesting the JSON string encoding of the metadata information. The code for generating the hash can be found in `generate_hash` in [zap_file_parser](https://github.com/project-chip/connectedhomeip/blob/master/zap_file_parser.py) There are some notable details here: 1) The full base64 encoded hash is 16 characters, but only 10 are used. This still gives us a sufficiently low probability of collision (~1.2 x 10^-8). 2) `_` and `-` are replaced in the base64 encoding because they have other uses in the naming. 3) Platform specific information is omitted from the hash. E.g. the networking_commissioning cluster is excluded. This is to make the hashes platform agnostic. ### Sample App Build Naming Convention The sample app builds formats will be named by pre-pending the zap file name (described above) with the platform and appending connectivity info. Valid build names conform to the following format: ``` _ ``` Note that `` follows the convention: `__`. Together that is: ``` ___ ``` The list of platforms supported here (as of writing this) are: ``` m5stack brd4161a nrf52840dk linux_x86 ``` For example, here are some valid names: ``` m5stack_rootnode_humiditysensor_pv0comNKyT brd4161a_rootnode_humiditysensor_pv0comNKyT nrf52840dk_rootnode_humiditysensor_pv0comNKyT linux_x86_rootnode_humiditysensor_pv0comNKyT ``` ### Metadata file convention Metadata files are `yaml` files that should accompany build files. The metadata files have a structure as follows: ``` - : client_clusters: : attributes: : ... commands: - - ... server_clusters: : attributes: : ... commands: - - ... - : ... ``` For an example, see [sample_zap_file_hashmeta.yaml](https://github.com/project-chip/connectedhomeip/blob/master/examples/chef/sample_app_util/test_files/sample_zap_file_hashmeta.yaml) which was generated from [sample_zap_file.zap](https://github.com/project-chip/connectedhomeip/blob/master/examples/chef/sample_app_util/test_files/sample_zap_file.zap). Note that it is more readable in `yaml` format. Since hashes are generated from the metadata info, additional conventions are needed to ensure consistency for the metadata structure. The following conventions are used: - All lists are sorted alphabetically. - If a list contains dictionaries, it will be sorted by the "name" key. If it does not contain "name" key, it will be sorted by the first key common to all dictionaries that comes first alphabetically. - The list of endpoints is excluded from the above conventions. Endpoints are ordered according to their endpoint number; here, the endpoint number is the same as the order they are read from the zap file. As an example, take a look at [sample_zap_file.yaml](https://github.com/project-chip/connectedhomeip/blob/master/examples/chef/sample_app_util/test_files/sample_zap_file.yaml) ## Utility Usage There are a few primary usage cases for the utility [sample_app_util.py](https://github.com/project-chip/connectedhomeip/blob/master/sample_app_util.py). Details are provided by using `python sample_app_util.py zap --help`. Below is a summary. | Command | Description | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `python sample_app_util.py zap --generate-name` | Generates the name for a zap file per the specified convention | | `python sample_app_util.py zap --rename-file` | Renames the zap file per specified convention | | `python sample_app_util.py zap --generate-metadata [output_path]` | Generates the metadata file adjacent to the zap file with `.yaml` extension. If `[output_path]` is provided then the metadata file will be stored at the location specified. | ## Running Tests Navigate to the base directory of this README. ``` cd /examples/chef/sample_app_util ``` Run unit tests. ``` python -m unittest ```