System Architecture & QEMU Wrapper
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu is a sophisticated Bash-based wrapper for QEMU (Quick Emulator) designed to simplify the creation and management of virtual machines across Linux and macOS hosts. Its primary architecture focuses on automating complex hardware detection and configuration, allowing users to run optimized VMs for nearly 1000 operating system editions without requiring deep technical knowledge of QEMU's exhaustive command-line options.
The system is split into two primary functional components: quickget, which handles the acquisition of assets and initial configuration generation, and quickemu, which serves as the runtime engine that executes the VM with hardware-optimized parameters.
Sources: README.md:15-22, AGENTS.md:3-6
Core Components and Tools
The project architecture is composed of several Bash scripts, each serving a distinct role in the VM lifecycle.
| Component | Language | Primary Purpose |
|---|---|---|
quickemu | Bash 4.0+ | Main VM launcher; handles hardware detection and QEMU execution. |
quickget | Bash 4.0+ | OS downloader and configuration file generator. |
quickreport | Bash 4.0+ | System diagnostics utility for troubleshooting. |
chunkcheck | Bash 4.0+ | Utility for verifying the integrity of downloaded files. |
Sources: AGENTS.md:8-16, AGENTS.md:58-58
The Workflow Architecture
The relationship between these components follows a linear data flow from asset acquisition to virtual machine execution.
This diagram illustrates the progression from user request to a running guest operating system.
Sources: README.md:59-75, AGENTS.md:10-12
Functional Logic: Quickget vs. Quickemu
Asset Management (quickget)
quickget operates as the entry point for the system. It contains the definitions for supported operating systems and the logic required to fetch them.
- OS Definitions: OS information is managed via a large
os_info()case statement. - Dynamic Dispatch: The script uses dynamic dispatch to invoke functions specific to a distribution, such as
releases_<os>(),editions_<os>(), andarch_<os>(). - Configuration Generation: Once the download is complete, it produces a
.conffile that defines the virtual machine's basic parameters.
Sources: AGENTS.md:65-74, README.md:19-20
Runtime Optimization (quickemu)
quickemu acts as the intelligent wrapper that translates the high-level configuration into specific QEMU arguments.
- Hardware Detection: It enumerates host hardware to determine the best acceleration methods (e.g., KVM for Linux).
- Guest Support: It manages specialized requirements for different architectures, such as using AAVMF firmware and the
virtmachine type for ARM64 guests. - Feature Integration: It automatically configures advanced features including SPICE support, VirtIO file sharing (webdavd or 9p), and Samba integration if available on the host.
Sources: README.md:21-22, README.md:31-48, AGENTS.md:103-106
System Integration and Dependencies
Quickemu relies on a specific set of runtime dependencies to provide a full-featured virtualization experience.
Host and Guest Matrix
| Layer | Supported Platforms / Features |
|---|---|
| Hosts | Linux (x86_64, aarch64), macOS (x86_64, aarch64) |
| Guests | Windows (10/11, Server), macOS (Sequoia to Mojave), Linux, BSDs, FreeDOS |
| Firmware | EFI (with/without SecureBoot), Legacy BIOS, OVMF, AAVMF |
| Emulation | TCG (for cross-architecture without KVM) |
Sources: README.md:27-39, AGENTS.md:100-107
Connectivity and Interaction
The architecture facilitates interaction between the host and guest through several protocols:
This sequence shows how Quickemu initializes the environment and facilitates host-guest communication.
Sources: README.md:31-48, AGENTS.md:10-12
Development and Maintenance
The project uses a Nix-based development environment to ensure consistency across different host systems. The flake.nix and package.nix files define the packaging, while devshell.nix provides a patched version of Quickemu that uses Nix store paths for critical components like OVMF and Samba.
Code Standards
- Compliance: All scripts must be ShellCheck compliant (Severity: warning).
- Style: Functions use the
function name() {syntax.quickemuuses 2-space indentation, whilequickgetuses 4-space indentation. - Contributions: Changes follow the Conventional Commits specification, with specific prefixes for
quickgetandquickemuto categorize fixes and features.
Sources: AGENTS.md:13-16, AGENTS.md:23-26, AGENTS.md:60-63, CONTRIBUTING.md:10-10
Security and Versioning
Quickemu maintains a security policy focusing on the most recent versions. Vulnerabilities are reported via GitHub Issues, and the project is maintained on a "best-efforts" basis.
| Version | Support Status |
|---|---|
| 4.9.x | Supported |
| < 4.8 | Unsupported |
Sources: SECURITY.md:5-15
Quickemu's architecture transforms QEMU from a complex command-line tool into a streamlined system for rapid deployment of virtualized environments, balancing ease of use with deep hardware-level optimization.