Local Development Environment
Relevant source files
The following files were used as context for generating this wiki page:
The Local Development Environment for Quickemu is designed to provide a consistent and reproducible workspace for developers to contribute to the project. It leverages Nix-based tooling to manage dependencies and provides a suite of Bash-based utilities for VM creation, ISO management, and system diagnostics. The environment is optimized for testing nearly 1000 operating system editions across Linux and macOS hosts.
Sources: AGENTS.md:3-13, README.md:20-25
Environment Setup and Tooling
Quickemu utilizes Nix to manage its development shell, ensuring that all contributors have the exact versions of required tools. The environment includes patches for specific paths like OVMF and Samba to facilitate testing within a controlled directory structure.
Nix Development Shell
The primary way to enter the development environment is via Nix commands. This setup configures the environment to use store paths and updates local binaries for immediate testing.
nix develop # Enter devshell with all dependencies
direnv reload # Update .direnv/bin/quickemu for testing
Sources: AGENTS.md:15-18
Core Components
The repository is structured around several Bash scripts, each serving a distinct purpose in the development and runtime lifecycle:
| Component | Description |
|---|---|
quickemu | Main VM launcher script that automates hardware detection and optimization. |
quickget | OS downloader and configuration generator for VM setup. |
quickreport | System diagnostics tool used for troubleshooting and reporting. |
chunkcheck | Utility for verifying the integrity of downloaded files. |
flake.nix | Defines the Nix flake for project packaging and environment management. |
Sources: AGENTS.md:5-13
Development Workflow and Standards
The development workflow is governed by strict coding standards and automated linting to maintain the integrity of the Bash scripts.
Coding Standards
All scripts must be compatible with Bash 4.0+ and comply with ShellCheck. The project maintains specific indentation rules for its primary scripts:
- quickemu: 2 spaces
- quickget: 4 spaces
General conventions include UTF-8 encoding, LF line endings, and the use of the function name() { syntax.
Sources: AGENTS.md:30-41
Testing and Validation
Developers are required to validate their changes locally using provided test commands. This includes linting with ShellCheck and verifying quickget functionality for different architectures.
The diagram shows the standard progression from local modification to PR submission, highlighting the specific validation steps required.
Sources: AGENTS.md:20-28, CONTRIBUTING.md:10-14
Contribution and CI Integration
Quickemu follows the Conventional Commits specification for all contributions. Pull requests (PRs) trigger a series of automated CI workflows to ensure code quality and functional reliability.
Commit and PR Requirements
- Format:
type(scope): description(e.g.,feat(quickget): add new OS). - Guidelines: PR titles must match the commit format; single-commit PRs must have matching titles and messages.
- Validation: CI enforces Conventional Commits and runs ShellCheck with a severity level of "warning".
Sources: AGENTS.md:54-66, CONTRIBUTING.md:12-13
CI Pipeline Overview
The CI environment replicates the local development checks to ensure stability across platforms.
| Workflow | Purpose |
|---|---|
lint-shellcheck | Executes ShellCheck on all PRs. |
lint-pr | Validates Conventional Commits in PR titles. |
test-quickget | Verifies the functionality of the OS downloader. |
test-build-quickemu | Ensures the main launcher builds and runs correctly. |
flake-checker | Validates the Nix flake configuration. |
Sources: AGENTS.md:73-79
Platform and Dependency Requirements
The development environment must account for cross-platform support and a specific list of runtime dependencies.
The diagram illustrates the relationship between the host environment, required tools, and the firmware needed for different guest architectures.
Sources: AGENTS.md:81-91, README.md:27-31
Dependency List
- Runtime:
qemu,cdrtools,curl,jq,spice-gtk,swtpm,samba,zsync. - Linux Specifics:
usbutils,mesa-demos, and EFI firmware (OVMF/AAVMF). - Bash: Version 4.0 or higher is mandatory, with runtime checks enforced.
Sources: AGENTS.md:89-94
Security and Community Standards
Developers must adhere to the Contributor Covenant Code of Conduct, promoting an inclusive environment. Security vulnerabilities discovered during development should be reported via the GitHub Issues interface by selecting the "Report a vulnerability" option.
Sources: CODE_OF_CONDUCT.md:3-15, SECURITY.md:11-15
The Quickemu local development environment provides a robust framework for managing the complexity of emulating a vast array of operating systems while maintaining high code quality through Nix-based automation and standardized Bash scripting practices.