How to Check for API/ABI Breakage: add support to packages providing multiple libraries

Signed-off-by: Dylan Aïssi <dylan.aissi@collabora.com>

content/guides/how_to_check_for_api_breakage.md

@@ -194,6 +194,77 @@ implications.
 The source compatibility tab reports similar information than the binary
 compatibility tab.
 
+## Packages providing multiple libraries
+
+Support of packages providing multiple libraries has been added in
+`apertis-dev-tools` version `0.2022.1`.
+
+For packages providing multiple libraries, it is highly recommended to provide
+a library XML descriptor for each library provided in the package.
+`abi-compliance-checker` requires this file to analyze a library. In order to
+facilitate the analysis, `apertis-abi-compare` generates a simple XML descriptor
+file that should work in simple case. Unfortunately, this feature is not smart
+enough for packages containing multiple libraries. The tool cannot separate
+headers between libraries, thus it assigns all headers to each library.
+
+The library descriptor file is handwritten as described in the following
+[library descriptor]({{< ref "#example-of-library-descriptor" >}}) paragraph.
+
+{{% notice info %}}
+The `zlib` package, used in the above example, is a special case of a source
+package providing multiple libraries. From the source package, several binary
+packages can be generated `zlib1g`, `lib64z1`, `lib32z1` and `libn32z1`.
+The main package `zlib1g` provides the library in a standard way whereas
+the other packages provide a different version of the library. In other words,
+they provide a 64 bit version of the library for 32 bits architectures or the
+other way around. Thus, all packages provide the same library, but for
+different architectures which is not possible to compare with
+`abi-compliance-checker`.
+
+Therefore, the `zlib` package cannot be used by `apertis-abi-compare` to test
+the support of packages providing multiple libraries.
+{{% /notice %}}
+
+
+## Example of library descriptor
+
+To be detected by `apertis-abi-compare`, the descriptor file must be named
+`MYLIB-abi-descriptor.xml` (where `MYLIB` is the related library name) and must
+be installed by your `lib***-dev` package. The recommended installation path is
+`/usr/share/doc/lib***-dev/` to be in compliance with the Debian Policy, but the
+path does not matter because `apertis-abi-compare` will scan all files installed
+by the `lib***-dev` package to find a file called `*-abi-descriptor.xml`.
+
+Below is a basic example for `zlib` named `zlib-abi-descriptor.xml`:
+```xml
+<ABI_Descriptor>
+  <version>
+    ${VER}
+  </version>
+  <headers>
+    ${PATH}/usr/include/zconf.h
+    ${PATH}/usr/include/zlib.h
+  </headers>
+  <libs>
+    ${PATH}/usr/lib/libz.so
+  </libs>
+</ABI_Descriptor>
+```
+
+This file contains three parts: the first one describes the version of the
+described library, the second one lists all library headers with their path
+and the last one defines the library path.
+
+In order to prevent having to modify this file for each new version, we use ${VER} and
+${PATH} variables which are filled by `apertis-abi-compare`. They refer to the
+package version and the path where the package was extracted. Although it is
+not necessary to use the ${VER} variable, not having the ${PATH} variable will
+result in a failure of `abi-compliance-checker`.
+
+Please refer to the documentation of `abi-compliance-checker` to know how to
+write it: [library descriptor documentation](https://lvc.github.io/abi-compliance-checker/Xml-Descriptor.html).
+
+
 # How to enable the apertis-abi-compare job in the build pipeline
 
 The `apertis-abi-compare` tool is only useful for comparing ABI of different
@@ -247,17 +318,20 @@ This report contains all information useful to understand the ABI breaks
 detected as explained in the previous part above.
 ![](/images/abi_checker_job_report_broken.png)
 
-# Limitations
-- The `apertis-abi-compare` tool only supports source packages providing a
-single library. For source packages building multiple libraries, only one
-library will be analyzed.
 
+# Limitations
 - The `abi-compliance-checker` tool which is used by `apertis-abi-compare` is
 only able to compare libraries for the current architecture. Indeed, it compiles
 headers in order to create an ABI dump. Since GitLab runners run on Intel
 machines, this means only x86_64 can be checked and we can't check the ABI of
 ARM packages.
 
+- To analyze packages containing multiple libraries it is highly recommended to
+provide XML descriptors. See the
+[Packages providing multiple libraries]({{< ref "#packages-providing-multiple-libraries" >}})
+paragraph for a comprehensive explanation.
+
+
 # FAQ
 
 ## abi-compliance-checker fails to build headers
@@ -266,11 +340,6 @@ case, you need to provide and customize a library XML descriptor. Please refer
 to the documentation of `abi-compliance-checker` to know how to write it:
 [library descriptor documentation](https://lvc.github.io/abi-compliance-checker/Xml-Descriptor.html).
 
-To be detected by `apertis-abi-compare`, the descriptor file must be named
-`abi-descriptor.xml` and must be installed by your `lib***-dev` package in
-`/usr/share/doc/lib***-dev/`. The location of the installation does not matter
-because `apertis-abi-compare` will scan all files installed by the `lib***-dev`
-package to find a file called `abi-descriptor.xml`.
 
 # References
 - [ABI Compliance Checker](https://lvc.github.io/abi-compliance-checker/)