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