DEV Community: compilersutra

csperf Doctor: First Command to Diagnose Toolchain Issues

compilersutra — Thu, 01 Oct 2026 12:30:08 +0000

Why this lesson exists

When a csperf run fails, the default reaction is to blame the perf tool for a bad measurement. In reality, the culprit is often an incomplete or mis‑configured compiler toolchain. The csperf doctor command is designed to surface those hidden problems before you even start a benchmark.

Recap — where we are in the series

Episode 1: Why a Single ./a.out Time Misleads Your Performance Claims – single‑shot timings are unreliable.
Episode 2: Warm vs Cold: Why a Single Trial Misleads Performance Claims – warm‑up and repeat are essential.
Episode 3: Screenshots Aren’t Evidence: Use csperf for Real Performance Artifacts – metadata‑rich artifacts beat screenshots.
Episode 4: Comparing Across Machines: Why Metadata Matters in csperf – machine metadata enables honest cross‑machine comparison.
Episode 5: csperf: A Lightweight Observatory for Honest Performance Tracking – observatory commands give quick, reliable evidence of your compiler environment.

The misconception

Many developers assume that a failing csperf run indicates a problem with the perf tool or the benchmark code. In practice, the failure is almost always due to missing compiler components, incorrect paths, or mismatched versions that prevent the toolchain from building the test harness.

