# intoli/exodus architecture

> Architecture diagram of the GitHub repository intoli/exodus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/intoli/exodus
- Repository: https://github.com/intoli/exodus

## Overview

Based on our analysis of the file tree and README, Exodus is a Python-based command-line tool designed to “relocate” Linux ELF binaries by bundling them together with all their runtime dependencies. In other words, the tool detects a binary’s shared library requirements, collects these files (and optionally extra files specified by the user), and then creates a bundle that includes a specially generated launcher (either a compiled binary or a shell script) that correctly sets up the runtime environment for the relocated executable.

##### Main Components
- Command-Line Interface (CLI):
- The entry point is the CLI (src/exodus_bundler/cli.py) which parses input arguments (binaries to bundle, extra files, and options like --detect or --tarball).
- Bundling/Packaging Engine:
- The “bundling” module (src/exodus_bundler/bundling.py) orchestrates collecting the target binary and its runtime dependencies.
- Dependency Detection:
- The dependency_detection.py module identifies all shared libraries by invoking the dynamic linker (using LD_TRACE_LOADED_OBJECTS) and maybe by leveraging additional data (like strace outputs when requested).
- Input Parsing:
- The input_parsing.py module helps interpret user arguments (files, renames, and additional files to include).
- Templating & Launcher Generation:
- The templating.py module and the templates folder are responsible for generating the launcher scripts or even compiling a small statically linked launcher (by interfacing with gcc and libraries like musl or diet libc if available). The launcher handles overriding the hardcoded RPATH/linker path so that the bundled binary executes using the bundled dependencies.
- Output Bundling:
- The final product is either a self-extracting installation script or a tarball (if the --tarball flag is provided). The bundle is organized into the “bin”, “bundles”, and “data” directories. “data” holds actual file assets (named by SHA-256 hash), “bundles” mirrors the original filesystem structure via symlinks, and “bin” provides user-friendly entry point symlinks.

##### Interactions and Data Flow
- The CLI then passes the request to the bundling engine.
- The dependency detection module is called next to analyze the binary and, if necessary, extra files provided (including possibly through an automatic detection via the system package manager or using strace output).
- The templating module constructs the launcher(s) with necessary parameters (setting library search paths and the relocated linker).
- The bundler then creates the bundled directory structure (data, bundles, bin) and populates it with symlinks to actual files, using hashed names to prevent conflicts.
- Finally, the output is either emitted directly (for piping into an SSH process) or written to a tarball file.

##### Architectural Patterns and Technologies
- Modular Structure – Separation between CLI, dependency detection, launchers generation, and output bundling shows a clear separation of concerns.
- Template-Based Code Generation – The templating strategy is used to generate both shell-script and compiled launcher binaries.
- Integration of Native Tools – The tool interfaces with system utilities (ld-linux, strace) and optionally uses GCC and alternative libc implementations.
- Test Suite – The “tests” directory emphasizes an automated test setup using pytest and tox, which supports good development practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Input"]:::user
    CLI["exodus CLI (cli.py)"]:::cli
    ENG["Bundling Engine (bundling.py)"]:::engine
    DEP["Dependency Detection (dependency_detection.py)"]:::module
    INP["Input Parsing (input_parsing.py)"]:::module
    TEMP["Templating (templating.py)"]:::module
    TEMP_DIR["Launcher Templates (templates)"]:::templating
    OUTPUT["Output Bundling Structure<br/>(bin, bundles, data)"]:::output
    SYS["System Tools<br/>(ld-linux, gcc, strace, musl/diet libc)"]:::external
    TS["Test Suite (pytest, tox)"]:::test

    U -->|"invokes"| CLI
    CLI -->|"passes request to"| ENG
    ENG -->|"triggers dependency detection"| DEP
    ENG -->|"parses inputs"| INP
    ENG -->|"invokes launcher generation"| TEMP
    TEMP -->|"uses templates from"| TEMP_DIR
    ENG -->|"creates bundled structure"| OUTPUT
    DEP -->|"invokes"| SYS
    TEMP -->|"compiles launcher via"| SYS
    ENG -->|"validated by"| TS

    click CLI "https://github.com/intoli/exodus/blob/master/src/exodus_bundler/cli.py"
    click ENG "https://github.com/intoli/exodus/blob/master/src/exodus_bundler/bundling.py"
    click DEP "https://github.com/intoli/exodus/blob/master/src/exodus_bundler/dependency_detection.py"
    click INP "https://github.com/intoli/exodus/blob/master/src/exodus_bundler/input_parsing.py"
    click TEMP "https://github.com/intoli/exodus/blob/master/src/exodus_bundler/templating.py"
    click TEMP_DIR "https://github.com/intoli/exodus/tree/master/src/exodus_bundler/templates"

    classDef user fill:#ffebcc,stroke:#333,stroke-width:2px;
    classDef cli fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef engine fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef module fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef templating fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef output fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ffccd5,stroke:#333,stroke-width:2px;
    classDef test fill:#d1ffd1,stroke:#333,stroke-width:2px;

    linkStyle 0 stroke:#0000ff,stroke-width:2px;
    linkStyle 1 stroke:#0000ff,stroke-width:2px;
    linkStyle 2 stroke:#00aa00,stroke-width:2px;
    linkStyle 3 stroke:#00aa00,stroke-width:2px;
    linkStyle 4 stroke:#00aa00,stroke-width:2px;
    linkStyle 5 stroke:#00aa00,stroke-width:2px;
    linkStyle 6 stroke:#0000ff,stroke-width:2px;
    linkStyle 7 stroke:#ff0000,stroke-width:2px;
    linkStyle 8 stroke:#ff0000,stroke-width:2px;
    linkStyle 9 stroke:#800080,stroke-width:2px;
```
