Add documentatin and tooling to help maintain ABI compatibility.

Author: SiegeLordEx

README_abi.txt

@@ -0,0 +1,44 @@
+ABI Compatibility Guidelines
+============================
+
+# ABI description
+
+Allegro is split into the core library (`liballegro`) and addons (e.g.
+`liballegro_image`). The public API starts with `al_` for functions and
+`ALLEGRO_` for types. The private API that is used by the addons starts with
+`_al` for functions and `_AL` for types. There are some exceptions where there
+are some `ALLEGRO_` types defined in `aintern_*.h` headers. Despite their names
+starting with `ALLEGRO_` those are private types.
+
+Within a minor version (5.0, 5.2 etc) we maintain ABI backwards compatibility
+only for public API. This means that we can't remove functions (even if we turn
+them into compatibility functions), can't change their arguments. For types, we
+can't change their size. If the type is not opaque, this means we can't add or
+remove fields, change their types. These considerations do not apply to private
+APIs: Allegro addons and Allegro core are intended to match in their precise
+version when used together. Therefore private APIs have no backwards compatibility.
+
+Similarly, the unstable public API (marked as such in the documentation) also
+does not come with backwards guarantees.
+
+# Tooling
+
+To help maintain ABI compatibility we provide two scripts. To use them you must
+be on Linux and have built the non-monolith version of the library with debug
+symbols (e.g. RelWithDebInfo). First, we have `misc/generate_abi.sh`:
+
+```bash
+./misc/generate_abi.sh $BUILD_DIR
+```
+
+This is used to generate "golden" ABI XML files which are checked in and
+updated every release. Then, there's `misc/compare_abi.sh`:
+
+```bash
+./misc/compare_abi.sh $BUILD_DIR
+```
+
+This is run before making a release to check for ABI compatibility regressions.
+Check over the outputs of this script to make sure the ABI compatibility is
+maintained. This process is manual due to the somewhat complex ABI guarantees,
+but we'll strive to make this more automatic in the future.

README_releasing.txt

@@ -4,7 +4,13 @@ How to Make a Release
 This guide explains how to make an Allegro release. This all assumes that we're
 on Linux.
 
-1.  Starting with the master branch, pick a commit which you want to be the base of
+1.  First, build the library with the addons, and run the
+    `./misc/compare_abi.sh` to check if ABI compatibility has been maintaned
+    (see README_abi.txt). Fix any regressions and along the way make sure that
+    the newly added public APIs are correctly classified as unstable and are
+    documented.
+
+2.  Starting with the master branch, pick a commit which you want to be the base of
     the release branch. Typically this will be HEAD, but if there are some
     underbaked commits there, you may want to use an earlier commit. Call this
     branch with the new release name (e.g. 5.2.2 in this case):
@@ -17,51 +23,55 @@ on Linux.
 
         git cherry-pick -x badf00d
 
-2.  On the master branch, bump the version to the next release in
+3.  On the master branch, bump the version to the next release in
     `include/allegro5/base.h` by using the `misc/fixver.sh` script. Commit this
     change. For example:
 
         misc/fixver.sh 5 2 3 GIT
 
-3.  Write a changelog file. This is located in docs/src/changes-5.2.txt.
+4.  Write a changelog file. This is located in docs/src/changes-5.2.txt.
 
     Typically you will want to look through the commits made since the last
     release, e.g. using `git log <last_release>..<this_release>` (e.g. `git log
     5.2.1..5.2.2`). Follow the format of the previous changelogs. Commit this
     change.
 
-4.  We are now done with the master branch. Check out the release branch now.
+5.  Generate the new ABI files using `./misc/generate_abi.sh`. Commit the
+    changes.
+
+6.  We are now done with the master branch. Check out the release branch now.
 
-5.  Cherry-pick the commit with the changelog onto this branch.
+7.  Cherry-pick the commit with the changelog and the ABI changes onto this
+    branch.
 
-6.  Remove the "GIT" suffix and increase the version by 1. This can be done via
+8.  Remove the "GIT" suffix and increase the version by 1. This can be done via
     `misc/fixver.sh` script. Commit this change. For example:
 
        misc/fixver.sh 5 2 2 0
 
-7.  Tag the previous commit with the same version number and the release number
+9.  Tag the previous commit with the same version number and the release number
     (e.g. "5.2.2.0" if you're releasing 5.2.2. An example command would be:
 
         git tag -a -m "Tag 5.2.2.0" 5.2.2.0
 
-8.  Create the source archives by running `misc/create_release_archives.sh` and
+10. Create the source archives by running `misc/create_release_archives.sh` and
     passing in the release version. This will create 3 source archives (.tar.gz,
     .7z and .zip) in the current directory. And example invocation would be:
 
         misc/create_release_archives.sh 5.2.2.0
 
-10. At this point you could do some additional checks (like making binaries).
+11. At this point you could do some additional checks (like making binaries).
 
-11. If all checks are good, push the master and release branches to github
+12. If all checks are good, push the master and release branches to github
     (with the --tags option).
 
-12. Upload the source archives to github. Go to the releases tab, and make a
+13. Upload the source archives to github. Go to the releases tab, and make a
     new release with the tag you just created.
 
-13. Build the docs, including the pdf. Add these to the website via the
+14. Build the docs, including the pdf. Add these to the website via the
     liballeg.github.io repository.
 
-14. Make an announcement on the website. This involves making a news item,
+15. Make an announcement on the website. This involves making a news item,
     changing the download area and copy-pasting the change list.
 
-15. Make an announcement on Discord. You're done!
+16. Make an announcement on Discord. You're done!

misc/compare_abi.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+#set -e
+
+build_dir="${1}"
+
+if [[ -z "${build_dir}" ]]
+then
+    echo "Usage: $0 <build-dir>"
+    exit 1
+fi
+
+if ! $(which abidw > /dev/null 2>&1)
+then
+    echo "abidw not found"
+    exit 1
+fi
+
+library_paths=("${build_dir}"/lib/*.so)
+abidiff_args=(
+   --suppressions misc/suppressions.abignore
+   --leaf-changes-only
+)
+
+for library_path in "${library_paths[@]}";
+do
+   library_filename=$(basename "${library_path}")
+   library="${library_filename%.*}"
+   abi_path="misc/${library}_abi.xml"
+   echo Comparing ${library}
+   header=$(cat <<HEADER
+================================
+Comparing ${library}
+================================
+
+HEADER
+   )
+   report=$(abidiff "${abidiff_args[@]}" "${abi_path}" "${library_path}")
+
+   printf "%s\n%s" "${header}" "${report}" | less
+done

misc/generate_abi.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+set -e
+
+build_dir="${1}"
+
+if [[ -z "${build_dir}" ]]
+then
+    echo "Usage: $0 <build-dir>"
+    exit 1
+fi
+
+if ! $(which abidw > /dev/null 2>&1)
+then
+    echo "abidw not found"
+    exit 1
+fi
+
+library_paths=("${build_dir}"/lib/*.so)
+abidw_args=(
+   --suppressions misc/suppressions.abignore
+   --exported-interfaces-only
+)
+
+for library_path in "${library_paths[@]}";
+do
+   library_filename=$(basename "${library_path}")
+   library="${library_filename%.*}"
+   out_path="misc/${library}_abi.xml"
+   echo Generating $out_path
+   abidw "${abidw_args[@]}" "${library_path}" --out-file "${out_path}"
+   sed -i "s@$(pwd)/@@g" "${out_path}"
+done