soap(1): Small Object Analyser and Pruner 🧼

A terminal user interface (TUI) application for analyzing object files.

Built with Rust and Ratatui.

Features

Multiple Analysis Tabs

• Overview Tab: Displays file information, architecture details, file size statistics, and dynamic linking information
• Sections Tab: Lists all ELF sections with sizes, types, flags, and offsets; sortable by name, size, type, or offset
• Symbols Tab: Lists all symbols with sizes, types, bindings, and addresses; sortable by name, size, type, or binding
• Statistics Tab: Comprehensive size breakdowns with visual charts showing section and symbol distributions
• Suggestions Tab: Actionable optimization suggestions with estimated size savings and risk levels

Core Capabilities

• ELF Metadata: Architecture, endianness, ELF class (32/64-bit), entry point, program/section headers
• Section Analysis:
  • Section types: .text, .data, .bss, .rodata, .rela.*, .debug_*, etc.
  • File size vs memory size
  • Section flags (readable, writable, executable, allocatable)
  • Grouping by type/category
  • Identification of strippable sections
• Symbol Analysis:
  • Symbol types: function, object, file, section
  • Symbol bindings: local, global, weak
  • Symbol visibility
  • Size calculations
  • Exported vs local symbols
• Statistics:
  • Total file size
  • Code size vs data size
  • Debug info size
  • Strippable size
  • Size breakdowns by section category
  • Size breakdowns by symbol type
• Optimization Suggestions:
  • Strip debug symbols
  • Remove unused sections
  • Strip local symbols
  • Link-time optimization recommendations
  • Compression opportunities
  • Each suggestion includes:
    • Description
    • Estimated size savings
    • Command/flag to apply
    • Risk level (low/medium/high)

Installation

Prerequisites

• Rust (latest stable version recommended)
• Cargo

Build

cargo build --release

The binary will be located at target/release/soap.

Usage

./target/release/soap <path-to-object-file>

Or using cargo:

cargo run --release -- <path-to-object-file>

Example:

cargo run --release -- /usr/lib/libc.so.6

Keybindings

General Navigation

• q or Esc: Quit the application
• h or ←: Previous tab
• l or →: Next tab

Scrolling (Sections, Symbols, and Suggestions tabs)

• ↑ or k: Scroll up
• ↓ or j: Scroll down
• Page Up: Scroll up one page
• Page Down: Scroll down one page
• Home: Jump to top
• End: Jump to bottom

Sorting (Sections and Symbols tabs)

• s: Cycle through sort modes (Name → Size → Type → Offset/Binding)
• r: Toggle sort direction (ascending/descending)

Section Detail View (Sections tab)

• Enter: View detailed hex dump of selected section (especially useful for .text section)
• Esc: Exit detail view and return to section list
• In detail view:
  • ↑/k: Scroll hex dump up
  • ↓/j: Scroll hex dump down
  • Page Up/Page Down: Scroll by page

Interactive filtering (Sections and Symbols tabs)

• /: Toggle search mode (filter by name substring)
• f: Open filter menu to filter by section type, symbol type/binding, and size range
• In filter menu: ↑/↓ navigate, Space toggle type/binding, +/- adjust min/max size (when on size row), Tab switch Section/Symbol filters, Enter apply, x clear, Esc cancel

Export

• e (Suggestions tab): Export optimization suggestions to a shell script (soap_suggestions_<basename>.sh)
• E: Export current file data (sections, symbols, stats) to JSON (soap_export_<basename>.json)

Comparison mode (when two files are loaded)

• c: Switch between File A and File B

Tabs Overview

Overview

Shows general information about object files:

• Architecture (x86_64, ARM, etc.)
• ELF class (32-bit/64-bit)
• Endianness
• Entry point address
• Program and section header counts
• Total file size
• Code size, data size, debug size
• Strippable size
• Section and symbol counts
• Dynamic linking information (SONAME, needed libraries)

Sections

Displays all ELF sections with:

• Section name
• Section type (Text, Data, Debug, etc.)
• File size and memory size
• Section flags (R=readable, W=writable, X=executable, A=allocatable)
• File offset and virtual address
• Sortable by name, size, type, or offset
• Detail View: Press Enter on any section to view a detailed hex dump showing:
  • Section header information
  • Hex dump with offsets (16 bytes per line)
  • ASCII representation of the data
  • Particularly useful for inspecting .text section code

Symbols

Displays all symbols with:

• Symbol name
• Symbol type (Function, Object, File, Section)
• Symbol binding (Local, Global, Weak)
• Symbol size
• Virtual address
• Sortable by name, size, type, or binding

Statistics

Comprehensive analysis including:

• Section Breakdown: Size distribution by section type with visual bars
• Symbol Breakdown: Size distribution by symbol type with counts and percentages
• Visual charts showing relative sizes

Suggestions

Optimization recommendations:

• Strip debug symbols: Remove .debug_* sections
• Strip local symbols: Remove local symbols to reduce size
• Remove comment section: Strip .comment section
• Link-time optimization: Recompile with LTO flags
• Remove relocation sections: If not needed for dynamic linking
• Each suggestion shows:
  • Title and description
  • Estimated size savings
  • Command to apply
  • Risk level (color-coded: green=low, yellow=medium, red=high)

Supported formats and features

• Formats: ELF (shared objects, executables), static libraries (.a), WebAssembly, Mach-O, PE/COFF
• ELF: Dynamic section (NEEDED, SONAME, RPATH, RUNPATH), symbol binding/visibility
• Export: CSV/JSON (CLI and TUI), export suggestions to shell script
• Filtering: By section/symbol type, binding, name search, min/max size
• Comparison: Load two files, switch with c, Comparison tab shows size diff and sections/symbols only in A or B

Technical Details

ELF Parsing

soap uses the object crate for parsing ELF files. It extracts:

• ELF header information
• Program headers (segments)
• Section headers
• Symbol tables (.symtab and .dynsym)
• Dynamic linking information

Section Types

Recognized section types:

• Text: Executable code (.text)
• Data: Initialized data (.data)
• BSS: Uninitialized data (.bss)
• Rodata: Read-only data (.rodata)
• Relocation: Relocation tables (.rela.*, .rel.*)
• Debug: Debug information (.debug_*)
• Dynamic: Dynamic linking information (.dynamic)
• StringTable: String tables (.strtab, .dynstr)
• SymbolTable: Symbol tables (.symtab, .dynsym)
• Note: Note sections (.note.*)

Symbol Analysis

Symbols are classified by:

• Type: Function, Object, File, Section
• Binding: Local, Global, Weak
• Visibility: Default, Hidden, Protected, Internal

Examples

Analyzing a system library

soap /usr/lib/libc.so.6

Analyzing a custom library

soap target/release/libmylib.so

CLI export (no TUI)

Export without starting the TUI:

soap --export csv [--output base] <file>     # Writes base_sections.csv and base_symbols.csv (or stdout)
soap --export json [--output path] <file>   # Writes full JSON (sections, symbols, stats)
soap --export-suggestions [output.sh] <file> # Writes shell script with optimization commands

Limitations

• Some advanced ELF features may not be fully parsed
• WebAssembly: section sizes for type/import/export are not shown; code and data sizes are computed
• Thin archives (.a with external member references) are skipped

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.

Contributing

See CONTRIBUTING.md for guidelines on contributing to this project.