1 INTERFACE_CMP(1ONBLD) illumos Build Tools INTERFACE_CMP(1ONBLD) 2 3 4 5 NAME 6 interface_cmp - compare shared object interface descriptions 7 8 SYNOPSIS 9 interface_cmp [-dot] [-e exfile] old new 10 11 DESCRIPTION 12 The interface_cmp command compares the interface definition files for 13 two workspaces and reports versioning inconsistencies. Interface 14 definition files are created by interface_check. 15 16 interface_cmp is typically called from nightly(1ONBLD) when the -A 17 option is in effect following the creation of a new database by 18 interface_check. To insure symbolic interface consistency between 19 successive software releases, existing version definitions and their 20 symbol association should remain intact. Any discrepancies between the 21 two interface definitions are flagged as errors. 22 23 Note that version definition inheritance has the effect of causing a 24 symbol to be viewed as existing in multiple definitions. This insures 25 that both version definitions and their inheritance relationship are 26 processed as part of the comparison. 27 28 OPTIONS 29 The following options are supported: 30 31 -c vertype_module 32 By default, interface_cmp is customized for the versioning 33 conventions used by the Solaris OSnet code base. This specialized 34 information, which includes the recognition of the SUNW_ prefix and 35 other special names, is contained in a perl module named 36 onbld_elfmod_vertype.pm, which is delivered with the SUNWonbld 37 tools. This module is loaded by interface_cmp at runtime. The -c 38 option can be used to supply an alternative module, customized for 39 a different code base, allowing interface_cmp to operate on code 40 from other projects. The alternative module must supply the same 41 module and calling interfaces as the standard module. 42 43 -d Asserts that the new interface is a direct descendant of old. If 44 so, the following additional checks are enabled: 45 46 o The top version of an inheritance chain must not increase by 47 more than one. 48 49 o The new interface must not add new empty versions. Pre-existing 50 empty versions represent public interfaces that cannot be 51 changed, but new ones should be removed before the product 52 ships. 53 54 55 -e exfile 56 An exception file is used to exclude objects from the usual rules. 57 See EXCEPTION FILE FORMAT. 58 59 -o Produce one-liner output, with each line of diagnostic output 60 prefixed with the object pathname. 61 62 -t If the -t option is present, only one argument is allowed. The 63 interface description file is parsed, and then regenerated on 64 stdout in the same format used by the interface_check -I option. 65 The -I output from interface_check and the output from 66 interface_cmp -t should be identical, excluding header comments. 67 This is a debugging feature, and not intended for general use. 68 69 EXCEPTION FILE FORMAT 70 Exceptions to the rules enforced by interface_cmp are specified using 71 an exception file. The -e option is used to specify an explicit 72 exception file. Otherwise, if used in an activated workspace, the 73 default exception file is $CODEMGR_WS/exception_list/interface_cmp if 74 that file exists. If not used in an activated workspace, or if 75 $CODEMGR_WS/exception_list/interface_cmp does not exist, interface_cmp 76 will use /opt/onbld/etc/exception_list/interface_cmp as a fallback 77 default exception file. 78 79 To run interface_cmp without applying exceptions, specify -e with a 80 value of /dev/null. 81 82 A '#' character at the beginning of a line, or at any point in a line 83 when preceded by whitespace, introduces a comment. Empty lines, and 84 lines containing only comments, are ignored by interface_cmp. 85 Exceptions are specified as space separated keyword, and perl(1) 86 regular expressions. The number of regular expressions depends on the 87 particular exception in questions: 88 89 keyword perl-regex... 90 91 Since whitespace is used as a separator, the regular expression cannot 92 itself contain whitespace. Use of the \s character class to represent 93 whitespace within the regular expression is recommended. Before the 94 perl regular expression is used, constructs of the form MACH(dir) are 95 expanded into a regular expression that matches the directory given, as 96 well as any 64-bit architecture subdirectory that might be present 97 (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the 98 following: 99 100 lib 101 lib/amd64 102 lib/sparcv9 103 104 The exceptions understood by interface_cmp are: 105 106 ADDSYM sym_re version_re object_re 107 108 The interfaces in a given version are not supposed to 109 change. interface_cmp will normally issue an error if 110 a new interface is added to a previously released 111 version. ADDSYM is used to override this requirement. 112 If the added symbol, version, and object match the 113 regular expressions specified by ADDSYM, the added 114 symbol is ignored. 115 116 117 DELDYM sym_re version_re object_re 118 119 Once released to the public, interfaces are required 120 to remain available in subsequent releases. DELSYM is 121 used to override this requirement, as can occur when 122 interfaces are EOL'd. Such an action generally 123 requires a PSARC case. If the deleted symbol, version, 124 and object match the regular expressions specified by 125 DELSYM, the deleted symbol is ignored. 126 127 128 EMPTY_TOPVERSION version_re object_re 129 130 interface_cmp normally issues an error if the old 131 object has an empty top version that is non-empty in 132 the new object. Such a situation is normally an error, 133 but may legitimately occur as part of a fix to another 134 versioning error. If the version, and object match 135 the regular expressions specified by EMPTY_TOPVERSION, 136 the error is suppressed. 137 138 139 EXAMPLES 140 The following example uses interface_cmp to compare this releases 141 interface definition with a previous builds results: 142 143 % interface_cmp -d -o $SRC/ELF-data.$MACH.ref/interfaces \ 144 $SRC/ELF-data.$MACH/interfaces 145 lib/libadm.so.1: SUNW_1.1: added interface: circf(4) 146 lib/libaio.so.1: SUNW_1.1: deleted interface: _aiocancel 147 148 149 Note: the above comparison files were doctored in order to provide the 150 example, they do not indicate any real changes that have occurred in 151 the associated system libraries. 152 153 SEE ALSO 154 find_elf(1ONBLD), interface_check(1ONBLD), ld(1), ldd(1), elfdump(1), 155 pvs(1). 156 157 158 159 March 25, 2010 INTERFACE_CMP(1ONBLD)