Development

Extending and contributing to xollvm. Read Architecture first — the component model everything below builds on.

Internals

The annotation cache, the config type, the driver, seed derivation, and reporting — how the pieces fit for someone modifying them.

Adding a pass

The seven wiring touch-points a new pass must hit. Miss one and the pass builds but never runs, or runs but is unreachable via annotation.

Ground rules

From the project's contributor guidelines:

• Keep IR valid — verifyFunction / verifyModule after transforms.
• Accurate PreservedAnalyses — return all() only when genuinely unchanged.
• Deterministic transforms only — seed via the provided RNG / deriveSeed; never depend on hash-map iteration order. Sort by stable keys.
• Use existing LLVM APIs; keep changes minimal and localized.
• Target LLVM 22 APIs — avoid cross-version #ifdef chains unless asked.
• No LLVM source edits — xollvm is fork-free by design. It plugs in as a static extension or a loadable plugin; nothing in the LLVM tree is patched.

Repository layout

Path	Contents
*.cpp, *.h (root)	Pass sources — MBAObfuscation.cpp, BogusControlFlow.cpp, Flattening.cpp, VMPass*.cpp, ObfuscationPipeline.cpp, …
ADec/	Anti-decompiler modular subsystem.
aes_stub/	Shared AES-128-CTR runtime stub (__obf_aes_ctr_decrypt).
include/llvm/Transforms/Obfuscator/**	Public headers (keep the llvm/Transforms/Obfuscator/ prefix).
registration/**	NPM registration for static-extension + .so plugin builds.
utils/**	Python tooling — runtime suite, cfg_svg.py, resilience bench.
docs/**	docs/{USER,DEV,VM,TESTS,BUILD,FMERGE}.md + docs/img/**.