From 06f41abd7674d75107e57afba0223a442b33453b Mon Sep 17 00:00:00 2001
From: Mu-Le Lee <mulelee@google.com>
Date: Fri, 12 Aug 2022 09:06:37 +0000
Subject: [PATCH] Update README in header checker for header-abi-diff
 configuration

Add description of the config format and logic for developer to add
flags to header-abi-diff in Cross-Version ABI Check.

Test: no need
Bug: 239790286
Change-Id: I5b8fbe57aaafd1357495395a416a5d6b51f0ff3f
---
 vndk/tools/header-checker/README.md | 58 +++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/vndk/tools/header-checker/README.md b/vndk/tools/header-checker/README.md
index 47f9a9266..44079048d 100644
--- a/vndk/tools/header-checker/README.md
+++ b/vndk/tools/header-checker/README.md
@@ -78,6 +78,64 @@ For more command line options, run `header-abi-diff --help`.
 * `16`: ELF incompatible (Some symbols in the `.dynsym` table, not exported by
   public headers, were removed.)
 
+### Configuration
+header-abi-diff reads a config file named `config.json`. The config file must
+be placed in the dump directory, such as
+`prebuilts/abi-dumps/platform/33/64/x86_64/source-based/config.json`.
+The file consists of multiple sections. There are two types of config sections:
+global config section and library config section. Each library config section
+contains flags for a specific version and a library. header-abi-diff chooses
+the library config section by options `-target-version` and `-lib`.
+header-abi-diff applies cli flags first, then the global config section and
+library config section.
+
+#### Target version
+The Soong Build System performs Cross-Version ABI Check. For example, when the
+future SDK version of current source is 34, the source ABI dump would be diffed
+with version 33 dump to check the backward compatibility. In this case, the
+`-target-version 34` is passed to header-abi-diff to select the corresponding
+config section.
+
+#### Format
+Here is an example of a config.json.
+```json
+{
+  "global": {
+    "flags": {
+      "allow_adding_removing_weak_symbols": true,
+    },
+  },
+  "libfoo": [
+    {
+      "target_version": "current",
+      "flags": {
+        "check_all_apis": true,
+      },
+    },
+    {
+      "target_version": "34",
+      "flags": {
+        "allow_extensions": true,
+      }
+    }
+  ]
+}
+```
+
+#### Library Config Section
+A library config section includes two members: "target_version" and "flags".
+header-abi-diff selects the config section that matches the target version
+given by cli.
+Take above config as an example, if `-target-version 34` and `-lib libfoo` are
+specified, the selected config section is:
+```json
+{
+  "target_version": "34",
+  "flags": {
+    "allow_extensions": true,
+  }
+}
+```
 
 ## Create Reference ABI Dumps