LLVM-REMARK-SIZE-DIFF(1)

💅 LLVM-REMARK-SIZE-DIFF 💅

okay so bestie, welcome to the llvm-remark-size-diff page — it's part of the LLVM manual set (yes, that LLVM, the big one 👑), and it's genuinely one of the most underrated little tools in the whole box. let's get into it 🫶

---

✨ NAME ✨

llvm-remark-size-diff — diff size remarks, that's the whole vibe 💖

---

🌸 SYNOPSIS 🌸

llvm-remark-size-diff [options] file_a file_b --parser parser

---

🦋 DESCRIPTION 🦋

So like. llvm-remark-size-diff diffs size remarks in two remark files: file_a and file_b. that's it, that's the job, and it ate 💅

You use it to gain insight into which functions were impacted the most by code generation changes. literally a glow-up detector for your functions 🔥

In most common use-cases, file_a and file_b will be remarks output by compiling a fixed source with differing compilers or differing optimization settings. same source, different compiler, and this tool tells you who got bigger and who got smaller. main character energy fr fr ✨

llvm-remark-size-diff handles both YAML and bitstream remarks. both! versatile icon 💖

---

⭐ OPTIONS ⭐

• --parser=<yaml|bitstream> — Select the type of input remark parser. Required. ngl you literally cannot skip this one 🙈
  • yaml: The tool will parse YAML remarks.
  • bitstream: The tool will parse bitstream remarks.
• --report-style=<human|json> — Output style. pick your aesthetic 🎀
  • human: Human-readable textual report. Default option.
  • json: JSON report.
• --pretty — Pretty-print JSON output. Optional. 💅

If output is not set to JSON, this does nothing. like, it just sits there being cute and useless 🫠

• -o=<file> — Output file for the report. Outputs to stdout by default.

---

🌈 HUMAN-READABLE OUTPUT 🌈

The human-readable format for llvm-remark-size-diff is composed of two sections:

• Per-function changes.
• A high-level summary of all changes.

---

🧚 Changed Function Section 🧚

Suppose you are comparing two remark files OLD and NEW.

For each function with a changed instruction count in OLD and NEW, llvm-remark-size-diff will emit a line like below:

(++|--|==) (>|<) function_name, N instrs, M stack B

A breakdown of the format is below:

• (++|--|==) — Which of OLD and NEW the function_name is present in.
  • ++: Only in NEW. ("Added") 🎉
  • --: Only in OLD. ("Removed") 😭
  • ==: In both. 🫶
• (>|<) — Denotes if function_name has more instructions or fewer instructions in the second file.
  • >: More instructions in second file than first file.
  • <: Fewer instructions in second file than in first file.
• function_name — The name of the changed function.
• N instrs — Second file instruction count - first file instruction count.
• M stack B — Second file stack byte count - first file stack byte count.

---

💜 Summary Section 💜

llvm-remark-size-diff will output a high-level summary after printing all changed functions. the grand finale, the recap, the "so how did we do" moment 💅

instruction count: N (inst_pct_change%)
stack byte usage: M (sb_pct_change%)

• N — Sum of all instruction count changes between the second and first file.
• inst_pct_change% — Percent increase or decrease in instruction count between the second and first file.
• M — Sum of all stack byte count changes between the second and first file.
• sb_pct_change% — Percent increase or decrease in stack byte usage between the second and first file.

---

🎀 JSON OUTPUT 🎀

🍓 High-Level view 🍓

Suppose we are comparing two files, OLD and NEW.

llvm-remark-size-diff will output JSON as follows.

"Files": [
  "A": "path/to/OLD",
  "B": "path/to/NEW"
]

"InBoth": [
  ...
],

"OnlyInA": [
  ...
],

"OnlyInB": [
  ...
]

• Files — Original paths to remark files.
  • A: Path to the first file.
  • B: Path to the second file.
• InBoth — Functions present in both files.
• OnlyInA — Functions only present in the first file.
• OnlyInB — Functions only present in the second file.

---

🌸 Function JSON 🌸

The InBoth, OnlyInA, and OnlyInB sections contain size information for each function in the input remark files.

{
  "FunctionName" : "function_name"
  "InstCount": [
      INST_COUNT_A,
      INST_COUNT_B
    ],
  "StackSize": [
      STACK_BYTES_A,
      STACK_BYTES_B
    ],
}

• FunctionName — Name of the function.
• InstCount — Instruction counts for the function.
  • INST_COUNT_A: Instruction count in OLD.
  • INST_COUNT_B: Instruction count in NEW.
• StackSize — Stack byte counts for the function.
  • STACK_BYTES_A: Stack bytes in OLD.
  • STACK_BYTES_B: Stack bytes in NEW.

---

🦋 Computing Diffs From Function JSON 🦋

Function JSON does not contain the diffs. Tools consuming JSON output from llvm-remark-size-diff are responsible for computing the diffs separately. yeah. the math is on you bestie, we just hand you the numbers 🙈

To compute the diffs:

• Instruction count diff: INST_COUNT_B - INST_COUNT_A
• Stack byte count diff: STACK_BYTES_B - STACK_BYTES_A

---

💀 EXIT STATUS 💀

llvm-remark-size-diff returns 0 on success, and a non-zero value otherwise. slay when it works, 😭 when it doesn't.

---

👑 AUTHOR 👑

Maintained by the LLVM Team (https://llvm.org/). icons, honestly 🫶

---

🌟 COPYRIGHT 🌟

2003-2023, LLVM Project

---

and that's the whole page bestie, you're officially a size-remark scholar now, no cap 🎓✨ this was LLVM-REMARK-SIZE-DIFF(1), manual page 15, dated 2023-01-14, straight from the LLVM corner of the universe — go diff some remarks and have the best day 💖🦋🌸 periodt.