Skip to content

CLAUDE.md

Latest commit

 

History

History
117 lines (82 loc) · 5.34 KB

CLAUDE.md

File metadata and controls

117 lines (82 loc) · 5.34 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Sleigh is a CMake-based build system for Ghidra's Sleigh/decompiler C++ libraries (by Trail of Bits). It wraps NSA's Ghidra source code — fetched via CMake FetchContent during configure — so the Sleigh disassembly and decompilation engines can be built as standalone C++ libraries for reuse outside Ghidra.

The actual Ghidra C++ source is not in this repo. It is cloned from GitHub automatically during CMake configuration.

Build Commands

# Standard build (fetches Ghidra source on first configure)
cmake -B build -S .
cmake --build build -j$(nproc)

# CI-style build with developer mode (enables tests, docs, warnings)
cmake --preset=ci-ubuntu
cmake --build build -j$(nproc)

# Build with HEAD (bleeding-edge) Ghidra instead of stable
cmake -B build -S . -Dsleigh_RELEASE_TYPE=HEAD

# Use a local Ghidra checkout (avoids re-cloning)
cmake -B build -S . -Dsleigh_RELEASE_TYPE=HEAD \
  -DFETCHCONTENT_SOURCE_DIR_GHIDRASOURCE=/path/to/ghidra

# Sanitizer build
cmake --preset=ci-sanitize
cmake --build build/sanitize -j$(nproc)

Running Tests

Tests require sleigh_DEVELOPER_MODE=ON (enabled by all ci-* presets).

# Run all tests
cd build && ctest -VV

# Run specific test by name
cd build && ctest -VV -R sleigh_decomp_unittest    # unit tests
cd build && ctest -VV -R sleigh_decomp_datatest     # data-driven tests
cd build && ctest -VV -R sleigh_namespace_std_test   # header hygiene check

Test binary: sleigh_decomp_test — wraps Ghidra's own test suite. Takes -sleighpath for compiled .sla files and a test mode (unittests or datatests).

Architecture

Library Targets

Target Library C++ Std Description
sleigh::sla sla C++11 Core sleigh: disassembly, encoding, p-code, emulation
sleigh::decomp decomp C++11 Full decompiler (superset of sla)
sleigh::support slaSupport C++17 Trail of Bits helpers: FindSpecFile(), version info

Headers: <ghidra/*.hh> for upstream Ghidra headers, <sleigh/*.h> for ToB additions.

Key Directories

  • src/setup-ghidra-source.cmake — Pinned Ghidra versions, FetchContent, source file lists, patch application. This is the central file for version bumps and source management.
  • src/patches/{stable,HEAD}/ — Git-format patches applied to Ghidra source during fetch
  • src/spec_files_{stable,HEAD}.cmake — Lists of ~148 .slaspec files to compile
  • tools/ — Ghidra executables (sleigh compiler, decompiler, ghidra service)
  • support/ — Trail of Bits support library (C++17)
  • extra-tools/sleigh-lift/ — Demo tool for disassembly/p-code lifting
  • cmake/modules/sleighCompile.cmake — sleigh_compile() function exported for downstream users

How Ghidra Source Integration Works

  1. src/setup-ghidra-source.cmake pins a Ghidra git ref (tag for stable, commit hash for HEAD)
  2. CMake FetchContent clones from github.com/NationalSecurityAgency/ghidra
  3. Patches from src/patches/ are applied via git am
  4. Source file lists reference into Ghidra/Features/Decompiler/src/decompile/cpp/
  5. Headers are copied into build/include/ghidra/ for clean include paths

Two Release Tracks

  • stable (default): Pinned to a Ghidra release tag (e.g., Ghidra_12.0.3_build). Shallow clone.
  • HEAD: Pinned to a specific commit on Ghidra main. Full clone. Updated weekly by CI via scripts/update_ghidra_head.py.

Patch System

Patches fix upstream Ghidra bugs (UB sanitizer issues, portability, strict weak ordering violations) without changing Sleigh functionality. They are standard git format-patch files.

  • src/patches/stable/ — Patches for stable release
  • src/patches/HEAD/ — Superset of stable patches plus HEAD-specific fixes
  • Custom patches via: -Dsleigh_ADDITIONAL_PATCHES="path/to/patch1;path/to/patch2"

When adding patches: create with git format-patch, number sequentially, and add to both directories if applicable. Patches in HEAD must be a superset of stable patches.

Key Gotchas

  • In-source builds are forbidden — enforced by cmake/prelude.cmake
  • First configure is slow — Ghidra repo clone takes time (especially HEAD which can't shallow clone)
  • Core libraries are C++11 — the support library and extra tools are C++17, but sleigh::sla and sleigh::decomp must stay C++11
  • Source file lists are manual — when Ghidra adds/removes .cc files, src/setup-ghidra-source.cmake must be updated; the scripts/update_ghidra_head.py script detects new files and flags them
  • Strict weak ordering — a recurring class of upstream bugs in Ghidra comparators; several patches fix these
  • Spec files differ between releases — src/spec_files_stable.cmake and src/spec_files_HEAD.cmake are separate lists and must be maintained independently

CMake Presets Reference

Preset Use Case
ci-ubuntu Linux dev build with warnings and tests
ci-macos macOS dev build
ci-windows Windows dev build (VS 2022, vcpkg)
ci-sanitize ASan + UBSan (builds to build/sanitize/)
ci-coverage Code coverage (builds to build/coverage/)

Code Style

  • .clang-format: BasedOnStyle LLVM
  • Compiler warnings are strict in CI (see flags-unix/flags-windows presets)