System Diagnostics (quickreport & chunkcheck)
Relevant source files
The following files were used as context for generating this wiki page:
The Quickemu project includes a suite of Bash-based utilities designed to ensure system compatibility and data integrity. While quickemu and quickget handle the core virtualization and image retrieval tasks, quickreport and chunkcheck serve as the diagnostic backbone of the ecosystem. These tools provide automated system assessments and verification of downloaded assets to maintain a reliable virtualization environment.
quickreport functions as a system diagnostics tool that gathers critical information about the host environment, while chunkcheck acts as a download verification utility to ensure that operating system images retrieved via quickget are intact and valid. Together, they facilitate troubleshooting and quality assurance for the ~1000 operating system editions supported by the project.
Sources: AGENTS.md:7-14, README.md:16-19
Architectural Role and Utility
The diagnostic tools are integrated into the broader Quickemu structure, which relies on Bash 4.0+ and specific hardware detection logic. These utilities are maintained alongside the primary scripts and share the same development standards, including ShellCheck compliance and UTF-8 formatting.
The diagram above illustrates the relationship between core launchers and diagnostic utilities within the Quickemu project structure.
Sources: AGENTS.md:10-23, README.md:65-74
quickreport: System Diagnostics
quickreport is specifically categorized as the system diagnostics tool within the project hierarchy. Its primary purpose is to analyze the host system to ensure it meet the requirements for optimized VM execution.
- Logic: It operates as a Bash script, consistent with the project's architecture.
- Context: It is used to identify issues related to hardware detection or missing dependencies that might prevent
quickemufrom launching VMs with "optimum configuration." - Maintenance: Development involves regular linting via
shellcheck quickreportto maintain code quality.
Sources: AGENTS.md:12, AGENTS.md:27, README.md:18-19
chunkcheck: Download Verification
chunkcheck is the utility responsible for download verification. In a project that supports nearly 1000 operating system editions, ensuring the integrity of large ISO files is critical.
- Integration: It complements
quickgetby providing a mechanism to verify that chunks of a downloaded file are correct. - Dependency: It works in tandem with the project's runtime dependencies such as
curlandzsync, which are used for image retrieval. - Validation: Like other components, it is subject to CI workflows to ensure functionality remains consistent across updates.
Sources: AGENTS.md:13, AGENTS.md:106, README.md:46
Development and Quality Standards
Both diagnostic tools follow the strict development guidelines of the Quickemu project. This ensures that diagnostics are as reliable as the virtualization engine itself.
| Feature | Standard/Requirement |
|---|---|
| Language | Bash 4.0+ |
| Linting | shellcheck (Severity: warning) |
| Formatting | 2-space or 4-space indent, LF line endings |
| Version Control | Conventional Commits |
| CI Validation | lint-shellcheck, test-build-quickemu |
Sources: AGENTS.md:27-46, AGENTS.md:73-82, CONTRIBUTING.md:10-11
Diagnostic Workflow in CI
The diagnostic utilities are part of the automated testing and linting pipelines. This prevents regressions in the reporting and verification logic.
The sequence diagram demonstrates how diagnostic tools are validated during the contribution process to ensure reliable reporting.
Sources: AGENTS.md:89-95, CONTRIBUTING.md:13-14
Dependency and Platform Support
The effectiveness of quickreport and chunkcheck is tied to the host's capabilities. Quickemu supports Linux and macOS hosts (x86_64 and aarch64).
- Runtime Dependencies: These tools rely on a suite of packages including
jqfor JSON processing,curlfor network checks, andzsyncfor chunk-based verification. - Host Specifics: Diagnostics may vary between Linux and macOS; for instance, OVMF/UEFI firmware support is noted as Linux-only, which
quickreportwould likely identify during a system scan.
Sources: AGENTS.md:100-107, README.md:36-37
Summary
quickreport and chunkcheck provide the necessary transparency and verification required for managing a complex virtualization environment. By automating host diagnostics and download integrity checks, they reduce the manual troubleshooting burden on users and maintainers, supporting Quickemu's goal of "quickly" creating and running optimized virtual machines.