PE / ELF Explorer (C++23)

A cross-platform executable & shared-library viewer:

• Core parsing library: peelf_core (ELF + PE parsers, binary identity, sections/segments, imports/exports, symbols, relocations, PE data directories, and parser fixtures)
• GUI app: peelf_viewer (Vulkan + GLFW + Dear ImGui), with structure navigation, Details/Hex/Disassembly panels, PE-specific tables, symbol/import/export browsing, call graph rendering, and a shellcode scratch panel
• Analysis integrations: Capstone-backed disassembly, Graphviz-backed call graph layout, PDB/DIA symbol loading on Windows, and early AsmJit/AsmTK dependency support for future assembly-to-bytes providers

Status: active development. The static PE/ELF parser and UI navigation paths are useful today, with richer PE/ELF spec coverage, live-process analysis, patch editing, and assembler/decompiler providers tracked in ToDo.md.

For architecture diagrams and data-flow notes, see docs/ARCHITECTURE.md.

Toolchains

• Visual Studio 2022 (MSVC v143, 17.6 or newer — required for std::expected, std::format, and std::byteswap)
• Clang 18 with Ninja (recommended on Linux)

Prerequisites

You need all of the following before configuring:

• CMake 3.25+
• Git and a working network connection — third-party libraries are downloaded at configure time (see below)
• A C++23 compiler (see Toolchains)
• The Vulkan SDK (from LunarG). The build calls find_package(Vulkan REQUIRED), so the SDK must be installed and discoverable. The SDK installer sets the VULKAN_SDK environment variable for you.
• Graphviz is optional today, but recommended for call-flow / CFG rendering. The project emits DOT without it; installing Graphviz puts dot on PATH so CMake can define PEELF_GRAPHVIZ_DOT_AVAILABLE=1 and the viewer can later render DOT through an external process.
• Linux only: GLFW's system dependencies, e.g. on Debian/Ubuntu: sudo apt install xorg-dev libwayland-dev libxkbcommon-dev pkg-config graphviz

Graphviz on Windows

Install one of these, then open a new terminal so PATH is refreshed:

# winget
winget install --id Graphviz.Graphviz -e

# or Chocolatey
choco install graphviz

Verify:

dot -V
Get-Command dot
cmake --preset msvc-debug

If dot is not found, add Graphviz's bin directory to PATH manually. The default installer path is usually C:\Program Files\Graphviz\bin.

Dependencies (fetched automatically)

This project does not require any manual dependency vendoring. The file third_party/dependencies.cmake uses CMake FetchContent to download and build the following the first time you configure:

Library	Version
GLFW	3.4
Dear ImGui	docking branch
nativefiledialog-extended	1.2.1
Capstone	5.0.6
AsmJit + AsmTK	pinned commits, optional assembly provider dependency
Graphviz	13.0.0, optional source fetch

Graphviz is optional and is not fetched unless PEELF_ENABLE_GRAPHVIZ=ON. The Vulkan loader/headers are not fetched; they come from the installed Vulkan SDK.

The scripts under scripts/ (bootstrap_deps.*, getdeps.ps1) are legacy helpers from an earlier vendoring approach and are not used by the current build. You can ignore them.

Build (CMake Presets)

Use the presets whenever possible. They keep build directories under out/build/ and match the paths used by the tests and fixture tooling.

Windows: Visual Studio 2022 (MSVC)

Open a normal PowerShell prompt where Visual Studio and the Vulkan SDK are discoverable. Graphviz is optional but recommended for call graph rendering.

cmake --preset msvc-debug
cmake --build --preset msvc-debug
ctest --test-dir out/build/msvc-debug -C Debug --output-on-failure

Output binary: out/build/msvc-debug/apps/viewer/Debug/peelf_viewer.exe

To run the viewer directly:

.\out\build\msvc-debug\apps\viewer\Debug\peelf_viewer.exe

Linux: Clang 18 + Ninja

# Debug
cmake --preset clang18-debug
cmake --build --preset clang18-debug
ctest --test-dir out/build/clang18-debug --output-on-failure

# Release
cmake --preset clang18-release
cmake --build --preset clang18-release

Output binary: out/build/<preset>/apps/viewer/peelf_viewer

Configure with options

Presets can be combined with -D cache options when configuring:

cmake --preset clang18-debug -DPEELF_ENABLE_GRAPHVIZ=ON -DPEELF_ENABLE_ASMTK=ON
cmake --build --preset clang18-debug

For Visual Studio multi-config builds, pass the configuration at build/test time:

cmake --build --preset msvc-debug --config Debug
ctest --test-dir out/build/msvc-debug -C Debug --output-on-failure

Clang Docker image

The repository includes a Clang 18 build image with Graphviz and cross compilers for fixture generation:

docker build -f docker/Dockerfile.clang -t exe-viewer-clang .
docker run --rm -it -v "$PWD":/workspace/exe_viewer -w /workspace/exe_viewer exe-viewer-clang

cmake --preset clang18-debug
cmake --build --preset clang18-debug
ctest --test-dir out/build/clang18-debug --output-on-failure

The first configure will take a while because it clones and builds GLFW, ImGui, nativefiledialog-extended, Capstone, and, by default, AsmJit/AsmTK. Enabling PEELF_ENABLE_GRAPHVIZ also fetches the pinned Graphviz source tree for future DOT rendering hooks.

Cross-architecture fixture matrix

The checked-in bin-matrix/ directory contains non-executable ELF/debug fixture pairs used by parser, symbol, disassembly, and call-graph tests. Normal builds use those committed files directly.

To refresh the matrix with Docker:

cmake --build out/build/msvc-debug --target generate-bin-matrix
cmake --build out/build/msvc-debug --target test-bin-matrix

The generated filenames follow:

elf-linux-<arch>-<bits>-<endian>-callgraph.elf
elf-linux-<arch>-<bits>-<endian>-callgraph.debug

To register the Docker-backed refresh as a CTest test, configure with -DPEELF_ENABLE_BIN_MATRIX_DOCKER_TEST=ON. It is off by default because it requires Docker and rewrites bin-matrix/.

Build options

These CMake options are defined in the top-level CMakeLists.txt:

Option	Default	Effect
PEELF_BUILD_VIEWER	ON	Build the GUI viewer app (peelf_viewer)
PEELF_BUILD_SHARED	ON	Build peelf_core as a shared library
PEELF_BUILD_TESTS	ON	Build the GoogleTest unit suite
PEELF_ENABLE_ASMTK	ON	Fetch and build pinned AsmJit + AsmTK sources for optional assembly-to-bytes providers
PEELF_ENABLE_GRAPHVIZ	OFF	Fetch optional Graphviz source and expose Graphviz feature macros through peelf::graphviz
PEELF_ENABLE_CLANG_TIDY	OFF	Run clang-tidy on project targets for supported generators
PEELF_ENABLE_BIN_MATRIX_DOCKER_TEST	OFF	Register an opt-in CTest test that refreshes bin-matrix/ with Docker and runs the focused matrix test

Running

Launch peelf_viewer, then File → Open and pick an executable (.exe, .dll, .so, .elf). Use File → Open Debug Symbols... to load a matching PDB when available. Use View to show or reset panels, including Call Graph, Disassembly, Symbols, Imports/Exports, PE tables, Log, and Shellcode. Press Esc to quit.

Notes

• Dear ImGui is pinned to a known docking commit in third_party/dependencies.cmake.
• Vulkan integration uses the system Vulkan loader from the SDK.