How iseki0/executables works
Main Components
• Library Core:
• Common Module: Contains shared code for file access, data abstraction, exception definitions, common utilities, and format detection (this is visible in packages like space.iseki.executables.common and share).
• Format-Specific Module(s):
• PE Parser: Contains classes and functions to parse COFF headers, optional headers, version information, and resource data.
• ELF Parser: Contains the logic to parse ELF headers, section headers, symbol tables, etc.
• Macho Parser: Contains the implementation for reading Macho file information.
• Platform-Specific/Binary Adaptors:
• Separate targets for JVM, mingwX64, Native, and nonJvm components (visible in directories: src/jvmMain, src/mingwX64Main, src/nativeFileSupportedMain, etc.). These adapt the core library functionality for different runtime environments or file-access APIs.
• Build & Dev Infrastructure:
• Gradle scripts and buildSrc modules (build.gradle.kts files, settings.gradle.kts) that manage building, testing, and publishing. Also shown is GitHub Actions workflows for continuous integration.
• Tests:
• Organized under commonTest, jvmTest, mingwX64Test, etc. to validate each module and platform-specific behavior.
Relationships and Data Flow
• External Client/Application: An external user or application calls the library’s public API (for example, using functions like PEFile.open() or ELFFile.open()).
• File Format Detection: The public API likely first invokes utilities in the “common” module to detect the file format (using FileFormat.detect()). Based on the detected format, it routes the processing to the appropriate parser.
• Format-Specific Processing: After detection, control passes to one of the format-specific components (PE, ELF, or Macho parser). These components further call into submodules that handle reading headers, sections, symbol tables, and other details.
• Platform Abstraction Layer: Depending on the running target (JVM, native, etc.), platform-specific code (in directories like jvmMain, mingwX64Main, etc.) ensures proper file I/O and data access.
• Exception and Logging: Exception handling components in the common module manage errors during parsing. This error handling flows upward to the clients.
Architectural Patterns
• Separation of Concerns: Clear modularity between shared logic (common) and format-specific implementations.
• Multiplatform Abstraction: Using Kotlin Multiplatform to factor out common code while providing specific implementations for different targets.
• API Facade: The public APIs (e.g., PEFile, ELFFile, etc.) serve as facades, encapsulating lower-level parsing logic.
Technologies and Tools
• Kotlin Multiplatform and Gradle (as build system)
• GitHub Actions (CI workflows; see .github/workflows)
• Testing Frameworks as seen in the test directories
• Serialization (Kotlinx.serialization used in the samples)
• Maven Central (for dependency distribution)
Elements
• External Client / Application
• API Facade (public functions like PEFile.open, ELFFile.open, etc.)
• File Format Detector (common utilities)
• Format Parsers: PE Parser, ELF Parser, Macho Parser
• Common Utilities & Exception Handling Module
• Platform-Specific Adapters (JVM adapter, Native adapter, etc.)
• Build & CI Infrastructure (optional, to illustrate overall project maintenance)
• From the external client to the API Facade
• From the API Facade to the File Format Detector, and then branching out to the appropriate format parser
• Core library modules versus platform-specific modules
• Public API layers versus internal logic
• Annotations where necessary that call out important architectural patterns like “Separation of Concerns” and “Platform Abstraction.”
Final Advice
• Every component is clearly labeled, grouping submodules appropriately (e.g., grouping the many “files/src/commonMain/kotlin/space/iseki/executables/…” into a single “Executables Core” module with internally labeled subcomponents like “ELF”, “PE”, “Macho”).
• Small notations regarding tools (like Gradle) and CI (like GitHub Action).
Happy diagramming!