Adding a New OS to quickget
Relevant source files
The following files were used as context for generating this wiki page:
Quickget is the component of the Quickemu project responsible for automatically downloading upstream operating system ISO images and generating the necessary virtual machine configurations. With support for nearly 1000 operating system editions, quickget acts as the primary entry point for users to provision new virtual machines without manual configuration. Sources: README.md:14-17, README.md:58-61, AGENTS.md:7-7
Adding a new operating system involves extending the Bash-based logic within the quickget script to define how versions, editions, and architectures are discovered and retrieved. This process ensures that quickemu can later launch the VM with optimized settings based on the generated configuration. Sources: AGENTS.md:7-7, AGENTS.md:52-58
Architecture of quickget OS Support
The quickget script is written in Bash 4.0+ and utilizes a dynamic dispatch mechanism to handle various operating systems. To add a new OS, a developer must implement a set of specific functions that follow a naming convention based on the OS name. Sources: AGENTS.md:38-40, AGENTS.md:43-43
Core Components for OS Integration
The integration is divided into metadata definition and download logic. The following table describes the required functional components:
| Component | Purpose | Required |
|---|---|---|
os_info() | A case statement that registers the OS and maps it to internal logic. | Yes |
releases_<os>() | Returns a list of available versions/releases for the OS. | Yes |
editions_<os>() | Returns available editions (e.g., Desktop, Server, XFCE) if applicable. | Optional |
arch_<os>() | Defines supported architectures (e.g., amd64, arm64). | Optional |
| Download Logic | Logic to construct the URL and fetch the ISO, often using curl or zsync. | Yes |
Sources: AGENTS.md:52-58, AGENTS.md:113-113
OS Registration Flow
The following diagram illustrates how quickget processes a request to add or check an OS, moving from the initial user command through the internal function dispatch.
A flowchart showing the logical progression of functions called within quickget when processing an OS. Sources: AGENTS.md:52-58, README.md:83-85
Implementation Requirements
1. Function Definitions
Each OS requires a series of functions within the quickget script. For an operating system named exampleos, the following structure is typical:
releases_exampleos(): This function must output the version strings supported by the downloader.arch_exampleos(): If the OS supports ARM64, this function is required. If omitted, the system defaults toamd64.- Dynamic Dispatch: Many functions are invoked indirectly. Note that
SC2317(unreachable code) is disabled in ShellCheck forquickgetbecause of this architecture.
Sources: AGENTS.md:43-43, AGENTS.md:52-58
2. Configuration Generation
quickget does not just download the ISO; it also creates a .conf file. This file is used by quickemu to determine hardware optimization, such as UEFI (OVMF/AAVMF) requirements or specific machine types like virt for ARM64 guests. Sources: AGENTS.md:7-7, AGENTS.md:105-107
Testing and Quality Assurance
Before submitting a Pull Request to add a new OS, the implementation must be verified using the built-in check flags in quickget.
| Command | Purpose |
|---|---|
./quickget --check <os> [rel] [ed] | Verifies the download URL for a specific release/edition. |
./quickget --arch arm64 --check <os> | Verifies ARM64 specific download paths. |
./quickget --check-all-arch <os> | Validates URLs across all supported architectures. |
shellcheck quickget | Ensures the script complies with Bash 4.0+ standards. |
Sources: AGENTS.md:27-32, AGENTS.md:38-38
Development Sequence Diagram
A sequence diagram showing the developer workflow for adding and testing a new OS entry. Sources: AGENTS.md:27-32, AGENTS.md:77-77
Contribution Standards
Contributions must adhere to the project's coding standards and administrative requirements:
- Code Style: Use 4 spaces for indentation in
quickget. The script must be ShellCheck compliant. Sources: AGENTS.md:41-41 - Commit Messages: Must follow Conventional Commits. New OS support should use the
feat(quickget):prefix (e.g.,feat(quickget): add Support for NewOS). Sources: AGENTS.md:60-68 - Licensing and Conduct: All contributors must adhere to the Contributor Covenant Code of Conduct. Sources: CODE_OF_CONDUCT.md:1-5
Summary
Adding a new OS to quickget expands the project's capability to provide "optimized by default" virtual machines. By implementing the required metadata functions and download logic, developers enable automated provisioning for users. The process is strictly governed by ShellCheck linting and the Conventional Commits specification to maintain project health. Sources: README.md:14-17, CONTRIBUTING.md:10-14, AGENTS.md:60-64