WSDIFF(1ONBLD) illumos Build Tools WSDIFF(1ONBLD)


wsdiff - report differences between proto area objects

SYNOPSIS


wsdiff [-dvVst] [-r results] [-i filelist] old new

DESCRIPTION


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.

old specifies the baseline proto area constructed without the source
change. new specifies the proto area constructed with the source change.
Both old and new should be constructed from the same workspace, otherwise
wsdiff will find object differences not associated with the source
change.

OPTIONS


-d Print debug information. The debug lines are prefixed with ##.

-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.

-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.

-s Produce sorted lists. This is handy when comparing multiple
wsdiff outputs because wsdiff runs in multithreaded mode so the
list of differences is not sorted and can differ between
multiple runs.

-t Look for the onbld tools in $SRC/tools rather than
/opt/onbld/bin

-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.

-i Specify which objects should be compared by wsdiff via an input
file list (See EXAMPLES).

OUTPUT


The list of objects appearing to differ between old and new is printed to
stdout. If -r was specified, the list of differing objects and their
differrences are logged to results.

EXAMPLES


Example 1: Using wsdiff to determine patch deliverables

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:

Starting with a built workspace, move the existing proto area aside:

user@example$ ls
Codemgr_wsdata/ proto/ usr/

user@example$ mv proto proto.old

Next, integrate the source changes, rebuild, and invoke wsdiff specifying
the old and new proto areas:

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

Example 2: The wsdiff results file

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:

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


Example 3: Using an input file list

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:

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 ...>

Example 4: Invoking wsdiff through nightly(1ONBLD)

By specifying -w in NIGHTLY_OPTIONS, nightly(1ONBLD) will use
wsdiff(1ONBLD) to determine which objects look different, compared to the
previous build. A pre-existing proto area must exist for wsdiff(1ONBLD)
to compare against. nightly(1ONBLD) 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.

Example 5: Influencing the level of paralelism

wsdiff spawns a number of threads by default after it determines the list
of files for comparison. Default number of threads is based on the number
of on-line CPUs present in the system. To set the number of threads for
processing to some other value the DMAKE_MAX_JOBS environment variable
can be used:

$ DMAKE_MAX_JOBS=24 wsdiff proto_base proto_patch

Note that this variable is also used for nightly(1ONBLD) so when run from
nightly(1ONBLD), wsdiff will honor the setting.

SEE ALSO


nightly(1ONBLD), elfdump(1),


July 15, 2010 WSDIFF(1ONBLD)