From d075fb7af61784053a04898c81ef9170fa1d1ff7 Mon Sep 17 00:00:00 2001
From: Francesco Montorsi <f18m_cpp217828@yahoo.it>
Date: Sun, 1 Feb 2009 17:17:58 +0000
Subject: [PATCH] add the abicheck.sh script for checking possible ABI
 violations

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58600 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/tech/tn0020.txt | 11 +++++--
 lib/abicheck.sh      | 77 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+), 3 deletions(-)
 create mode 100755 lib/abicheck.sh

diff --git a/docs/tech/tn0020.txt b/docs/tech/tn0020.txt
index 27406c6905..e83c319a62 100644
--- a/docs/tech/tn0020.txt
+++ b/docs/tech/tn0020.txt
@@ -271,10 +271,15 @@ binary compatibility between those releases.
 You can also break into your debugger or whatever program you want
 to use and check the memory layout of the class.  If it is the same
 then it is binary compatible.
+(In GDB the command x/d will show addresses as pointers to functions if
+possible so you can see if the order of the functions in vtbl doesn't change.)
 
-Also remember to look at http://www.wxwidgets.org/bincompat.html page which
-summarizes the results of testing of all the samples built against old
-libraries headers with the new library binaries under Unix.
+Another way to check for binary compatibility is to build wxWidgets in shared mode
+and use the 'abicheck.sh --generate' script before doing your changes to generate
+the current ABI (if the 'expected_abi' file is not already in the repo).
+Then rebuild wxWidgets with your changes and use 'abicheck.sh' to compare the
+resulting ABI with the expected one.
+Note that the abicheck.sh script is in the "lib" folder.
 
 
 === EOF ===
diff --git a/lib/abicheck.sh b/lib/abicheck.sh
new file mode 100755
index 0000000000..d46e64a917
--- /dev/null
+++ b/lib/abicheck.sh
@@ -0,0 +1,77 @@
+#!/bin/bash
+
+# Script originally based on GTK+'s own abicheck.sh; it should be run anytime
+# there is a change in the stable branch of wxWidgets which could lead to an
+# ABI breakage and thus result in a binary-incompatible change (see tech docs).
+#
+# $Id$
+
+
+expected_abi_file="expected_abi"
+actual_abi_file="actual_abi"
+
+if [[ "$1" == "--generate" ]]; then
+
+    # IMPORTANT: we need a shared build of wxWidgets to proceed
+    if [[ $(echo *.so) == "*.so" ]]; then
+        echo "No shared objects (*.so) were found... aborting"
+        exit 1
+    fi
+
+    # generated the "expected ABI" for later comparison
+    rm -f $expected_abi_file
+    for library in *.so; do
+        # NOTE: don't use -C option as otherwise cut won't work correctly
+        nm -D -g --defined-only $library | cut -d ' ' -f 3 | sort >>$expected_abi_file
+    done
+
+    echo "Expected wxWidgets ABI generated in \"$expected_abi_file\"..."
+
+elif [[ -z "$1" ]]; then
+
+    if [[ ! -f "$expected_abi_file" ]]; then
+        echo "The file containing the expected wxWidgets ABI '$expected_abi_file' does not exist!"
+        echo "Please generate it first using the '--generate' option"
+        exit 1
+    fi
+
+    echo "Comparing actual ABI with the expected ABI (loading it from \"$expected_abi_file\")..."
+
+    # IMPORTANT: we need a shared build of wxWidgets to do the check
+    if [[ $(echo *.so) == "*.so" ]]; then
+        echo "No shared objects (*.so) were found... aborting"
+        exit 1
+    fi
+
+    rm -f $actual_abi_file
+    for library in *.so; do
+        # NOTE: don't use -C option as otherwise cut won't work correctly
+        nm -D -g --defined-only $library | cut -d ' ' -f 3 | sort >>$actual_abi_file
+    done
+
+    result=`diff -u $expected_abi_file $actual_abi_file`
+
+    if [[ -z "$result" ]]; then
+        echo "No binary (in)compatible changes were found."
+    else
+        echo "========================================================="
+        echo "WARNING: Possible binary-incompatible changes were found:"
+        echo "========================================================="
+        echo
+        echo "$result"
+
+        # this doesn't necessarly indicate that binary compatibility was surely
+        # broken; e.g. adding non-virtual methods will generate a new line in the
+        # $actual_abi_file but that's a compatible change.
+    fi
+
+else
+
+    echo "Usage: $0 [--generate]"
+    echo "When running without options, compares the wxWidgets ABI saved in '$expected_abi_file'"
+    echo "with the current ABI of the .so files of the working directory."
+    echo "When --generate is given, saves in '$expected_abi_file' the ABI of the .so files"
+    echo "(for later comparisons)."
+
+fi
+