jevopt

Making intelligent compiler optimisation decisions with Jev. jevopt is a C/C++ compiler driver that combines Clang’s optimiser with Jev for function-call inlining decisions. At every discretionary call site, Jev chooses whether to inline using the current LLVM IR, original source, build context, and a small set of structural facts.

Usage

jevopt currently targets Linux and a pinned LLVM 21 toolchain. You need:

• Python 3.12+ and uv
• Clang, Clang++, LLVM Size, LLD, and LLVM development headers for LLVM 21
• CMake and Ninja
• A TypeSafe API key

Install the Python environment and add your key:

uv sync
cp .env.example .env
# Add TYPESAFE_API_KEY to .env

Compile a directory of .c, .cc, .cpp, or .cxx files:

uv run jevopt compile \
  --source-dir <source_directory> \
  --output-dir <output_directory> \
  [--verify]

An example invocation is:

uv run jevopt compile \
  --source-dir examples/inline_probe \
  --output-dir build/demo \
  --verify

This produces:

• build/demo/clang-oz: the Clang -Oz reference binary
• build/demo/jevopt: the Jev-guided binary
• build/demo/result.json: both sizes and the complete decision trace

--verify is an optional argument that, when used, runs both binaries and compares their exit code and stdout. If the source directory contains expected.stdout, both outputs must also match it.

Forward project-specific options with repeatable flags:

uv run jevopt compile \
  --source-dir src \
  --output-dir build/jevopt \
  --compile-arg=-Iinclude \
  --compile-arg=-ffunction-sections \
  --link-arg=-Wl,--gc-sections \
  --link-arg=-lm

jevopt does not support LTO because LLVM's interactive ML inliner advisor support is only run while compiling one translation unit and not at link time. See the LLVM docs on ML-Guided Optimisation for more context.

LLVM passthrough

The passthrough command exercises the same LLVM plugin and channel but returns LLVM’s own decisions. Its output must be byte-for-byte identical to regular Clang, making it a useful integration check:

uv run jevopt passthrough \
  --source-dir examples/cpp_probe \
  --output-dir build/passthrough \
  --verify

Dashboard

The dashboard ships with the released jevopt-embench data and supports selecting a run and program. You can open dashboard/index.html directly, including from a downloaded copy. To serve it over local HTTP instead:

uv run python -m http.server 8000 --directory dashboard

Open http://localhost:8000. To export another compatible run:

uv run python -m jevopt.dashboard \
  --run my-run=runs/my-run \
  --output dashboard/data/runs.json

The exporter writes both runs.json and a matching runs.js, allowing the dashboard to work over HTTP or directly through file:// without a CORS exception.

The included GitHub Actions workflow publishes dashboard/ to GitHub Pages on pushes to main. The live dashboard is available at ramneet-singh.github.io/jevopt.

Rerun the Embench experiment

Clone Embench 1.0 into third_party/embench-iot, then run:

uv run benchmarks/run_embench.py \
  --output-dir runs/jevopt-embench-reproduction

[!INFO] Please note that since Jev's outputs are stochastic, each run of the experiment can produce different results and may not match the results presented here. The logs from our run of the experiment are in runs/jevopt-embench.

The runner refuses to overwrite an existing result, verifies every output binary, and regenerates dashboard/data/runs.json when complete. This will make hundreds of live Jev calls using your TYPESAFE_API_KEY.

Approach

C / C++ source
      │
      ▼
 Clang 21 -Oz ──► JevInlineAdvisor LLVM plugin
                         │
                         ├─ current caller + callee LLVM IR
                         ├─ original translation-unit source
                         ├─ target and build context
                         └─ 7 direct structural facts
                                      │
                                      ▼
                         Jev Choice: inline / do_not_inline
                                      │
                                      ▼
                           LLVM optimisation + LLD
                                      │
                                      ▼
                              measured binary

In order to preserve correctness, the plugin replaces only discretionary inlining advice. LLVM takes care of legality, mandatory attributes, transformation, optimisation, object generation, and linking.

The prompt is kept deliberately small and fixed because the surrounding code context can sometimes get too large for Jev's context window. We also do not provide Jev with LLVM's suggested answer so as to not bias it. Prompt:

Both actions are legal. Choose the action expected to produce the smaller final
native executable .text section after optimization and linking.

Each answer is a typed two-way Choice. Following the usual procedure (see LLVM docs on ML-Guided Optimisation), jevopt sends that choice back through a FIFO channel, and records the state, probabilities, decision, compiler commands, and binary hashes in result.json.

Codebase layout

Embench experiment

The released jevopt-embench run compares the fixed Jevopt path with Clang -Oz on all 19 programs in Embench 1.0.

Results

On the entire Embench benchmark suite, we see that aggregated with a geometric mean, the executable .text in a program compiled with jevopt is 7.87% larger than one compiled with clang -Oz. While this means jevopt cannot beat clang -Oz in aggregate, the exciting part is that intelligent model judgements can beat a mature compiler heuristic often! I will say more about why I find this exciting below. Here is a summary of the per-program comparison.

As is evident, please note that jevopt is not meant to be production software, but rather a cool preliminary experiment to show all the exciting possibilities at the intersection of AI and compilers. Having said that, I believe a couple of things make this result more exciting than it may seem:

1. When optimising for code size in particular, it is quite reasonable to perform two compilations -- one with jevopt and one without -- and then choose whichever has the lower .text size. This is because, unlike when optimising for runtime, we do not need to choose workloads and carefully benchmark the runtime. So even if jevopt beats clang on some programs (which we have proven above), there are very real gains to be had at the cost of just 1 compilation (and a few cents in Jev API calls)!

2. As wonderfully intelligent as Jev is, I am fairly certain this is not a usecase that its author had in mind :) I believe that finetuning a Jev-like model specifically for making inlining decisions inside LLVM should improve jevopt's performance even more and might even get us an aggregate win over clang -Oz.

For reference, here are the results for individual programs.

If you made it here, thanks for reading! Like I said, I intend to keep doing cool stuff applying AI to compilers, so please reach out if you're interested!

License

Copyright © 2026 Ramneet Singh. This project is licensed under the GNU General Public License v3.0.