2 .\"
3 .\" CDDL HEADER START
4 .\"
5 .\" The contents of this file are subject to the terms of the
6 .\" Common Development and Distribution License (the "License").
7 .\" You may not use this file except in compliance with the License.
8 .\"
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 .\" or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions
12 .\" and limitations under the License.
13 .\"
14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 .\" If applicable, add the following below this CDDL HEADER, with the
17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 .\"
20 .\" CDDL HEADER END
21 .\"
22 .TH interface_cmp 1ONBLD "25 March 2010"
23 .SH NAME
24 interface_cmp \- compare shared object interface descriptions
25 .SH SYNOPSIS
26 \fBinterface_cmp [-dot] [-e exfile] old new\fP
27 .LP
28 .SH DESCRIPTION
29 .IX "OS-Net build tools" "interface_cmp" "" "\fBinterface_cmp\fP"
30 The
31 .I interface_cmp
32 command compares the interface definition files for two workspaces
33 and reports versioning inconsistencies. Interface definition
34 files are created by
35 .IR interface_check.
36 .PP
37 .I interface_cmp
38 is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
39 option is in effect following the creation of a new database by
40 .IR interface_check .
41 To insure symbolic
42 interface consistency between successive software releases, existing
43 version definitions and their symbol association should remain intact.
44 Any discrepancies between the two interface definitions are flagged as
45 errors.
46 .PP
47 Note that version definition inheritance has the effect of causing a
48 symbol to be viewed as existing in multiple definitions. This insures
49 that both version definitions and their inheritance relationship are
50 processed as part of the comparison.
51 .LP
52 .SH OPTIONS
53 .LP
54 The following options are supported:
55 .TP 4
56 .B \-c vertype_module
57 By default,
58 .I interface_cmp
59 is customized for the versioning conventions used by the Solaris
60 OSnet code base. This specialized information, which includes
61 the recognition of the SUNW_ prefix and other special names, is
62 contained in a perl module named onbld_elfmod_vertype.pm, which
63 is delivered with the SUNWonbld tools. This module is loaded by
64 .I interface_cmp
65 at runtime. The \fB-c\fP option can be used to supply
66 an alternative module, customized for a different code base, allowing
67 .I interface_cmp
68 to operate on code from other projects. The alternative module must
69 supply the same module and calling interfaces as the standard module.
70 .TP 4
71 .B \-d
72 Asserts that the \fBnew\fP interface is a direct descendant of
73 \fBold\fP. If so, the following additional checks are enabled:
74 .RS +4
75 .TP
76 .ie t \(bu
77 .el o
78 The top version of an inheritance chain must not increase
79 by more than one.
80 .RE
81 .RS +4
82 .TP
83 .ie t \(bu
84 .el o
85 The new interface must not add new empty versions. Pre-existing empty
86 versions represent public interfaces that cannot be changed, but new
87 ones should be removed before the product ships.
88 .RE
89 .sp
90 .LP
91 .TP 4
92 .B \-e exfile
93 An exception file is used to exclude objects from
94 the usual rules. See EXCEPTION FILE FORMAT.
95 .TP 4
96 .B \-o
97 Produce one-liner output, with each line of diagnostic output
98 prefixed with the object pathname.
99 .TP 4
100 .B \-t
101 If the \fB-t\fP option is present, only one argument is allowed.
102 The interface description file is parsed, and then regenerated on
103 stdout in the same format used by the
104 .I interface_check
105 \fB-I\fP option. The \fB-I\fP output from
106 .I interface_check
107 and the output from
108 .I interface_cmp
109 \fB-t\fP
110 should be identical, excluding header comments.
111 This is a debugging feature, and not intended for general use.
112 .LP
113 .SH EXCEPTION FILE FORMAT
114 Exceptions to the rules enforced by
115 .I interface_cmp
116 are specified using an exception file. The \fB-e\fP option is used to
117 specify an explicit exception file. Otherwise, if used in an activated
118 workspace, the default exception file is
119 $CODEMGR_WS/exception_list/interface_cmp
120 if that file exists. If not used in an activated workspace, or if
121 $CODEMGR_WS/exception_list/interface_cmp does not exist,
122 .I interface_cmp
123 will use
124 .I /opt/onbld/etc/exception_list/interface_cmp
125 as a fallback default exception file.
126 .p
127 To run
128 .I interface_cmp
129 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
130 .P
131 A '#' character at the beginning of a line, or at any point in
132 a line when preceded by whitespace, introduces a comment. Empty lines,
133 and lines containing only comments, are ignored by
134 .I interface_cmp.
135 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
136 regular expressions. The number of regular expressions depends on the
137 particular exception in questions:
138 .sp
139 .in +4
140 .nf
141 keyword perl-regex...
142 .fi
143 .in -4
144 .sp
145 Since whitespace is used as a separator, the regular
146 expression cannot itself contain whitespace. Use of the \\s character
147 class to represent whitespace within the regular expression is recommended.
148 Before the perl regular expression is used, constructs of the form
149 MACH(dir) are expanded into a regular expression that matches the directory
150 given, as well as any 64-bit architecture subdirectory that
151 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
152 match any of the following:
153 .sp
154 .in +4
155 .nf
156 lib
157 lib/amd64
158 lib/sparcv9
159 .fi
160 .in -4
161 .sp
162 The exceptions understood by
163 .I interface_cmp
164 are:
165 .sp
166 .ne 2
167 .mk
168 .na
169 \fBADDSYM\fR sym_re version_re object_re
170 .ad
171 .RS 17n
172 .rt
173 .sp
174 The interfaces in a given version are not supposed to change.
175 .I interface_cmp
176 will normally issue an error if a new interface is added to a previously
177 released version. ADDSYM is used to override this
178 requirement. If the added symbol, version, and object match
179 the regular expressions specified by ADDSYM, the added symbol is ignored.
180 .RE
181
182 .sp
183 .ne 2
184 .mk
185 .na
186 \fBDELDYM\fR sym_re version_re object_re
187 .ad
188 .RS 17n
189 .rt
190 .sp
191 Once released to the public, interfaces are required to remain available
192 in subsequent releases. DELSYM is used to override this
193 requirement, as can occur when interfaces are EOL'd. Such an action generally
194 requires a PSARC case. If the deleted symbol, version, and object match
195 the regular expressions specified by DELSYM, the deleted symbol is ignored.
196 .RE
197
198 .sp
199 .ne 2
200 .mk
201 .na
202 \fBEMPTY_TOPVERSION\fR version_re object_re
203 .ad
204 .RS 17n
205 .rt
206 .sp
207 .I
208 interface_cmp
209 normally issues an error if the old object has an empty top version
210 that is non-empty in the new object. Such a situation is normally
211 an error, but may legitimately occur as part of a fix to another versioning
212 error. If the version, and object match
213 the regular expressions specified by EMPTY_TOPVERSION, the error is suppressed.
214 .RE
215
216 .PP
217 .SH EXAMPLES
218 The following example uses
219 .I interface_cmp
220 to compare this releases interface definition with a previous
221 builds results:
222 .PP
223 .RS
224 .nf
225 .B % interface_cmp -d -o $SRC/ELF-data.$MACH.ref/interfaces\ \\\\
226 .B \ \ \ \ \ \ \ $SRC/ELF-data.$MACH/interfaces
227 lib/libadm.so.1: SUNW_1.1: added interface: circf(4)
228 lib/libaio.so.1: SUNW_1.1: deleted interface: _aiocancel
229 .fi
230 .RE
231 .sp
232 .PP
233 Note: the above comparison files were doctored in order to provide
234 the example, they do not indicate any real changes that have
235 occurred in the associated system libraries.
236 .br
237 .SH SEE ALSO
238 .BR find_elf(1ONBLD),
239 .BR interface_check(1ONBLD),
240 .BR ld(1),
241 .BR ldd(1),
242 .BR elfdump(1),
243 .BR pvs(1).
244 .LP
245 .TZ LLM
|
2 .\"
3 .\" CDDL HEADER START
4 .\"
5 .\" The contents of this file are subject to the terms of the
6 .\" Common Development and Distribution License (the "License").
7 .\" You may not use this file except in compliance with the License.
8 .\"
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 .\" or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions
12 .\" and limitations under the License.
13 .\"
14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 .\" If applicable, add the following below this CDDL HEADER, with the
17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 .\"
20 .\" CDDL HEADER END
21 .\"
22 .TH INTERFACE_CMP 1ONBLD "Mar 25, 2010"
23 .SH NAME
24 interface_cmp \- compare shared object interface descriptions
25 .SH SYNOPSIS
26 \fBinterface_cmp [-dot] [-e exfile] old new\fP
27 .SH DESCRIPTION
28 The
29 .I interface_cmp
30 command compares the interface definition files for two workspaces
31 and reports versioning inconsistencies. Interface definition
32 files are created by
33 .IR interface_check.
34 .PP
35 .I interface_cmp
36 is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
37 option is in effect following the creation of a new database by
38 .IR interface_check .
39 To insure symbolic
40 interface consistency between successive software releases, existing
41 version definitions and their symbol association should remain intact.
42 Any discrepancies between the two interface definitions are flagged as
43 errors.
44 .PP
45 Note that version definition inheritance has the effect of causing a
46 symbol to be viewed as existing in multiple definitions. This insures
47 that both version definitions and their inheritance relationship are
48 processed as part of the comparison.
49 .SH OPTIONS
50 The following options are supported:
51 .TP 4
52 .B \-c vertype_module
53 By default,
54 .I interface_cmp
55 is customized for the versioning conventions used by the Solaris
56 OSnet code base. This specialized information, which includes
57 the recognition of the SUNW_ prefix and other special names, is
58 contained in a perl module named onbld_elfmod_vertype.pm, which
59 is delivered with the SUNWonbld tools. This module is loaded by
60 .I interface_cmp
61 at runtime. The \fB-c\fP option can be used to supply
62 an alternative module, customized for a different code base, allowing
63 .I interface_cmp
64 to operate on code from other projects. The alternative module must
65 supply the same module and calling interfaces as the standard module.
66 .TP 4
67 .B \-d
68 Asserts that the \fBnew\fP interface is a direct descendant of
69 \fBold\fP. If so, the following additional checks are enabled:
70 .RS +4
71 .TP
72 .ie t \(bu
73 .el o
74 The top version of an inheritance chain must not increase
75 by more than one.
76 .RE
77 .RS +4
78 .TP
79 .ie t \(bu
80 .el o
81 The new interface must not add new empty versions. Pre-existing empty
82 versions represent public interfaces that cannot be changed, but new
83 ones should be removed before the product ships.
84 .RE
85 .sp
86 .TP 4
87 .B \-e exfile
88 An exception file is used to exclude objects from
89 the usual rules. See EXCEPTION FILE FORMAT.
90 .TP 4
91 .B \-o
92 Produce one-liner output, with each line of diagnostic output
93 prefixed with the object pathname.
94 .TP 4
95 .B \-t
96 If the \fB-t\fP option is present, only one argument is allowed.
97 The interface description file is parsed, and then regenerated on
98 stdout in the same format used by the
99 .I interface_check
100 \fB-I\fP option. The \fB-I\fP output from
101 .I interface_check
102 and the output from
103 .I interface_cmp
104 \fB-t\fP
105 should be identical, excluding header comments.
106 This is a debugging feature, and not intended for general use.
107 .SH EXCEPTION FILE FORMAT
108 Exceptions to the rules enforced by
109 .I interface_cmp
110 are specified using an exception file. The \fB-e\fP option is used to
111 specify an explicit exception file. Otherwise, if used in an activated
112 workspace, the default exception file is
113 $CODEMGR_WS/exception_list/interface_cmp
114 if that file exists. If not used in an activated workspace, or if
115 $CODEMGR_WS/exception_list/interface_cmp does not exist,
116 .I interface_cmp
117 will use
118 .I /opt/onbld/etc/exception_list/interface_cmp
119 as a fallback default exception file.
120 .P
121 To run
122 .I interface_cmp
123 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
124 .P
125 A '#' character at the beginning of a line, or at any point in
126 a line when preceded by whitespace, introduces a comment. Empty lines,
127 and lines containing only comments, are ignored by
128 .I interface_cmp.
129 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
130 regular expressions. The number of regular expressions depends on the
131 particular exception in questions:
132 .sp
133 .in +4
134 .nf
135 keyword perl-regex...
136 .fi
137 .in -4
138 .sp
139 Since whitespace is used as a separator, the regular
140 expression cannot itself contain whitespace. Use of the \\s character
141 class to represent whitespace within the regular expression is recommended.
142 Before the perl regular expression is used, constructs of the form
143 MACH(dir) are expanded into a regular expression that matches the directory
144 given, as well as any 64-bit architecture subdirectory that
145 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
146 match any of the following:
147 .sp
148 .in +4
149 .nf
150 lib
151 lib/amd64
152 lib/sparcv9
153 .fi
154 .in -4
155 .sp
156 The exceptions understood by
157 .I interface_cmp
158 are:
159 .sp
160 .ne 2
161 .na
162 \fBADDSYM\fR sym_re version_re object_re
163 .ad
164 .RS 17n
165 .sp
166 The interfaces in a given version are not supposed to change.
167 .I interface_cmp
168 will normally issue an error if a new interface is added to a previously
169 released version. ADDSYM is used to override this
170 requirement. If the added symbol, version, and object match
171 the regular expressions specified by ADDSYM, the added symbol is ignored.
172 .RE
173
174 .sp
175 .ne 2
176 .na
177 \fBDELDYM\fR sym_re version_re object_re
178 .ad
179 .RS 17n
180 .sp
181 Once released to the public, interfaces are required to remain available
182 in subsequent releases. DELSYM is used to override this
183 requirement, as can occur when interfaces are EOL'd. Such an action generally
184 requires a PSARC case. If the deleted symbol, version, and object match
185 the regular expressions specified by DELSYM, the deleted symbol is ignored.
186 .RE
187
188 .sp
189 .ne 2
190 .na
191 \fBEMPTY_TOPVERSION\fR version_re object_re
192 .ad
193 .RS 17n
194 .sp
195 .I
196 interface_cmp
197 normally issues an error if the old object has an empty top version
198 that is non-empty in the new object. Such a situation is normally
199 an error, but may legitimately occur as part of a fix to another versioning
200 error. If the version, and object match
201 the regular expressions specified by EMPTY_TOPVERSION, the error is suppressed.
202 .RE
203
204 .SH EXAMPLES
205 The following example uses
206 .I interface_cmp
207 to compare this releases interface definition with a previous
208 builds results:
209 .PP
210 .RS
211 .nf
212 .B % interface_cmp -d -o $SRC/ELF-data.$MACH.ref/interfaces\ \\\\
213 .B \ \ \ \ \ \ \ $SRC/ELF-data.$MACH/interfaces
214 lib/libadm.so.1: SUNW_1.1: added interface: circf(4)
215 lib/libaio.so.1: SUNW_1.1: deleted interface: _aiocancel
216 .fi
217 .RE
218 .sp
219 .PP
220 Note: the above comparison files were doctored in order to provide
221 the example, they do not indicate any real changes that have
222 occurred in the associated system libraries.
223 .br
224 .SH SEE ALSO
225 .BR find_elf(1ONBLD),
226 .BR interface_check(1ONBLD),
227 .BR ld(1),
228 .BR ldd(1),
229 .BR elfdump(1),
230 .BR pvs(1).
|