ABI stability
For -STABLE branches, it's important to make sure that ABI is compatible across dot releases (in other words, user can expect applications that is compiled for X.0 would run without modification on any X.y releases). We also try to maintain ABI compatibility across .0 releases, but they are not strictly enforced except for libraries that already implements versioned symbols.
Use of abi-compliance-checker
devel/abi-compliance-checker is a Perl script that can dump and compare sets of header files and libraries that are considered as part of ABI. First, a "descriptor" XML file has to be created to nominate the headers and the libraries.
The following is an example (note that quite a few headers were omitted here):
<version>
11.0
</version>
<headers>
/usr/include/a.out.h
/usr/include/arpa/inet.h
/usr/include/arpa/nameser.h
/usr/include/assert.h
/usr/include/atf-c.h
/usr/include/ctype.h
/usr/include/db.h
/usr/include/dirent.h
/usr/include/dlfcn.h
/usr/include/elf-hints.h
/usr/include/elf.h
/usr/include/err.h
/usr/include/errno.h
/usr/include/fcntl.h
/usr/include/fenv.h
/usr/include/float.h
/usr/include/fmtmsg.h
/usr/include/fnmatch.h
/usr/include/fstab.h
/usr/include/fts.h
/usr/include/ftw.h
/usr/include/getopt.h
/usr/include/glob.h
/usr/include/grp.h
/usr/include/iconv.h
/usr/include/ieeefp.h
/usr/include/ifaddrs.h
/usr/include/inttypes.h
/usr/include/langinfo.h
/usr/include/libgen.h
/usr/include/libutil.h
/usr/include/limits.h
/usr/include/link.h
/usr/include/locale.h
/usr/include/math.h
/usr/include/monetary.h
/usr/include/mpool.h
/usr/include/ndbm.h
/usr/include/net/ethernet.h
/usr/include/net/firewire.h
/usr/include/net/if.h
/usr/include/net/if_dl.h
/usr/include/net/if_types.h
/usr/include/net/route.h
/usr/include/netconfig.h
/usr/include/netdb.h
/usr/include/netinet/in.h
/usr/include/netinet/in_systm.h
/usr/include/netinet/ip.h
/usr/include/netinet/ip6.h
/usr/include/netinet/ip_var.h
/usr/include/netinet/sctp.h
/usr/include/netinet/sctp_uio.h
/usr/include/netinet/tcp.h
/usr/include/netinet6/in6_var.h
/usr/include/nl_types.h
/usr/include/nss.h
/usr/include/nsswitch.h
/usr/include/paths.h
/usr/include/poll.h
/usr/include/printf.h
/usr/include/pthread.h
/usr/include/pthread_np.h
/usr/include/pwd.h
/usr/include/readpassphrase.h
/usr/include/regex.h
/usr/include/res_update.h
/usr/include/resolv.h
/usr/include/runetype.h
/usr/include/sched.h
/usr/include/search.h
/usr/include/semaphore.h
/usr/include/setjmp.h
/usr/include/signal.h
/usr/include/spawn.h
/usr/include/stdarg.h
/usr/include/stdbool.h
/usr/include/stddef.h
/usr/include/stdint.h
/usr/include/stdio.h
/usr/include/stdlib.h
/usr/include/string.h
/usr/include/stringlist.h
/usr/include/strings.h
/usr/include/sys/acl.h
/usr/include/sys/aio.h
/usr/include/sys/capsicum.h
/usr/include/sys/cdefs.h
/usr/include/sys/disklabel.h
/usr/include/sys/elf.h
/usr/include/sys/endian.h
/usr/include/sys/errno.h
/usr/include/sys/eui64.h
/usr/include/sys/event.h
/usr/include/sys/exec.h
/usr/include/sys/extattr.h
/usr/include/sys/fcntl.h
/usr/include/sys/file.h
/usr/include/sys/filio.h
/usr/include/sys/gmon.h
/usr/include/sys/ioctl.h
/usr/include/sys/ipc.h
/usr/include/sys/limits.h
/usr/include/sys/mac.h
/usr/include/sys/mman.h
/usr/include/sys/mount.h
/usr/include/sys/param.h
/usr/include/sys/poll.h
/usr/include/sys/proc.h
/usr/include/sys/queue.h
/usr/include/sys/resource.h
/usr/include/sys/select.h
/usr/include/sys/sem.h
/usr/include/sys/signal.h
/usr/include/sys/socket.h
/usr/include/sys/sockio.h
/usr/include/sys/stat.h
/usr/include/sys/statvfs.h
/usr/include/sys/stddef.h
/usr/include/sys/syscall.h
/usr/include/sys/sysctl.h
/usr/include/sys/syslog.h
/usr/include/sys/time.h
/usr/include/sys/timeb.h
/usr/include/sys/times.h
/usr/include/sys/types.h
/usr/include/sys/ucontext.h
/usr/include/sys/ucred.h
/usr/include/sys/uio.h
/usr/include/sys/umtx.h
/usr/include/sys/un.h
/usr/include/sys/utsname.h
/usr/include/sys/vdso.h
/usr/include/sys/wait.h
/usr/include/sysexits.h
/usr/include/syslog.h
/usr/include/termios.h
/usr/include/time.h
/usr/include/timeconv.h
/usr/include/ttyent.h
/usr/include/uchar.h
/usr/include/ucontext.h
/usr/include/ulimit.h
/usr/include/unistd.h
/usr/include/utime.h
/usr/include/utmpx.h
/usr/include/uuid.h
/usr/include/vis.h
/usr/include/vm/pmap.h
/usr/include/vm/vm.h
/usr/include/vm/vm_param.h
/usr/include/wchar.h
/usr/include/wctype.h
/usr/include/wordexp.h
/usr/include/xlocale.h
</headers>
<libs>
/lib/libc.so.7
</libs>Once a descriptor file is created, the ABI can be dumped using:
abi-compliance-checker.pl -l c -dump libc-11.0.xml
Now, assuming that we want to check the same library on 11.1-RELEASE, change the version number of libc-11.0.xml and save it as libc-11.1.xml and do the same dump, then dump in a similar manner.
We would then have two files on the two systems: abi_dumps/libc/libc_11.0.abi.tar.gz and abi_dumps/libc/libc_11.1.abi.tar.gz.
The report can then be generated by using:
abi-compliance-checker.pl -l c -d1 abi_dumps/FreeBSD/FreeBSD_11.0.abi.tar.gz -d2 abi_dumps/FreeBSD/FreeBSD_11.1.abi.tar.gz