Golden files help ensure that changes to the Fuchsia System Interface are expected and acknowledged.
API level-specific golden files are stored in the SDK history directory. API level-independent golden files with the extension .api are stored throughout fuchsia.git, though are usually under //sdk/ and with the associated library definition.
For stable and exposed (in the IDK) FIDL libraries, there are API level-specific .api_summary.json golden files within //sdk/history. For every such library, there is an .api_summary.json in each of the API level subdirectories. If the library is not supported at a given API level, the file will be empty.
There should be no changes to golden files when making modifications at HEAD, which is usually the first step in making a change. When promoting that change to NEXT, the corresponding file(s) in //sdk/history/NEXT/ need to be updated. When adding a new library and in other rare cases, the corresponding files for all supported API levels will need to be added or updated, respectively.
FIDL libraries also have API level-independent .api golden files.
The best way to generate/test all the FIDL golden files is to run:
fx build //sdk/fidl:compatibility_tests
When modifying files for stable (numbered) API levels, it may be necessary to use update_goldens = true in your fx args to avoid build errors.
There are many golden files, often with the extension api, that are independent of the API level. These are generated and checked when building the relevant code in the main build (normal fx build, not a sub-build). These files can currently be found throughout fuchsia.git.
These files generally need to be updated whenever a change is made to the covered source file(s).
Finally, there are API level-specific golden files for non-FIDL interfaces. For example, .ifs files for shared libraries. These must be generated by a sub-build for the appropriate API level.
There should be no changes when making modifications at HEAD, which is usually the first step in making a change. When promoting that change to NEXT, the corresponding file(s) in //sdk/history/NEXT/ need to be updated as described in the following section.
NEXTThere are two ways to do generate golden files for NEXT. The second, longer option may be necessary in rare cases that affect multiple API levels.
fx build -- -C $(fx get-build-dir)/idk_subbuild.fuchsia_collection_for_subbuilds-apiNEXT-x64 sdk:fuchsia_collection_for_subbuilds
It is recommended to use update_goldens = true in your fx args because the command lines in the error message are currently incorrect for sub-builds (https://fxbug.dev/384955652).
See All sub-builds.
It is recommended to use update_goldens = true in your fx args since there may be files from multiple API levels to update.
The following command will generate goldens for all versioned FIDL libraries and API level-independent golden files for most other libraries in the Fuchsia IDK. It will not generate non-FIDL API level-specific golden files.
fx build //sdk:generate_compatibility_goldens
You must include --with //sdk:generate_compatibility_goldens in your fx set command in order to build this target.