"
" 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 (c) 2010, Oracle and/or its affiliates. All rights reserved.
" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
"
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.
10 -d Print debug information. The debug lines are prefixed with ##.
10 "-i " filelist Specify which objects should be compared by wsdiff via an input file list (See EXAMPLES). "-r " results 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.
10 -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.
10 -t Look for the onbld tools in $SRC/tools rather than /opt/onbld/bin
10 -u Use unified diff output for diffs logged to the results file.
10 "-U " lines Use unified diff output with lines context lines for diffs logged to the results file.
10 -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.
10 -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.
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 parallelism
wsdiff spawns a number of threads by default after it determines the list of files for comparison. The 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.