Home /Modules/decompiler/API.md

API.md

decompiler/API.md · 151 line(s) · markdown

Slecompiler™ API Guide

Max Rupplin - MEARVK LLC - 2026

Slecompiler™ exposes a C++ analysis library under decompiler/. The API follows a read-only static-analysis pipeline:

artifact
  -> container identification
  -> format/metadata decoding
  -> symbols and sections
  -> instruction decoding
  -> control-flow analysis
  -> SLIR
  -> higher-level analysis
  -> library relationships / report

Product boundary

Slecompiler is an analysis product, not an execution sandbox. Opening or decoding an artifact does not imply permission to execute it. The default product path does not load kernel modules, perform device I/O, write target memory, or invoke recovered code.

Supported artifact families include ELF, PE/COFF, Mach-O where implemented, GNU/static archives, relocatable objects, kernel modules as static evidence, and raw/firmware artifacts.

API concepts

ConceptResponsibility
ArtifactInput native artifact and identity/container information
DecoderNative-byte decoding into structured evidence
ELF / PE supportFormat-specific headers, sections, symbols, and relocation metadata
ArchiveStatic-library container and object members
LibraryLibrary/family model for related native artifacts
AnalyzerHigher-level static analysis
SLIRLifted intermediate representation
VMAnalysis-oriented representation/execution model; it does not execute the input artifact

The exact C++ declarations remain authoritative in decompiler/include/. This guide documents the contract without inventing declarations that are not yet stabilized.

API exemplars

With SLEE_LA_BUILD_API_EXAMPLES=ON (the current CMake default), the product builds:

Their sources are under decompiler/examples/.

They demonstrate:

  1. artifact identity and metadata inspection;
  2. decoding and control-flow analysis;
  3. library/archive metadata;
  4. library-family dependency relationships;
  5. SLIR and analysis-VM work.
  1. Accept an input path under the caller's authorization policy.
  2. Open the artifact without executing it.
  3. Identify its container and format.
  4. Collect metadata and provenance.
  5. Decode the structures needed for the requested analysis.
  6. Recover functions/control flow where supported.
  7. Lift supported material into SLIR.
  8. Run higher-level analysis.
  9. Emit an evidence-based report.
  10. Keep original input separate from generated analysis output.

Reports should distinguish observed evidence, derived analysis, and unknown/unsupported properties. Never invent symbols, source lines, calling conventions, or hardware facts.

Normal analysis limitations

Unknown formats, truncated files, malformed headers, unsupported architectures, stripped symbols, unresolved indirect control flow, unsupported instructions, missing dependencies, and undecodable archive members are normal analysis outcomes. An unrecovered fact should remain explicitly unknown.

Platform contract

The product targets Linux, macOS, and Windows 10+. The native library is C++20. Platform-specific build mechanics belong in build/; the analysis contract remains in decompiler/.

See decompiler/TUTORIAL.md for the developer walkthrough.

Source output targets

Slecompiler supports explicit source-language selection for decompilation. The CLI argument is:

sleela-decompiler decompile <file> --output <java|sleela|c|c++>

The output may be written to standard output or to a file:

sleela-decompiler decompile program --output java sleela-decompiler decompile program --output sleela --file decompiled.sleela sleela-decompiler decompile program --output c --file decompiled.c sleela-decompiler decompile program --output c++ --file decompiled.cpp

Accepted aliases are sl for Sleela and cpp for C++. The source emitter is language-selected after native decoding, CFG recovery, and function recovery.

The four supported source targets are:

TargetTypical extensionPurpose
Java.javaObject-oriented JVM-oriented source reconstruction
Sleela.sleelaNative SLeeLa/Sleela source representation
C.cProcedural C-oriented reconstruction
C++.cppC++20-oriented reconstruction

Generated source is evidence-derived. It must not be represented as the original source unless the evidence actually establishes that equivalence. Missing or ambiguous native semantics remain explicitly represented as comments/unknowns rather than invented source behavior.

Shared C/C++ class model

The repository now includes api/sleela/2.1/include/sleela/api.hpp, with the corresponding translation unit in api/sleela/2.1/src/api.cpp. This public C++20 API provides the shared semantic model used by planned C and C++ reconstruction.

The model includes Type, Field, Variable, and FunctionSignature for reusable type/signature information; CallingConvention and Method for ABI and function evidence; CStruct, CUnion, and CEnum for C declarations; CppClass and CppNamespace for C++ class and namespace reconstruction; vtable-address and RTTI evidence on CppClass; Artifact, Address, Instruction, BasicBlock, and ControlFlowGraph for native-analysis context; ReconstructionUnit as the language-neutral collection consumed by source backends; and Provenance and EvidenceKind so recovered declarations can distinguish observed, decoded, derived, inferred, hypothesized, unknown, unsupported, and conflicting information.

This is an API foundation rather than a claim that every construct can already be recovered from every binary. The decompiler must populate these objects from actual analysis evidence and preserve uncertainty.

SLeeLa syntax 3.1 source target

The SLeeLa source-output target is aligned with the normative syntax 3.1 edition. The compiler gate accepts declared source syntax 1.0–3.1. When reconstructing SLeeLa, the decompiler should preserve a known original source version when evidence supports it; otherwise it must label the selected target version explicitly and avoid claiming that reconstructed source is byte-for-byte or semantically identical to the original. Syntax 3.0 does not make unsupported instructions, source constructs, or native behavior recoverable.

Normative grammar: SLEELA.syntax. Generated standard-library API: docs/api/index.html.