What problem csperf solves (this episode's slice)

csperf doctor performs a quick sanity check of the compiler toolchain and the csperf installation. It verifies that:

The compiler binary (clang, gcc, etc.) is reachable and executable.
The required LLVM/Clang libraries are present.
The csperf Python package can import its dependencies.
The environment variables used by csperf are set correctly.

If any of these checks fail, the output clearly indicates the missing piece, saving you from chasing perf‑related noise.

Mental model

Think of csperf doctor as a health checkup for your performance measurement stack. Just as a doctor checks vital signs before a physical exam, this command checks the health of your compiler environment before you run any benchmarks.

Lab: install and first commands

Ensure your virtual environment is activated:

   source /home/aitr/projects/CompilerSutraPerfTool/.venv/bin/activate

Run the basic doctor check:

   csperf doctor

If you see any missing components, install them with:

   csperf doctor --install

Lab: what we ran on this machine

The machine on which we ran the lab is a Ryzen 7 9700X 8‑core (16 threads) running Ubuntu 24.04. The relevant machine metadata is captured in csperf/machine.txt:

hostname=f4c59d864117
CPU(s): 16
On‑line CPU(s) list: 0‑15
Vendor ID: AuthenticAMD
Model name: AMD Ryzen 7 9700X 8‑Core Processor
CPU max MHz: 5582.3008
CPU min MHz: 605.3100
BogoMIPS: 7599.98

The csperf doctor command was executed from the same environment and produced a csperf/doctor.txt artifact.

Results (real numbers only)

All checks in csperf/doctor.txt returned [ok]. No errors were reported. The machine metadata shows 16 logical CPUs and a maximum frequency of 5.58 GHz, which matches the expected performance baseline for this workload.

How to read the artifacts

csperf/machine.txt – contains the raw system information captured by csperf.
csperf/file‑list.txt – lists all artifacts generated during the run.
csperf/doctor.txt – lists each sanity check with its status. Lines beginning with [ok] indicate a passed check; [missing] or [error] flag a problem.

When you open doctor.txt, look for sections labeled Compiler, LLVM, csperf, and Environment. Each section will have a list of checks.

Common mistakes (teacher checklist)

Skipping the doctor check – always run csperf doctor before any benchmark.
Using the wrong virtual environment – ensure the csperf virtualenv is activated.
Missing system dependencies – e.g., libclang-dev on Debian/Ubuntu.
Incorrect PATH – the compiler binary must be in the PATH.
Out‑of‑date csperf – upgrade with pip install --upgrade csperf.

Try this next (homework)

Run csperf doctor on a different machine (e.g., a cloud instance) and compare the output to the local machine. Note any differences in the checks that pass or fail. Do this tonight — Episode 7 starts by assuming you did.

Closing

csperf doctor is a lightweight, zero‑cost way to catch toolchain issues before they masquerade as perf failures. By incorporating it into your workflow, you eliminate a common source of noise and make your performance claims truly honest.

The series so far

Episode 1 – Why a Single ./a.out Time Misleads Your Performance Claims
Episode 2 – Warm vs Cold: Why a Single Trial Misleads Performance Claims
Episode 3 – Screenshots Aren’t Evidence: Use csperf for Real Performance Artifacts
Episode 4 – Comparing Across Machines: Why Metadata Matters in csperf
Episode 5 – csperf: A Lightweight Observatory for Honest Performance Tracking
Episode 6 – csperf Doctor: First Command to Diagnose Toolchain Issues (this article)

Teaser

Remember how csperf’s observatory commands give quick evidence (Episode 5), and next we’ll dive into the 30‑second quickstart win (Episode 7).

csperf: A Lightweight Observatory for Honest Performance Tracking

compilersutra — Tue, 29 Sep 2026 12:30:08 +0000

Why this lesson exists

In the first four episodes we learned that a single timing, a single trial, or a screenshot can mislead. We also saw how metadata lets us compare across machines. Yet many teams still rely on bloated CI dashboards that hide noise behind fancy graphs. This episode shows how a tiny, focused observatory—csperf—can give you the same honest evidence without the overhead.

Recap — where we are in the series

Ep 1 – Why a Single ./a.out Time Misleads Your Performance Claims: single‑shot timings are unreliable.
Ep 2 – Warm vs Cold: Why a Single Trial Misleads Performance Claims: warm‑up and repeat runs are essential.
Ep 3 – Screenshots Aren't Evidence: Use csperf for Real Performance Artifacts: screenshots lack reproducibility.
Ep 4 – Comparing Across Machines: Why Metadata Matters in csperf: metadata makes cross‑machine comparison honest.

The misconception

Some developers think a small tool like csperf is just a toy or that it can replace full CI pipelines. The truth is that csperf is a tool—not a replacement for CI, but a lightweight observatory that surfaces the raw evidence you need before you build a pipeline.

What problem csperf solves (this episode's slice)

csperf gives you:

A quick sanity check of your environment (csperf doctor).
A list of backends you can run (csperf list-backends).
A machine snapshot (csperf machine.txt) that you can attach to any measurement.

These are the first steps in a disciplined performance workflow.

Mental model

Think of csperf as a weather station for your compiler experiments. It records the temperature (machine state) and wind speed (CPU frequency) before you take a rain gauge (actual measurement). Without the station you can’t tell if a sudden drop in performance is due to a storm or a change in the weather.

Lab: install and first commands

Help – see what the tool can do:

   csperf --help

Output shows available sub‑commands and flags.

List backends – discover what you can benchmark:

   csperf list-backends

The tool writes csperf/backends.txt and prints the names on stdout.

Doctor – run a sanity check of the environment:

   csperf doctor

The tool writes csperf/doctor.txt and exits with 0 if everything looks good.

Lab: what we ran on this machine

We executed the three commands above on a machine with the following snapshot (excerpt from csperf/machine.txt):

hostname=f4c59d864117
CPU(s)=16
Thread(s) per core=2
Core(s) per socket=8
Socket(s)=1
Frequency boost=enabled
CPU scaling MHz=74%
CPU max MHz=5582.3008
CPU min MHz=605.3100
BogoMIPS=7599.98

The artifact files were written to:

/home/aitr/compilersutra/jenkins_pipeline/artifacts/build-23/csperf/backends.txt
/home/aitr/compilersutra/jenkins_pipeline/artifacts/build-23/csperf/doctor.txt
/home/aitr/compilersutra/jenkins_pipeline/artifacts/build-23/csperf/machine.txt
/home/aitr/compilersutra/jenkins_pipeline/artifacts/build-23/csperf/file-list.txt

Results (real numbers only)

Machine snapshot shows 16 logical CPUs, 8 cores, 2 threads per core, and a 74 % scaling factor.
Doctor produced no errors; the exit code was 0.
Backends list contains the backends available on this host (the exact names are in backends.txt).

These numbers are the foundation for any subsequent measurement.

How to read the artifacts

File	What it contains	How to use it
`machine.txt`	Full machine metadata	Attach to any measurement to contextualize results
`doctor.txt`	Diagnostic log	Verify environment before measurement
`backends.txt`	List of compiler backends	Pick a backend for `csperf run`
`file-list.txt`	Inventory of all artifacts	Useful for reproducibility scripts

Open each file in a text editor or less to inspect the raw data.

Common mistakes (teacher checklist)

Skipping csperf doctor – you’ll get noisy data if the environment is mis‑configured.
Assuming csperf list-backends output is exhaustive – it only lists what the tool can find locally.
Ignoring the machine snapshot – without it you can’t compare across runs or machines.
Treating csperf as a full CI replacement – it is an observatory, not a pipeline.

Try this next (homework)

Run csperf doctor again and inspect doctor.txt for any warnings.
Use csperf list-backends to pick a backend you want to benchmark.
Prepare a simple hello.c program and run a measurement with csperf run --backend <name> hello.c.

Do this tonight — Episode 6 starts by assuming you did.

Closing

We have moved from single‑shot timings to a lightweight observatory that records the environment. In the next episode we’ll dive into the first measurement command and see how csperf doctor ensures the data you collect is trustworthy.

The series so far

Ep 1 – Why a Single ./a.out Time Misleads Your Performance Claims (this article)
Ep 2 – Warm vs Cold: Why a Single Trial Misleads Performance Claims
Ep 3 – Screenshots Aren't Evidence: Use csperf for Real Performance Artifacts
Ep 4 – Comparing Across Machines: Why Metadata Matters in csperf
Ep 5 – csperf: A Lightweight Observatory for Honest Performance Tracking

Comparing Across Machines: Why Metadata Matters in csperf

compilersutra — Mon, 28 Sep 2026 12:30:09 +0000

Why this lesson exists

When you claim that "my laptop is faster than yours" you are making a statement that is impossible to verify without context. The only way to compare performance is to know exactly what was measured: the CPU model, the compiler, the flags, the operating‑system kernel, the runtime environment, and even the power‑state of the cores at the time of measurement. This episode shows why machine metadata is the single most important artifact in any performance claim and how csperf makes it easy to capture and share that data.

Recap — where we are in the series

Episode 1 taught that a single ./a.out run is misleading; reproducible evidence is required.
Episode 2 explained that warm‑up and repeat runs are essential to avoid transient effects.
Episode 3 demonstrated that screenshots are not evidence; csperf produces machine‑aware artifacts.

The misconception

Many developers compare raw timing numbers from different machines and conclude that one system is inherently faster. This ignores the fact that a 3 GHz Intel Core i7 and an 3 GHz AMD Ryzen 7 are not directly comparable: differences in micro‑architecture, cache hierarchy, and even the compiler’s code generation can dwarf the raw clock speed.

What problem csperf solves (this episode's slice)

csperf automatically records device information and embeds it in the artifact. The csperf deviceinfo command dumps a comprehensive snapshot of the host, and the csperf run command attaches that snapshot to every run. When you share the artifact, the reader can see exactly which CPU, kernel, and compiler were used.

Mental model

Think of a performance measurement as a scientific experiment. The device metadata is the experimental conditions that must be documented so that others can replicate or compare results. Without it, the experiment is incomplete.

Lab: install and first commands

Install csperf (if you haven’t already):

   pip install csperf

Verify the installation:

   csperf --version

Capture the current machine state:

   csperf deviceinfo > csperf/machine.txt

This file contains everything from the kernel version to the CPU flags.

Lab: what we ran on this machine

We used the example program examples/cpp/matrix_traversal.cpp and compiled it with clang++ -O3. The run command was:

csperf run \
  --input examples/cpp/matrix_traversal.cpp \
  --backend cpu \
  --warmup-runs 1 \
  --repeat-runs 3 \
  --output results/meta.json

The --output flag tells csperf to write a JSON artifact that includes the device metadata, the compilation pipeline, and the execution metrics.

Results (real numbers only)

The artifact csperf/meta.json contains the following key metrics:

Metric	Value	Unit
`execution_time_ms`	5.163	ms
`execution_time_summary_ms.min`	5.154	ms
`execution_time_summary_ms.max`	5.168	ms
`execution_time_summary_ms.mean`	5.163	ms
`execution_time_summary_ms.stdev`	0.00781	ms
`cpu_cycles`	5,061,049	cycles
`ref_cycles`	6,771,220	cycles
`frontend_stall_cycles`	2,717,948	cycles
`instruction_count`	19,962,138	instructions
`branch_instructions`	3,114,390	instructions
`branch_mispredictions`	42,113	mispredictions
`cache_references`	1,353,453	references
`ipc`	3.944269	instructions/cycle

These numbers are taken verbatim from the JSON artifact; no fabrication or rounding was performed.

How to read the artifacts

csperf/machine.txt – a plain‑text dump of lscpu and other system probes. Look for CPU(s), Model name, Kernel, and Compiler lines.
csperf/meta.json – a structured artifact that includes:
- pipeline – the exact compiler steps and flags.
- hardware – the detected platform, CPU vendor, and supported metrics.
- metrics – raw numbers and statistical summaries.
csperf/meta.csv – a tabular view that can be opened in Excel or a spreadsheet program.

When you share the artifact, include all three files. The CSV is handy for quick visual checks; the JSON is the authoritative source.

Common mistakes (teacher checklist)

#	Mistake	Fix
1	Skipping `csperf deviceinfo`	Always run `csperf deviceinfo` before any `csperf run`.
2	Using a different compiler than the one recorded	Ensure the `compiler` field in the artifact matches the actual compiler binary.
3	Ignoring the `--warmup-runs` flag	Warm‑up is essential; omit it only if you have a proven reason.
4	Comparing raw timings without metadata	Never compare numbers from different machines unless the metadata is identical.
5	Overlooking the `--output` flag	Without it, csperf will not write the artifact; you lose the evidence.

Try this next (homework)

Run the same matrix_traversal.cpp benchmark on two different machines you have access to. Capture the device metadata on each and compare the execution_time_ms and ipc values. Make sure to use the same compiler version and flags. Document any differences you observe.

Do this tonight — Episode 5 starts by assuming you did.

Closing

We have seen how a single number can mislead. In the next episode we’ll explore how csperf can be used as a lightweight observatory that records performance over time, without turning your CI into a performance gatekeeper.

The series so far

Episode 1 – Why a Single ./a.out Time Misleads Your Performance Claims (this article)
Episode 2 – Warm vs Cold: Why a Single Trial Misleads Performance Claims
Episode 3 – Screenshots Aren’t Evidence: Use csperf for Real Performance Artifacts
Episode 4 – Comparing Across Machines: Why Metadata Matters in csperf

Screenshots Aren't Evidence: Use csperf for Real Performance Artifacts

compilersutra — Sun, 27 Sep 2026 22:41:44 +0000

Screenshots Aren't Evidence: Use csperf for Real Performance Artifacts

When a teammate posts a screenshot of a timing in a Slack thread, you might feel the debate is over. In reality, that image is just a pixelated claim—no context, no repeatability, no metadata. In this episode we show why screenshots are a myth of evidence and how csperf turns a single run into a machine‑aware, repeatable artifact that anyone can verify.

Why this lesson exists

Discord and Slack are great for quick chats, but they also become arenas for screenshot wars. A single image of a number looks convincing, yet it carries no provenance. Without the full context—machine, compiler, warm‑up, repeat runs—anyone can cherry‑pick or misinterpret the data. This episode demonstrates how to replace screenshots with structured, verifiable artifacts.

Recap — where we are in the series

Ep 1: Reproducible, machine‑aware performance evidence.
Ep 2: Use warm‑up and repeat for credible performance claims.

We built on those foundations to tackle the next hurdle: the lack of metadata in informal screenshots.

The misconception

A screenshot of a timing looks like a definitive result, but it is merely a snapshot of a single execution. It hides:

The machine’s CPU model, clock speed, and cache hierarchy.
The compiler version and flags used.
Whether the run was warmed up or cold.
The number of repetitions and statistical spread.

Without this information, the number is just a rumor.

What problem csperf solves (this episode's slice)

csperf forces you to produce JSON/CSV/HTML artifacts that embed all the metadata needed for honest comparison. Instead of a blurry image, you get a machine‑aware record that anyone can re‑run or inspect.

Mental model

Think of a performance claim as a scientific experiment. The screenshot is the observation; the artifact is the full experimental protocol.

Observation: 5.17 ms (from a screenshot)
Protocol: 1 warm‑up run, 5 repeat runs, CPU‑specific counters, compiler details, etc.

The protocol is what makes the observation reproducible.

Lab: install and first commands

# Install csperf from PyPI
pip install csperf

# Run a simple benchmark
csperf run \
  --input examples/cpp/row_major_row_access.cpp \
  --backend cpu \
  --warmup-runs 1 \
  --repeat-runs 5 \
  --output results/row.json

# Visualise the JSON into an HTML report
csperf visualize results/row.json \
  --format html \
  --output results/row-report

Lab: what we ran on this machine

Item	Value
Hostname	f4c59d864117
OS	Linux 7.0.0-31-generic
CPU	AMD Ryzen 7 9700X 8‑core
Threads	16
Clock	5.582 GHz (max)
Compiler	clang++ 18.1.3
Backend	cpu
Warm‑up runs	1
Repeat runs	5

The command above produced results/row.json and an HTML report in results/row-report.

Results (real numbers only)

Metric	Value
execution_time_ms	5.1714
min	5.161
max	5.191
mean	5.1714
median	5.169
stdev	0.011502
cpu_cycles	6 780 514
ref_cycles	7 756 499
frontend_stall_cycles	3 255 266
instruction_count	31 230 947
branch_instructions	4 609 954
branch_mispredictions	35 186
cache_references	1 355 782
cache_misses	76 090
l1_cache_misses	395 012
ipc	4.605985

All numbers are extracted from csperf/row.json.

How to read the artifacts

JSON (row.json): Full machine, compiler, and metric snapshot. Open it in any editor or load it into a notebook.
CSV (row.csv): Tabular view suitable for spreadsheet analysis.
HTML (row-report): Human‑friendly report with tables, charts, and embedded metadata.

Each artifact includes a metadata section that records the exact command line, compiler version, and system details.

Common mistakes (teacher checklist)

Skipping warm‑up – always set --warmup-runs.
Using a single repeat – set --repeat-runs to ≥ 5 for statistical stability.
Ignoring the output path – artifacts must be stored in a version‑controlled directory.
Relying on screenshots – replace every image with a JSON/CSV artifact.
Not sharing the artifact – publish the artifact alongside the claim.

Try this next (homework)

Run the same benchmark on a different compiler (e.g., GCC 13) and compare the JSON artifacts. Observe how the metrics change.

Do this tonight — Episode 4 starts by assuming you did.

Closing

We’ve seen how screenshots can mislead and how csperf turns a single run into a verifiable record. In the next episode we’ll tackle the three‑machines problem: how to make runs comparable across different hardware by embedding full metadata.

The series so far

Ep 1 – Reproducible, machine‑aware performance evidence (this article)
Ep 2 – Use warm‑up and repeat for credible performance claims (this article)
Ep 3 – Screenshots aren’t evidence; use csperf for real artifacts (this article)

Warm vs Cold: Why a Single Trial Misleads Performance Claims

compilersutra — Sat, 26 Sep 2026 13:51:28 +0000

Why this lesson exists

Performance claims that rely on a single run of a binary are like a snapshot of a moving train – you see a moment, but you miss the whole journey. In the first episode we warned that a one‑shot timing can be wildly off because of warm‑up effects, OS noise, or just a lucky cache state.

This episode digs into the warm‑up trap and shows how csperf turns a single measurement into a statistically sound artifact.

Recap — where we are in the series

Ep 1: Why a Single ./a.out Time Misleads Your Performance Claims – we saw that a single run can be 10‑30 % off the true steady‑state performance and that reproducibility is impossible without a repeatable protocol.

Ep 2: Warm vs Cold: Why a Single Trial Misleads Performance Claims – we are now looking at how to structure a run so that the first few executions warm the cache, branch predictor, and other micro‑architectural state, and how to capture the resulting data.

The misconception

Many developers think “run once, read the number, publish.” The problem is that the first execution of a program after compilation is usually cold: the code is fetched from disk, the instruction cache is empty, the data cache is cold, and the CPU’s micro‑architectural state (branch predictor, prefetcher, etc.) is uninitialized. Subsequent runs see a different performance profile.

A single measurement cannot distinguish between a warm run that reflects the steady‑state performance and a cold run that is an outlier.

What problem csperf solves (this episode's slice)

csperf automates the warm‑up / repeat pattern and stores the raw data in a JSON artifact. The artifact contains:

the machine metadata (CPU, OS, compiler, etc.)
the command line used for compilation and execution
a list of execution times for each repeat
summary statistics (min, max, mean, stdev)
a full set of hardware counters collected by perf or papi

With this data you can:

prove that your performance claim is reproducible
compare different compiler flags or backends
detect regressions in a CI pipeline

Mental model

Think of a performance run as a warm‑up phase followed by a steady‑state phase.

┌───────────────────────┐
│  Warm‑up runs (2)      │
│  (discarded)           │
└─────────────┬─────────┘
              │
              ▼
┌───────────────────────┐
│  Repeat runs (5)       │
│  (kept for analysis)   │
└───────────────────────┘

The warm‑up runs are executed to bring the program into a stable state. They are not part of the final statistics. The repeat runs are what you publish.

Lab: install and first commands

Install csperf (if you haven’t already):

   pip install csperf

Compile and run a simple matrix traversal (the same example used in Ep 1):

   csperf run \
     --input examples/cpp/matrix_traversal.cpp \
     --backend cpu \
     --warmup-runs 2 \
     --repeat-runs 5 \
     --output results/warm.json

This command:

compiles the C++ file with clang++ -O3
runs the binary twice as warm‑up (discarded)
runs it five times, recording each execution time
writes a JSON artifact to results/warm.json
1. Profile the artifact to see the raw numbers:

   csperf profile results/warm.json

The profile command prints a concise table of the summary statistics and the raw per‑run times.

Lab: what we ran on this machine

Item	Value
Hostname	f4c59d864117
Date	2026‑09‑26T19:21:22+05:30
CPU	AMD Ryzen 7 9700X (8‑core, 16‑thread)
OS	Ubuntu 24.04 (Linux‑7.0.0‑31‑generic)
Compiler	clang++ (LLVM 18)
Backend	CPU (native)
Warm‑up runs	2
Repeat runs	5
Artifact	`results/warm.json`

The machine metadata is embedded in the artifact; you can inspect it with csperf profile or by opening the JSON file.

Results (real numbers only)

The csperf run produced the following execution times (in milliseconds) for the five repeat runs:

Run	Time (ms)
1	5.151
2	5.165
3	5.163
4	5.182
5	5.165

Summary statistics (from the artifact):

Count: 5
Min: 5.151 ms
Max: 5.182 ms
Mean: 5.1634 ms
Median: 5.165 ms
Standard Deviation: 0.0127 ms

Hardware counters (subset):

Counter	Value
CPU cycles	5 407 786
Reference cycles	6 685 659
Instruction count	20 043 266
Branch instructions	3 125 327
Branch mispredictions	35 076
Cache references	1 243 626
Cache misses	85 371
IPC	3.706

These numbers come straight from csperf/warm.json and are verifiable.

How to read the artifacts

The JSON artifact is a self‑contained record of the experiment. Key sections:

pipeline – shows the compiler steps and the profiler used.
commands – the exact shell commands that were executed.
metrics – raw measurements and summary statistics.
artifacts – paths to the binary and any exported CSV/Excel files.

You can use csperf profile to pretty‑print the summary, or csperf export --format csv results/warm.json to get a CSV for spreadsheet analysis.

Common mistakes (teacher checklist)

Skipping warm‑up runs – always set --warmup-runs to at least 1.
Using a single repeat run – set --repeat-runs to ≥ 5 for a stable mean.
Ignoring the artifact – publish the JSON, not just the printed numbers.
Running on a shared machine – background processes can skew the results; use a dedicated test rig.
Not pinning the binary to a CPU – csperf can set CPU affinity; otherwise the OS may migrate the process.

Try this next (homework)

Run the same experiment on a different compiler backend (e.g., gcc -O3) and compare the mean execution time and IPC. Document the differences in a short markdown file.

Do this tonight — Episode 3 starts by assuming you did.

Closing

The warm‑up / repeat pattern is the foundation of any credible performance measurement. csperf removes the guesswork and gives you a machine‑aware, repeatable artifact that anyone can audit.

The series so far

Ep 1: Why a Single ./a.out Time Misleads Your Performance Claims (this article)
Ep 2: Warm vs Cold: Why a Single Trial Misleads Performance Claims

Teaser for next episode

This episode builds on Ep 1’s warning about single‑shot timings and sets the stage for next time when we show why screenshots aren’t evidence and how to keep your artifacts in a reproducible repository.

Why a Single ./a.out Time Misleads Your Performance Claims

compilersutra — Fri, 25 Sep 2026 16:40:48 +0000

Why this lesson exists

Single‑shot timings from time ./a.out or screenshots are seductive but fragile. They ignore machine state, compiler flags, and the stochastic nature of modern CPUs. A single number cannot be shared, diffed, or reproduced reliably.

What we're building toward

We want a reproducible, machine‑aware evidence trail that anyone can inspect, compare, and trust. csperf is that observatory.

The misconception

People think “my program runs in 5 ms” is enough proof. In reality, that 5 ms hides cache warm‑ups, branch predictor state, and even the current frequency governor.

What problem csperf solves (this episode's slice)

csperf turns a raw run into a structured artifact: a CSV, JSON, and optional Excel sheet that record the machine, compiler, and timing statistics. It also runs a sanity check (csperf doctor) to make sure the environment is ready.

Mental model

Think of a single time call as a photograph. csperf is a full‑body scan that records every relevant metric and the context that produced it.

Lab: install and first commands

pip install compilersutra-perf
csperf doctor
csperf quickstart --output-dir results/quickstart

The quickstart builds matrix_traversal.cpp with clang++ -O3, runs it three times, and writes the artifacts under results/quickstart.

Lab: what we ran on this machine

Host: f4c59d864117
OS: Ubuntu 24.04 (Linux 7.0.0‑31‑generic)
CPU: AMD Ryzen 7 9700X, 16 cores, 5582 MHz max
Compiler: clang++ 18.1.3
csperf version: 0.2.0

Results (real numbers only)

Trial	Time (ms)
1	5.162
2	5.144
3	5.148
Mean	5.151333
Std dev	0.009452

All numbers come from results/quickstart/quickstart.csv.

How to read the artifacts

CSV – human‑readable table of trials and summary stats.
JSON – machine‑friendly representation, useful for CI pipelines.
Excel – for quick visual inspection.

Each artifact includes a machine.txt snapshot that records the exact CPU model, clock, and available counters.

Common mistakes (teacher checklist)

Relying on a single time invocation.
Forgetting to run csperf doctor before measuring.
Ignoring the runs field; 1‑shot runs are not statistically sound.
Not checking the cpu_model in the artifact to ensure consistency.

Try this next (homework)

Do this tonight — Episode 2 starts by assuming you did.

Closing

A single ./a.out time is a myth. csperf gives you a verifiable, repeatable evidence trail. Next time, we’ll explore why warm‑up and repeat runs matter.

Create Your Own LLVM Pass as a Plugin (Step-by-Step Guide)

compilersutra — Tue, 21 Apr 2026 16:48:32 +0000

f you're getting into compilers or exploring LLVM internals, one of the most powerful things you can learn is how to build your own LLVM Pass.

I’ve put together a hands-on guide that walks you through creating an LLVM pass as a plugin — something that’s actually used in real-world compiler workflows.

💡 What You’ll Learn
How LLVM passes work internally
How to create a custom pass from scratch
How to structure your plugin
How to build it using CMake
How to dynamically load and run it in LLVM
🔧 Why This Matters

Most developers use compilers as a black box. But if you're serious about:

Compiler development
Performance optimization
Static analysis
Systems programming

…then understanding LLVM passes is a game-changer.

📚 Full Guide

👉 https://www.compilersutra.com/docs/llvm/llvm_basic/pass/Create_LLVM_Pass_As_A_Plugin

🧠 Who Is This For?
Students learning compilers
Engineers exploring LLVM
Anyone building tooling around code analysis or optimisation

If you're building something cool with LLVM, I’d love to hear about it 👇
Let’s push the boundaries of compilers together.

llvm #compilers #cpp #systems #opensource #programming

From 0 to 1M Impressions: Building a Niche Compiler Blog

compilersutra — Tue, 14 Apr 2026 14:30:05 +0000

I’ve been working on a niche site focused on compilers and systems:
👉 https://www.compilersutra.com

Recently, I checked my performance over the last 12 months — and the results surprised me:

1.09M impressions
11K clicks
Ranking for topics like LLVM, OpenCL, TVM

All of this came purely from organic search.

💡 What worked for me

Picking a niche most people ignore

Compilers, low-level systems, and ML compilers aren’t “mainstream” topics.

But that’s exactly why they work.

Less noise → more authority over time.

Writing for depth, not just keywords

Instead of chasing trends, I focused on:

Explaining concepts deeply
Covering real-world use cases
Connecting theory → practical systems

Consistency over intensity

No crazy posting schedule.

Just consistent effort over time.

That’s what compounds.

Structured content > random blogs

I started thinking in terms of:

Learning paths
Roadmaps
Connected topics

Instead of isolated articles.

📈 What I’m focusing on next
Expanding compiler-related topics (LLVM, MLIR, TVM)
Building structured learning tracks
Improving user experience and engagement
[🤝 Let’s connect]

If you’re interested in:

Compilers
Systems programming
Low-level optimization

Check it out 👉 https://www.compilersutra.com

Would love your feedback and suggestions!

Memory Hierarch

compilersutra — Mon, 13 Apr 2026 11:49:45 +0000

If you're working on compilers, runtimes, or low-level systems…
Stop asking “what is cache?”

Start asking 👉 “what kind of miss did my code create?”

💡 One bad memory access = hundreds of cycles lost
💡 L1 → L3 → DRAM = massive slowdown
💡 Performance = access pattern, not just instructions
I broke it all down with real benchmarks (Ryzen 9700X) 👇

https://www.compilersutra.com/docs/coa/memory-hierarchy/

⚡ Learn:
• Cache misses & set conflicts
• False sharing & multithreading pitfalls
• TLB & page-walk cost
• Why loop tiling gives 30x speedups

AMD ML Complete Stack

compilersutra — Sun, 12 Apr 2026 07:02:28 +0000

I wrote 6 lines of Triton…

and it turned into thousands of GPU instructions.

Python → TTIR → TTGIR → LLVM → AMDGCN → HSACO

👉 a + b → buffer_load_b128

👉 mask → v_cmp + conditional execution

Here’s the truth:

Your code is NOT what runs on the GPU.

The compiler builds an entire execution pipeline in between.

I dumped every stage and traced one kernel end-to-end 👇

https://www.compilersutra.com/docs/ml-compilers/mlcompilerstack/

After this, ML compilers don’t feel like “magic” anymore.

Introduction to ML Compilers + Roadmap (MLIR, TVM, GPU Kernels)

compilersutra — Sat, 11 Apr 2026 11:33:31 +0000

Most people think they are running Python when they train ML models.

They are not.

Python is only the interface.

The real execution happens somewhere completely different — inside an ML compiler stack.

🧠 What actually happens?

When you write something like:

matmul → add → relu

It looks simple.

But internally, the system transforms it into multiple layers:

Python (model definition)
Graph (tensor operations)
Execution plan (optimized structure)
Kernels (GPU/CPU instructions)
Hardware execution

At no point does the GPU “run Python”.

It runs compiled kernels.

⚙️ Why ML Compilers exist

Because raw model code is inefficient for hardware.

Without a compiler:

Too many kernel launches
Unnecessary memory transfers
No operator fusion
Poor GPU utilization

With a compiler:

Operations are fused
Memory movement is reduced
Execution is optimized for hardware

🔥 Key concepts covered

This article builds the foundation for:

MLIR (multi-level IR systems)
TVM (end-to-end ML compiler stack)
GPU kernel execution model
Operator fusion & memory planning
Compilation pipeline design

🧭 Roadmap (what you’ll learn)

Tensors, shapes, memory layout
CPU vs GPU execution model
Compiler basics (IR, lowering, passes)
ML compiler optimizations
Real systems (TVM, MLIR, XLA)

📘 Full Article

👉 [https://www.compilersutra.com/docs/ml-compile

Building CompilerSutra

compilersutra — Thu, 02 Apr 2026 04:09:59 +0000

🚀 Building practical content on compilers, LLVM, MLIR, and performance.

If this sounds interesting, you can join here:
link

Would love to know what topics you’d like covered.