diff command — Glaurung

use it for

The matcher uses names and content similarity to pair functions across builds. Review changed pairs before treating them as the same function.

Run glaurung diff --help on your installed version before putting the command in a script. Glaurung is still pre-1.0.

input: Two binaries that represent an earlier and later build, variant, or suspected match.
output: Paired functions classified as same, changed, added, or removed, with similarity and structural hashes.
mode: read only. The examples leave the input unchanged.

command shape

syntax

short form

$ glaurung diff BEFORE AFTER [--json]

The installed parser is authoritative: glaurung diff --help

run it

examples

Compare two fixture builds

The switchy fixture has one known changed function and eight unchanged functions.

run

from the engine checkout

$ glaurung diff samples/binaries/platforms/linux/amd64/synthetic/switchy-c-gcc-O2 samples/binaries/platforms/linux/amd64/synthetic/switchy-c-gcc-O2-v2

output

captured result captured tutorial fixture

# Binary diff — switchy-c-gcc-O2 ↔ switchy-c-gcc-O2-v2

8 same / 1 changed / 0 added / 0 removed (a=9 b=9)

## Changed functions

| similarity | function | a size | b size |
|---:|---|---:|---:|
| 0.600 | dispatch | 151 | 151 |

captured tutorial fixture.

Read the result: Equal size does not mean equal code. Inspect the paired dispatch functions before accepting the match or describing the change.

Keep a machine-readable report

JSON is useful when a CI job needs changed-function counts or names.

run

from the engine checkout

$ glaurung diff samples/binaries/platforms/linux/amd64/export/native/clang/debug/hello-c-clang-debug samples/binaries/platforms/linux/amd64/export/native/clang/O2/hello-c-clang-O2 --json > build-diff.json

output

captured result selected from the generated build-diff.json

{
  "summary": {
    "added": 0,
    "changed": 2,
    "removed": 1,
    "same": 7
  }
}

selected from the generated build-diff.json.

Read the result: Optimization changed the function inventory as well as instruction shapes. Use the function pairs in the full file before turning these counts into a regression rule.

used above

important options

--json: Return function pairs and summary counts as JSON.
--cross-name-threshold N: Set the minimum similarity used to pair unnamed functions.
--max-rows N: Limit the number of function rows printed.

These are the flags used by the examples. Run glaurung diff --help for the complete parser help.

keep working

related commands

← all 40 commands