OpenSolaris_b135/tools/scripts/wsdiff.1
.\" ident "%Z%%M% %I% %E% SMI"
.\" " CDDL HEADER START
.\" "
.\" " The contents of this file are subject to the terms of the
.\" " Common Development and Distribution License (the "License").
.\" " You may not use this file except in compliance with the License.
.\" "
.\" " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" " or http://www.opensolaris.org/os/licensing.
.\" " See the License for the specific language governing permissions
.\" " and limitations under the License.
.\" "
.\" " When distributing Covered Code, include this CDDL HEADER in each
.\" " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" " If applicable, add the following below this CDDL HEADER, with the
.\" " fields enclosed by brackets "[]" replaced with your own identifying
.\" " information: Portions Copyright [yyyy] [name of copyright owner]
.\" "
.\" " CDDL HEADER END
.\" "
.\" "Copyright 2006 Sun Microsystems, Inc. All rights reserved.
.\" "Use is subject to license terms."
.TH wsdiff 1 "07 Jul 2006"
.I wsdiff
\- report differences between proto area objects
.SH SYNOPSIS
\fBwsdiff [-vVt] [-r \fIresults\fP] [-i \fIfilelist\fP] \fIold\fP \fInew\fP
.LP
.SH DESCRIPTION
.IX "OS-Net build tools" "wsdiff" "" "\fBwsdiff\fP"
.LP
The wsdiff utility detects and reports on object differences found between
two proto areas constructed from the same workspace. This can be useful
when trying to understand which objects have changed as a result of a particular
source change.
.LP
\fIold\fP specifies the baseline proto area constructed without the source
change. \fInew\fP specifies the proto area constructed with the source
change. Both \fIold\fP and \fInew\fP should be constructed from the same
workspace, otherwise wsdiff will find object differences not associated
with the source change.
.SH OPTIONS
.TP 10
.B -v
Do not truncate the diffs logged to the results file. By default wsdiff
will truncate the length of a sufficiently long set of object diffs to preserve
the readability of the results file. -v can be used to override this behaviour.
.TP 10
.B -V
Log observed differences for all ELF sections, rather than logging only the first
difference found. When wsdiff encounters an ELF section difference, by default
it will log the difference associated with that section only, and move on. -V forces
wsdiff to log all ELF section differences found between two objects, rather than
just the first. Because of the extra work involved, this may slow wsdiff down
considerably.
.TP 10
.B -t
Look for the onbld tools in $SRC/tools rather than /opt/onbld/bin
.TP 10
.B -r
Log results to the specified log file. The log file contains a list of new, deleted,
and changed objects, as well as diffs signifying what wsdiff found to be different.
.TP 10
.B -i
Specify which objects should be compared by wsdiff via an input file list (See
EXAMPLES).
.LP
.SH OUTPUT
.LP
The list of objects appearing to differ between \fIold\fP and \fInew\fP is
printed to stdout. If -r was specified, the list of differing objects and
their differrences are logged to \fIresults\fP.
.LP
.SH EXAMPLES
.PP
\fBExample 1: Using wsdiff to determine patch deliverables\fR
.PP
The following example shows how to use wsdiff to determine the set of objects
requiring (re)delivery via patch as a result of a given source change:
.LP
Starting with a built workspace, move the existing proto area aside:
.LP
.nf
user@example$ ls
Codemgr_wsdata/ proto/ usr/
user@example$ mv proto proto.old
.fi
.LP
Next, integrate the source changes, rebuild, and invoke wsdiff specifying the
old and new proto areas:
.LP
.nf
user@example$ ls
Codemgr_wsdata/ proto/ proto.old/ usr/
user@example$ wsdiff proto.old proto
platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
platform/SUNW,Sun-Fire-15000/kernel/sparcv9/unix
platform/sun4v/kernel/sparcv9/unix
platform/sun4u/kernel/sparcv9/unix
platform/SUNW,Ultra-Enterprise-10000/kernel/sparcv9/unix
platform/SUNW,Sun-Fire/kernel/sparcv9/unix
.fi
.PP
\fBExample 2: The wsdiff results file\fR
.PP
With the -r option, wsdiff will log the list of objects that appear different, as well
as a set of diffs highlighting the observed difference:
.LP
.nf
user@example$ wsdiff -r results proto.old proto
platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
platform/SUNW,Sun-Fire-15000/kernel/sparcv9/unix
platform/sun4v/kernel/sparcv9/unix
platform/sun4u/kernel/sparcv9/unix
platform/SUNW,Ultra-Enterprise-10000/kernel/sparcv9/unix
platform/SUNW,Sun-Fire/kernel/sparcv9/unix
user@example$ cat results
# This file was produced by wsdiff
# 2006/7/10 at 18:28:56
Base proto area: proto.old/
Patch (new) proto area: proto/
Results file: results
platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
NOTE: ELF .text difference detected.
89562,89567c89562,89567
< lgrp_cpu_init+0x158: 9e 10 20 01 mov 0x1, %o7
< lgrp_cpu_init+0x15c: b3 2b d0 1c sllx %o7, %i4, %i1
< lgrp_cpu_init+0x160: 9a 12 40 19 or %o1, %i1, %o5
< lgrp_cpu_init+0x164: da 76 a0 30 stx %o5, [%i2 + 0x30]
< lgrp_cpu_init+0x168: d8 04 e0 00 ld [%l3], %o4
< lgrp_cpu_init+0x16c: 80 a3 20 00 cmp %o4, 0x0
---
> lgrp_cpu_init+0x158: 9a 10 20 01 mov 0x1, %o5
> lgrp_cpu_init+0x15c: b3 2b 50 1c sllx %o5, %i4, %i1
> lgrp_cpu_init+0x160: 98 12 00 19 or %o0, %i1, %o4
> lgrp_cpu_init+0x164: d8 76 a0 30 stx %o4, [%i2 + 0x30]
> lgrp_cpu_init+0x168: d6 04 e0 00 ld [%l3], %o3
> lgrp_cpu_init+0x16c: 80 a2 e0 00 cmp %o3, 0x0
...
.fi
.PP
\fBExample 3: Using an input file list\fR
.PP
The -i option tells wsdiff to compare a specific list of objects. This can be useful
in conjunction with other options that direct wsdiff to log more verbosely, allowing
one to "drill down" into a particular object's differences:
.LP
.nf
user@example$ echo "usr/lib/mdb/kvm/sparcv9/genunix.so" > flist
user@example$ wsdiff -vV -r results -i flist proto.old proto
usr/lib/mdb/kvm/sparcv9/genunix.so
user@example$ cat results
<... verbose differences only for genunix.so ...>
.fi
.PP
\fBExample 4: Invoking wsdiff through nightly(1)\fR
.PP
By specifying -w in NIGHTLY_OPTIONS, nightly(1) will use wsdiff(1) to determine
which objects look different, compared to the previous build. A pre-existing proto area
must exist for wsdiff(1) to compare against. nightly(1) will move aside the
pre-existing proto area (renaming it to $ROOT.prev under proto), and will
invoke wsdiff at the end of the build. The list of changed objects will be reported
in the nightly mail message, and a results file "wsdiff_results" will appear in the
nightly log area.
.LP
.SH SEE ALSO
.LP
.IR lintdump(1),
.IR nightly(1),
.IR elfdump(1),