usr/src/tools/scripts/wsdiff.1onbld

   1 .\" " CDDL HEADER START
   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.
  48 .TP 10
  49 .B -V
  50 Log observed differences for all ELF sections, rather than logging only the first
  51 difference found. When wsdiff encounters an ELF section difference, by default
  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
  97 user@example$ ls
  98 Codemgr_wsdata/  proto/           proto.old/      usr/
  99
 100 user@example$ wsdiff proto.old proto
 101 platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
 102 platform/SUNW,Sun-Fire-15000/kernel/sparcv9/unix
 103 platform/sun4v/kernel/sparcv9/unix
 104 platform/sun4u/kernel/sparcv9/unix
 105 platform/SUNW,Ultra-Enterprise-10000/kernel/sparcv9/unix
 106 platform/SUNW,Sun-Fire/kernel/sparcv9/unix
 107 .fi
 108 .PP
 109 \fBExample 2: The wsdiff results file\fR
 110 .PP
 111 With the -r option, wsdiff will log the list of objects that appear different, as well
 112 as a set of diffs highlighting the observed difference:
 113 .LP
 114 .nf
 115 user@example$ wsdiff -r results proto.old proto
 116 platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
 117 platform/SUNW,Sun-Fire-15000/kernel/sparcv9/unix
 118 platform/sun4v/kernel/sparcv9/unix
 119 platform/sun4u/kernel/sparcv9/unix
 120 platform/SUNW,Ultra-Enterprise-10000/kernel/sparcv9/unix
 121 platform/SUNW,Sun-Fire/kernel/sparcv9/unix
 122
 123 user@example$ cat results
 124 # This file was produced by wsdiff
 125 # 2006/7/10 at 18:28:56
 126 Base proto area: proto.old/
 127 Patch (new) proto area: proto/
 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
 168 By specifying -w in NIGHTLY_OPTIONS, nightly(1ONBLD) will use wsdiff(1ONBLD) to determine
 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),