2 .\" "
3 .\" " The contents of this file are subject to the terms of the
4 .\" " Common Development and Distribution License (the "License").
5 .\" " You may not use this file except in compliance with the License.
6 .\" "
7 .\" " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 .\" " or http://www.opensolaris.org/os/licensing.
9 .\" " See the License for the specific language governing permissions
10 .\" " and limitations under the License.
11 .\" "
12 .\" " When distributing Covered Code, include this CDDL HEADER in each
13 .\" " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 .\" " If applicable, add the following below this CDDL HEADER, with the
15 .\" " fields enclosed by brackets "[]" replaced with your own identifying
16 .\" " information: Portions Copyright [yyyy] [name of copyright owner]
17 .\" "
18 .\" " CDDL HEADER END
19 .\" "
20 .\" " Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
21 .\" "
22 .TH wsdiff 1ONBLD "15 Jul 2010"
23 .I wsdiff
24 \- report differences between proto area objects
25 .SH SYNOPSIS
26 \fBwsdiff [-dvVst] [-r \fIresults\fP] [-i \fIfilelist\fP] \fIold\fP \fInew\fP
27 .LP
28 .SH DESCRIPTION
29 .IX "OS-Net build tools" "wsdiff" "" "\fBwsdiff\fP"
30 .LP
31 The wsdiff utility detects and reports on object differences found between
32 two proto areas constructed from the same workspace. This can be useful
33 when trying to understand which objects have changed as a result of a particular
34 source change.
35 .LP
36 \fIold\fP specifies the baseline proto area constructed without the source
37 change. \fInew\fP specifies the proto area constructed with the source
38 change. Both \fIold\fP and \fInew\fP should be constructed from the same
39 workspace, otherwise wsdiff will find object differences not associated
40 with the source change.
41 .SH OPTIONS
42 .TP 10
43 .B -d
44 Print debug information. The debug lines are prefixed with ##.
45 .TP 10
46 .B -v
47 Do not truncate the diffs logged to the results file. By default wsdiff
48 will truncate the length of a sufficiently long set of object diffs to preserve
49 the readability of the results file. -v can be used to override this behaviour.
54 it will log the difference associated with that section only, and move on. -V forces
55 wsdiff to log all ELF section differences found between two objects, rather than
56 just the first. Because of the extra work involved, this may slow wsdiff down
57 considerably.
58 .TP 10
59 .B -s
60 Produce sorted lists. This is handy when comparing multiple wsdiff outputs
61 because wsdiff runs in multithreaded mode so the list of differences is not
62 sorted and can differ between multiple runs.
63 .TP 10
64 .B -t
65 Look for the onbld tools in $SRC/tools rather than /opt/onbld/bin
66 .TP 10
67 .B -r
68 Log results to the specified log file. The log file contains a list of new, deleted,
69 and changed objects, as well as diffs signifying what wsdiff found to be different.
70 .TP 10
71 .B -i
72 Specify which objects should be compared by wsdiff via an input file list (See
73 EXAMPLES).
74 .LP
75 .SH OUTPUT
76 .LP
77 The list of objects appearing to differ between \fIold\fP and \fInew\fP is
78 printed to stdout. If -r was specified, the list of differing objects and
79 their differrences are logged to \fIresults\fP.
80 .LP
81 .SH EXAMPLES
82 .PP
83 \fBExample 1: Using wsdiff to determine patch deliverables\fR
84 .PP
85 The following example shows how to use wsdiff to determine the set of objects
86 requiring (re)delivery via patch as a result of a given source change:
87 .LP
88 Starting with a built workspace, move the existing proto area aside:
89 .LP
90 .nf
91 user@example$ ls
92 Codemgr_wsdata/ proto/ usr/
93
94 user@example$ mv proto proto.old
95 .fi
96 .LP
97 Next, integrate the source changes, rebuild, and invoke wsdiff specifying the
98 old and new proto areas:
99 .LP
100 .nf
132 Results file: results
133
134 platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
135 NOTE: ELF .text difference detected.
136
137 89562,89567c89562,89567
138 < lgrp_cpu_init+0x158: 9e 10 20 01 mov 0x1, %o7
139 < lgrp_cpu_init+0x15c: b3 2b d0 1c sllx %o7, %i4, %i1
140 < lgrp_cpu_init+0x160: 9a 12 40 19 or %o1, %i1, %o5
141 < lgrp_cpu_init+0x164: da 76 a0 30 stx %o5, [%i2 + 0x30]
142 < lgrp_cpu_init+0x168: d8 04 e0 00 ld [%l3], %o4
143 < lgrp_cpu_init+0x16c: 80 a3 20 00 cmp %o4, 0x0
144 ---
145 > lgrp_cpu_init+0x158: 9a 10 20 01 mov 0x1, %o5
146 > lgrp_cpu_init+0x15c: b3 2b 50 1c sllx %o5, %i4, %i1
147 > lgrp_cpu_init+0x160: 98 12 00 19 or %o0, %i1, %o4
148 > lgrp_cpu_init+0x164: d8 76 a0 30 stx %o4, [%i2 + 0x30]
149 > lgrp_cpu_init+0x168: d6 04 e0 00 ld [%l3], %o3
150 > lgrp_cpu_init+0x16c: 80 a2 e0 00 cmp %o3, 0x0
151
152 ...
153
154 .fi
155 .PP
156 \fBExample 3: Using an input file list\fR
157 .PP
158 The -i option tells wsdiff to compare a specific list of objects. This can be useful
159 in conjunction with other options that direct wsdiff to log more verbosely, allowing
160 one to "drill down" into a particular object's differences:
161 .LP
162 .nf
163 user@example$ echo "usr/lib/mdb/kvm/sparcv9/genunix.so" > flist
164 user@example$ wsdiff -vV -r results -i flist proto.old proto
165 usr/lib/mdb/kvm/sparcv9/genunix.so
166
167 user@example$ cat results
168 <... verbose differences only for genunix.so ...>
169 .fi
170 .PP
171 \fBExample 4: Invoking wsdiff through nightly(1ONBLD)\fR
172 .PP
174 which objects look different, compared to the previous build. A pre-existing proto area
175 must exist for wsdiff(1ONBLD) to compare against. nightly(1ONBLD) will move aside the
176 pre-existing proto area (renaming it to $ROOT.prev under proto), and will
177 invoke wsdiff at the end of the build. The list of changed objects will be reported
178 in the nightly mail message, and a results file "wsdiff_results" will appear in the
179 nightly log area.
180 .PP
181 \fBExample 5: Influencing the level of paralelism\fR
182 .PP
183 wsdiff spawns a number of threads by default after it determines the list
184 of files for comparison. Default number of threads is based on the number of
185 on-line CPUs present in the system. To set the number of threads for processing
186 to some other value the DMAKE_MAX_JOBS environment variable can be used:
187 .LP
188 .nf
189 $ DMAKE_MAX_JOBS=24 wsdiff proto_base proto_patch
190 .fi
191 .PP
192 Note that this variable is also used for nightly(1ONBLD) so when run from
193 nightly(1ONBLD), wsdiff will honor the setting.
194 .LP
195 .SH SEE ALSO
196 .LP
197 .IR nightly(1ONBLD),
198 .IR elfdump(1),
|
2 .\" "
3 .\" " The contents of this file are subject to the terms of the
4 .\" " Common Development and Distribution License (the "License").
5 .\" " You may not use this file except in compliance with the License.
6 .\" "
7 .\" " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 .\" " or http://www.opensolaris.org/os/licensing.
9 .\" " See the License for the specific language governing permissions
10 .\" " and limitations under the License.
11 .\" "
12 .\" " When distributing Covered Code, include this CDDL HEADER in each
13 .\" " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 .\" " If applicable, add the following below this CDDL HEADER, with the
15 .\" " fields enclosed by brackets "[]" replaced with your own identifying
16 .\" " information: Portions Copyright [yyyy] [name of copyright owner]
17 .\" "
18 .\" " CDDL HEADER END
19 .\" "
20 .\" " Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
21 .\" "
22 .TH WSDIFF 1ONBLD "Jul 15, 2010"
23 .I wsdiff
24 \- report differences between proto area objects
25 .SH SYNOPSIS
26 \fBwsdiff [-dvVst] [-r \fIresults\fP] [-i \fIfilelist\fP] \fIold\fP \fInew\fP
27 .SH DESCRIPTION
28 .LP
29 The wsdiff utility detects and reports on object differences found between
30 two proto areas constructed from the same workspace. This can be useful
31 when trying to understand which objects have changed as a result of a particular
32 source change.
33 .LP
34 \fIold\fP specifies the baseline proto area constructed without the source
35 change. \fInew\fP specifies the proto area constructed with the source
36 change. Both \fIold\fP and \fInew\fP should be constructed from the same
37 workspace, otherwise wsdiff will find object differences not associated
38 with the source change.
39 .SH OPTIONS
40 .TP 10
41 .B -d
42 Print debug information. The debug lines are prefixed with ##.
43 .TP 10
44 .B -v
45 Do not truncate the diffs logged to the results file. By default wsdiff
46 will truncate the length of a sufficiently long set of object diffs to preserve
47 the readability of the results file. -v can be used to override this behaviour.
52 it will log the difference associated with that section only, and move on. -V forces
53 wsdiff to log all ELF section differences found between two objects, rather than
54 just the first. Because of the extra work involved, this may slow wsdiff down
55 considerably.
56 .TP 10
57 .B -s
58 Produce sorted lists. This is handy when comparing multiple wsdiff outputs
59 because wsdiff runs in multithreaded mode so the list of differences is not
60 sorted and can differ between multiple runs.
61 .TP 10
62 .B -t
63 Look for the onbld tools in $SRC/tools rather than /opt/onbld/bin
64 .TP 10
65 .B -r
66 Log results to the specified log file. The log file contains a list of new, deleted,
67 and changed objects, as well as diffs signifying what wsdiff found to be different.
68 .TP 10
69 .B -i
70 Specify which objects should be compared by wsdiff via an input file list (See
71 EXAMPLES).
72 .SH OUTPUT
73 .LP
74 The list of objects appearing to differ between \fIold\fP and \fInew\fP is
75 printed to stdout. If -r was specified, the list of differing objects and
76 their differrences are logged to \fIresults\fP.
77 .SH EXAMPLES
78 .PP
79 \fBExample 1: Using wsdiff to determine patch deliverables\fR
80 .PP
81 The following example shows how to use wsdiff to determine the set of objects
82 requiring (re)delivery via patch as a result of a given source change:
83 .LP
84 Starting with a built workspace, move the existing proto area aside:
85 .LP
86 .nf
87 user@example$ ls
88 Codemgr_wsdata/ proto/ usr/
89
90 user@example$ mv proto proto.old
91 .fi
92 .LP
93 Next, integrate the source changes, rebuild, and invoke wsdiff specifying the
94 old and new proto areas:
95 .LP
96 .nf
128 Results file: results
129
130 platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
131 NOTE: ELF .text difference detected.
132
133 89562,89567c89562,89567
134 < lgrp_cpu_init+0x158: 9e 10 20 01 mov 0x1, %o7
135 < lgrp_cpu_init+0x15c: b3 2b d0 1c sllx %o7, %i4, %i1
136 < lgrp_cpu_init+0x160: 9a 12 40 19 or %o1, %i1, %o5
137 < lgrp_cpu_init+0x164: da 76 a0 30 stx %o5, [%i2 + 0x30]
138 < lgrp_cpu_init+0x168: d8 04 e0 00 ld [%l3], %o4
139 < lgrp_cpu_init+0x16c: 80 a3 20 00 cmp %o4, 0x0
140 ---
141 > lgrp_cpu_init+0x158: 9a 10 20 01 mov 0x1, %o5
142 > lgrp_cpu_init+0x15c: b3 2b 50 1c sllx %o5, %i4, %i1
143 > lgrp_cpu_init+0x160: 98 12 00 19 or %o0, %i1, %o4
144 > lgrp_cpu_init+0x164: d8 76 a0 30 stx %o4, [%i2 + 0x30]
145 > lgrp_cpu_init+0x168: d6 04 e0 00 ld [%l3], %o3
146 > lgrp_cpu_init+0x16c: 80 a2 e0 00 cmp %o3, 0x0
147
148
149 .fi
150 .PP
151 \fBExample 3: Using an input file list\fR
152 .PP
153 The -i option tells wsdiff to compare a specific list of objects. This can be useful
154 in conjunction with other options that direct wsdiff to log more verbosely, allowing
155 one to "drill down" into a particular object's differences:
156 .LP
157 .nf
158 user@example$ echo "usr/lib/mdb/kvm/sparcv9/genunix.so" > flist
159 user@example$ wsdiff -vV -r results -i flist proto.old proto
160 usr/lib/mdb/kvm/sparcv9/genunix.so
161
162 user@example$ cat results
163 <... verbose differences only for genunix.so ...>
164 .fi
165 .PP
166 \fBExample 4: Invoking wsdiff through nightly(1ONBLD)\fR
167 .PP
169 which objects look different, compared to the previous build. A pre-existing proto area
170 must exist for wsdiff(1ONBLD) to compare against. nightly(1ONBLD) will move aside the
171 pre-existing proto area (renaming it to $ROOT.prev under proto), and will
172 invoke wsdiff at the end of the build. The list of changed objects will be reported
173 in the nightly mail message, and a results file "wsdiff_results" will appear in the
174 nightly log area.
175 .PP
176 \fBExample 5: Influencing the level of paralelism\fR
177 .PP
178 wsdiff spawns a number of threads by default after it determines the list
179 of files for comparison. Default number of threads is based on the number of
180 on-line CPUs present in the system. To set the number of threads for processing
181 to some other value the DMAKE_MAX_JOBS environment variable can be used:
182 .LP
183 .nf
184 $ DMAKE_MAX_JOBS=24 wsdiff proto_base proto_patch
185 .fi
186 .PP
187 Note that this variable is also used for nightly(1ONBLD) so when run from
188 nightly(1ONBLD), wsdiff will honor the setting.
189 .SH SEE ALSO
190 .LP
191 .IR nightly(1ONBLD),
192 .IR elfdump(1),
|