 |
FlatImage
A configurable Linux containerization system
|
|
FlatImage
A configurable Linux containerization system
|
This section provides an organized overview of all headers grouped by functionality. Click on the header links to view detailed API documentation.
src/config.hpp - Global configuration structures and distribution enums. Defines Flatimage with all runtime paths, metadata, and build information.src/common.hpp - Common includes, type aliases, and shared utilities used across the codebase. Single point of inclusion for standard library headers.src/macro.hpp - Preprocessor macros for compile-time configuration and code generation. Includes helper macros for error handling and debugging.src/boot/relocate.hpp - Executable self-relocation and extraction. Handles copying the FlatImage binary to runtime directories and extracting embedded tools.The reserved space is a block within the ELF binary that stores persistent configuration. This allows FlatImage to be self-contained with all settings embedded in the executable itself, surviving file moves and copies. The file reserved/reserved.hpp provides low-level read/write functions for reserved space access. Provides read() and write() primitives that all other reserved handlers use.
FlatImage supports 4 different filesystem strategies that can be selected at runtime via fim-overlay command or FIM_OVERLAY environment variable.
filesystems/filesystem.hpp - Abstract base class defining the filesystem interface. All filesystem implementations inherit from this and implement mount() and destructor for automatic unmounting. Provides RAII semantics for mount lifecycle.filesystems/controller.hpp - Orchestrates the complete filesystem stack.filesystems/overlayfs.hpp - OverlayFS (fuse-overlayfs): Kernel-like overlay via FUSE.filesystems/unionfs.hpp - UnionFS (unionfs-fuse): Pure FUSE union filesystem.BWRAP Native (implemented in controller): Bubblewrap's built-in overlay capability.filesystems/dwarfs.hpp - DwarFS: Compressed read-only filesystem for base layers.filesystems/ciopfs.hpp - CIOPFS: Case-insensitive overlay filesystem.filesystems/utils.hpp - Filesystem utilities. Provides utility functions for managing instances and layers.bwrap/bwrap.hpp - Bubblewrap wrapper with AppArmor support. Provides process isolation primitives including namespace setup, mount configuration, UID/GID mapping, and AppArmor profile application. Builds bubblewrap command-line arguments from permission bitmask. Implements 15 permission types (home, network, audio, GPU, etc.) as bind mount collections.parser/parser.hpp - Command-line argument parser. Tokenizes arguments and routes to command handlers. Uses a registry pattern for command registration. Supports both direct execution (fim-exec, fim-root) and configuration commands (fim-boot, fim-env).parser/interface.hpp - Abstract command interface that all command implementations must follow. Defines the contract for command execution and help text generation.parser/executor.hpp - Command executor. Manages command lifecycle and filesystem setup before execution. Handles the transition from parsing to actual command execution, including environment preparation and cleanup.All commands are implemented in parser/cmd/ and follow a consistent pattern:
parser/cmd/help.hpp - Help system. Generates usage documentation for all commands. Includes examples, arguments, and notes. Uses HelpEntry builder pattern for formatting.parser/cmd/bind.hpp - Bind mount management (fim-bind). Add/delete/list host path bindings (ro, rw, dev types). Stores configuration in reserved space (1 MiB JSON).parser/cmd/desktop.hpp - Desktop integration (fim-desktop). Setup menu entries, MIME types, and icons. Generates XDG-compliant .desktop files and icon sets. Supports entry, mimetype, and icon integrations. Paths auto-update on binary relocation.parser/cmd/icon.hpp - Icon processing. Handles PNG/JPG/SVG icon scaling to multiple sizes (16x16, 32x32, 48x48, 64x64, 96x96, 128x128, 256x256). Integrates with desktop integration system for hicolor icon theme installation.parser/cmd/layers.hpp - Filesystem layer management (fim-layer). Create compressed DwarFS layers, commit changes, and append layers to the FlatImage binary. Uses mkdwarfs with configurable compression levels (0-9). Layers are stacked with newest taking precedence.parser/cmd/recipe.hpp - Package recipe system (fim-recipe, fim-remote). Fetch and install curated package sets with recursive dependency resolution. Supports distribution-specific package managers (apk for Alpine, pacman for Arch). Includes cycle detection and local caching.The portal provides FIFO-based inter-process communication between FlatImage instances and between containers and the host system.
portal/portal.hpp - Portal daemon (host-side). Manages FIFO creation, process spawning, and output redirection. Runs on the host and accepts commands from containers via named pipes. Handles instance registration and command routing.portal/child.hpp - Portal child process handler. Manages individual command execution within the portal system. Creates child processes with redirected stdout/stderr to FIFOs. Handles process lifecycle and cleanup.portal/config.hpp - Portal configuration file.portal/fifo.hpp - FIFO (named pipe) utilities. Low-level FIFO creation, read, write, and cleanup operations. Handles non-blocking I/O and error conditions.db/portal/daemon.hpp - Portal daemon database. Manages daemon-side state, logging, and process tracking. Handles background portal service operations and lifecycle.db/portal/dispatcher.hpp - Command dispatcher. Routes portal commands between containers and host system. Handles message queuing and command ordering.db/portal/message.hpp - Portal message format and serialization. Defines the message protocol for IPC communication, including encoding/decoding of portal commands.The runtime database stores FlatImage component configurations. These configuration are stored in the binary and immutable unless explicitly changed through FlatImage's configuration commands.
db/db.hpp - Main database interface. Provides database CRUD operations.db/env.hpp - Runtime environment variable storage.db/bind.hpp - Runtime bind mount tracking.db/boot.hpp - Stores the current default boot command.db/desktop.hpp - Runtime desktop integration state.db/recipe.hpp - Parse recipes from external recipe files.db/remote.hpp - Store the remote URL.| Feature | Reserved Space | Runtime Database |
|---|---|---|
| Persistence | Permanent (in ELF) | Session only |
| Location | FlatImage binary | Runtime directories |
| Size | 4 MB total | No fixed limit |
| Purpose | Configuration | Transient state |
| Survives moves | ✅ Yes | ❌ No |
Reusable utility modules used throughout the codebase.
lib/log.hpp - Thread-safe logging with fork safety. Uses thread_local storage and pthread_atfork() to handle multi-threading and process forking correctly. Supports 5 log levels (DEBUG, INFO, WARN, ERROR, CRITICAL) with compile-time dispatch. Automatic file/line capture, sink file support, and format string utilities.lib/subprocess.hpp - Process execution utilities. Spawns child processes with proper error handling, output capture, and timeout support. Provides both synchronous and asynchronous execution modes. Includes pipe management for stdin/stdout/stderr redirection.lib/subprocess/pipe.hpp - Pipe creation and management for subprocess communication. Handles data forwarding between the parent and the child.lib/linux.hpp - Linux syscall wrappers and OS-specific utilities. Includes mount/umount wrappers, namespace operations, and low-level system calls not exposed by C++ standard library.lib/env.hpp - Environment variable manipulation. Utilities for getting, setting, and unsetting environment variables with proper error handling. Supports variable expansion and substitution.lib/elf.hpp - ELF binary parsing and manipulation. Reads ELF headers, sections, and symbols. Used for locating the reserved space offset and patching binaries. Implements ELF64 format support for reading FlatImage metadata.lib/fuse.hpp - FUSE filesystem utilities. Detection of FUSE filesystems, mounting, unmounting, and status checking. Includes fusermount wrapper for proper FUSE cleanup.lib/image.hpp - Image processing (PNG/JPG). Resizes icons to multiple standard sizes for desktop integration. Uses libturbojpeg (JPEG) and libpng (PNG) for efficient encoding/decoding.C++ standard library supplements and utilities.
std/expected.hpp - std::expected<T, E> implementation (Rust-like Result type). Provides explicit error handling without exceptions. Used throughout FlatImage for functions that can fail. Includes monadic operations (and_then, or_else, transform).std/concept.hpp - Concept definitions for template constraints. Includes concepts for string representability, iterability, and other type requirements.std/enum.hpp - Enum class wrapper including string conversion, iteration, and reflection.std/string.hpp - String manipulation utilities. Includes static_string for compile-time strings and additional string utility functions.std/vector.hpp - Vector utilities including range operations, transformations, and vector-specific algorithms. Supplements std::vector with convenience methods.std/filesystem.hpp - Filesystem path utilities and extensions. Wraps std::filesystem with additional helpers for common path operations. 
1.13.2