WL#3462 Add testing of MySQL client ABI to prevent unintentional ABI breaks

BUG#23427 incompatible ABI change in 5.0.26?
   - Use the icheck tool if avaliable and compare the current mysql.h to a version
controlled reference file 


BitKeeper/etc/ignore:
  Added include/check_abi include/mysql_h.ic to the ignore list
configure.in:
  Look for icheck in configure
include/Makefile.am:
  Add rule to build mysql_h.ic if icheck is avaliable
  Add rule to compare mysql_h.ic to the version
  controlled reference file mysql_h_abi.ic
include/mysql.h:
  Add comment about taking care when editing mysql.h
  Add example how to add reserved fiels in the structs to
  allow for features to be added without breaking ABI
include/mysql_h_abi.ic:
  Add new file describing the libmysqlclient ABI used as a reference to detect ABI breakage

.bzrignore

@@ -1064,3 +1064,5 @@ vio/test-ssl
 vio/test-sslclient
 vio/test-sslserver
 vio/viotest-ssl
+include/check_abi
+include/mysql_h.ic

configure.in

@@ -508,6 +508,10 @@ AC_SUBST(DOXYGEN)
 AC_SUBST(PDFLATEX)
 AC_SUBST(MAKEINDEX)
 
+# icheck, used for ABI check
+AC_PATH_PROG(ICHECK, icheck, no)
+AC_SUBST(ICHECK)
+
 # Lock for PS
 AC_PATH_PROG(PS, ps, ps)
 AC_MSG_CHECKING("how to check if pid exists")

include/Makefile.am

@@ -15,7 +15,7 @@
 # Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 # MA 02111-1307, USA
 
-BUILT_SOURCES =		mysql_version.h m_ctype.h my_config.h
+BUILT_SOURCES =		mysql_version.h m_ctype.h my_config.h mysql_h.ic
 pkginclude_HEADERS =	my_dbug.h m_string.h my_sys.h my_list.h my_xml.h \
 			mysql.h mysql_com.h mysqld_error.h mysql_embed.h \
 		  	my_semaphore.h my_pthread.h my_no_pthread.h raid.h \
@@ -32,8 +32,10 @@ noinst_HEADERS =	config-win.h config-os2.h config-netware.h \
 			thr_lock.h t_ctype.h violite.h md5.h \
 			mysql_version.h.in my_handler.h my_time.h
 
+CLEANFILES =            mysql_h.ic
+
 # mysql_version.h are generated
-SUPERCLEANFILES =	mysql_version.h my_config.h
+SUPERCLEANFILES =	mysql_version.h my_config.h $(CLEANFILES)
 
 # Some include files that may be moved and patched by configure
 DISTCLEANFILES =	sched.h $(SUPERCLEANFILES)
@@ -55,5 +57,27 @@ link_sources:
 dist-hook:
 	$(RM) -f $(distdir)/mysql_version.h $(distdir)/my_config.h
 
+#
+# Rules for checking that ABI has not changed
+#
+
+# Create a icheck file for mysql.h
+mysql_h.ic: mysql.h
+	@set -x; \
+	if [ @ICHECK@ != no ] ; then \
+	  @ICHECK@ --canonify -o $@ mysql.h; \
+	fi;
+
+# Compare the icheck file to the reference
+check_abi: mysql_h.ic
+	@set -x; \
+	if [ @ICHECK@ != no ] ; then \
+	  @ICHECK@ --compare mysql_h.ic mysql_h_abi.ic; \
+	fi; \
+	touch check_abi;
+
+all: check_abi
+
+
 # Don't update the files from bitkeeper
 %::SCCS/s.%

include/mysql.h

@@ -14,6 +14,17 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
+/*
+  This file defines the client API to MySQL and also the ABI of the
+  dynamically linked libmysqlclient.
+
+  The ABI should never be changed in a released product of MySQL
+  thus you need to take great care when changing the file. In case
+  the file is changed so the ABI is broken, you must also
+  update the SHAREDLIB_MAJOR_VERSION in configure.in .
+
+*/
+
 #ifndef _mysql_h
 #define _mysql_h