1 WSDIFF(1ONBLD)                illumos Build Tools               WSDIFF(1ONBLD)
   2 
   3 
   4 
   5 wsdiff - report differences between proto area objects
   6 
   7 SYNOPSIS
   8        wsdiff [-dvVst] [-r results] [-i filelist] old new
   9 
  10 DESCRIPTION
  11        The wsdiff utility detects and reports on object differences found
  12        between two proto areas constructed from the same workspace. This can
  13        be useful when trying to understand which objects have changed as a
  14        result of a particular source change.
  15 
  16        old specifies the baseline proto area constructed without the source
  17        change. new specifies the proto area constructed with the source
  18        change. Both old and new should be constructed from the same workspace,
  19        otherwise wsdiff will find object differences not associated with the
  20        source change.
  21 
  22 OPTIONS
  23        -d        Print debug information. The debug lines are prefixed with
  24                  ##.
  25 
  26        -v        Do not truncate the diffs logged to the results file. By
  27                  default wsdiff will truncate the length of a sufficiently
  28                  long set of object diffs to preserve the readability of the
  29                  results file. -v can be used to override this behaviour.
  30 
  31        -V        Log observed differences for all ELF sections, rather than
  32                  logging only the first difference found. When wsdiff
  33                  encounters an ELF section difference, by default it will log
  34                  the difference associated with that section only, and move
  35                  on. -V forces wsdiff to log all ELF section differences found
  36                  between two objects, rather than just the first. Because of
  37                  the extra work involved, this may slow wsdiff down
  38                  considerably.
  39 
  40        -s        Produce sorted lists. This is handy when comparing multiple
  41                  wsdiff outputs because wsdiff runs in multithreaded mode so
  42                  the list of differences is not sorted and can differ between
  43                  multiple runs.
  44 
  45        -t        Look for the onbld tools in $SRC/tools rather than
  46                  /opt/onbld/bin
  47 
  48        -r        Log results to the specified log file. The log file contains
  49                  a list of new, deleted, and changed objects, as well as diffs
  50                  signifying what wsdiff found to be different.
  51 
  52        -i        Specify which objects should be compared by wsdiff via an
  53                  input file list (See EXAMPLES).
  54 
  55 OUTPUT
  56        The list of objects appearing to differ between old and new is printed
  57        to stdout. If -r was specified, the list of differing objects and their
  58        differrences are logged to results.
  59 
  60 EXAMPLES
  61        Example 1: Using wsdiff to determine patch deliverables
  62 
  63        The following example shows how to use wsdiff to determine the set of
  64        objects requiring (re)delivery via patch as a result of a given source
  65        change:
  66 
  67        Starting with a built workspace, move the existing proto area aside:
  68 
  69        user@example$ ls
  70        Codemgr_wsdata/  proto/           usr/
  71 
  72        user@example$ mv proto proto.old
  73 
  74        Next, integrate the source changes, rebuild, and invoke wsdiff
  75        specifying the old and new proto areas:
  76 
  77        user@example$ ls
  78        Codemgr_wsdata/  proto/           proto.old/      usr/
  79 
  80        user@example$ wsdiff proto.old proto
  81        platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
  82        platform/SUNW,Sun-Fire-15000/kernel/sparcv9/unix
  83        platform/sun4v/kernel/sparcv9/unix
  84        platform/sun4u/kernel/sparcv9/unix
  85        platform/SUNW,Ultra-Enterprise-10000/kernel/sparcv9/unix
  86        platform/SUNW,Sun-Fire/kernel/sparcv9/unix
  87 
  88        Example 2: The wsdiff results file
  89 
  90        With the -r option, wsdiff will log the list of objects that appear
  91        different, as well as a set of diffs highlighting the observed
  92        difference:
  93 
  94        user@example$ wsdiff -r results proto.old proto
  95        platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
  96        platform/SUNW,Sun-Fire-15000/kernel/sparcv9/unix
  97        platform/sun4v/kernel/sparcv9/unix
  98        platform/sun4u/kernel/sparcv9/unix
  99        platform/SUNW,Ultra-Enterprise-10000/kernel/sparcv9/unix
 100        platform/SUNW,Sun-Fire/kernel/sparcv9/unix
 101 
 102        user@example$ cat results
 103        # This file was produced by wsdiff
 104        # 2006/7/10 at 18:28:56
 105        Base proto area: proto.old/
 106        Patch (new) proto area: proto/
 107        Results file: results
 108 
 109        platform/SUNW,SPARC-Enterprise/kernel/sparcv9/unix
 110        NOTE: ELF .text difference detected.
 111 
 112        89562,89567c89562,89567
 113        <     lgrp_cpu_init+0x158:    9e      10 20 01  mov       0x1, %o7
 114        <     lgrp_cpu_init+0x15c:    b3      2b d0 1c  sllx      %o7, %i4, %i1
 115        <     lgrp_cpu_init+0x160:    9a      12 40 19  or        %o1, %i1, %o5
 116        <     lgrp_cpu_init+0x164:    da      76 a0 30  stx       %o5, [%i2 + 0x30]
 117        <     lgrp_cpu_init+0x168:    d8      04 e0 00  ld        [%l3], %o4
 118        <     lgrp_cpu_init+0x16c:    80      a3 20 00  cmp       %o4, 0x0
 119        ---
 120        >     lgrp_cpu_init+0x158:    9a      10 20 01  mov       0x1, %o5
 121        >     lgrp_cpu_init+0x15c:    b3      2b 50 1c  sllx      %o5, %i4, %i1
 122        >     lgrp_cpu_init+0x160:    98      12 00 19  or        %o0, %i1, %o4
 123        >     lgrp_cpu_init+0x164:    d8      76 a0 30  stx       %o4, [%i2 + 0x30]
 124        >     lgrp_cpu_init+0x168:    d6      04 e0 00  ld        [%l3], %o3
 125        >     lgrp_cpu_init+0x16c:    80      a2 e0 00  cmp       %o3, 0x0
 126 
 127 
 128 
 129        Example 3: Using an input file list
 130 
 131        The -i option tells wsdiff to compare a specific list of objects. This
 132        can be useful in conjunction with other options that direct wsdiff to
 133        log more verbosely, allowing one to "drill down" into a particular
 134        object's differences:
 135 
 136        user@example$ echo "usr/lib/mdb/kvm/sparcv9/genunix.so" > flist
 137        user@example$ wsdiff -vV -r results -i flist proto.old proto
 138        usr/lib/mdb/kvm/sparcv9/genunix.so
 139 
 140        user@example$ cat results
 141        <... verbose differences      only for genunix.so ...>
 142 
 143        Example 4: Invoking wsdiff through nightly(1ONBLD)
 144 
 145        By specifying -w in NIGHTLY_OPTIONS, nightly(1ONBLD) will use
 146        wsdiff(1ONBLD) to determine which objects look different, compared to
 147        the previous build. A pre-existing proto area must exist for
 148        wsdiff(1ONBLD) to compare against. nightly(1ONBLD) will move aside the
 149        pre-existing proto area (renaming it to $ROOT.prev under proto), and
 150        will invoke wsdiff at the end of the build. The list of changed objects
 151        will be reported in the nightly mail message, and a results file
 152        "wsdiff_results" will appear in the nightly log area.
 153 
 154        Example 5: Influencing the level of paralelism
 155 
 156        wsdiff spawns a number of threads by default after it determines the
 157        list of files for comparison. Default number of threads is based on the
 158        number of on-line CPUs present in the system. To set the number of
 159        threads for processing to some other value the DMAKE_MAX_JOBS
 160        environment variable can be used:
 161 
 162        $ DMAKE_MAX_JOBS=24 wsdiff proto_base proto_patch
 163 
 164        Note that this variable is also used for nightly(1ONBLD) so when run
 165        from nightly(1ONBLD), wsdiff will honor the setting.
 166 
 167 SEE ALSO
 168        nightly(1ONBLD), elfdump(1),
 169 
 170 
 171 
 172                                  July 15, 2010                  WSDIFF(1ONBLD)