This provides basic instructions for building QEMU. Tested-by: Chao Liu <[email protected]> Signed-off-by: Alex Bennée <[email protected]>
--- v3 - add builds to gitignore v2 - drop ECA/qemu-helper-agent sub-agent language - mention configure --help - drop mention of full paths - not needed for compilation - moved earlier is series so code-reviewer can refer to it --- .agents/skills/qemu-build/SKILL.md | 50 ++++++++++++++++++++++++++++++ .gitignore | 1 + AGENTS.md | 1 + 3 files changed, 52 insertions(+) create mode 100644 .agents/skills/qemu-build/SKILL.md diff --git a/.agents/skills/qemu-build/SKILL.md b/.agents/skills/qemu-build/SKILL.md new file mode 100644 index 00000000000..91819a0992a --- /dev/null +++ b/.agents/skills/qemu-build/SKILL.md @@ -0,0 +1,50 @@ +--- +name: qemu-build +description: Provides step-by-step instructions on configuring and building QEMU. You MUST trigger this skill whenever the user asks to build QEMU or debug build failures. It includes critical details on build directory reuse and spawning sub-agents. +license: GPL-2.0-or-later +--- + +# Instructions + +## Examining and Re-using Build Directories +Before creating a new build directory, check if an existing one can be re-used. QEMU uses out-of-tree builds, typically in `build` or `builds/` sub-directories. + +1. **Check existing configs**: You can examine how an existing build directory was configured by checking its `config.log`. Run `head -n 2 builds/<dir>/config.log`. The second line typically contains the full `../configure` command line used. +2. **Re-use and Reconfigure**: You have latitude to re-use existing directories when appropriate (e.g., `builds/debug` which is a general-purpose debug directory for whatever is currently going on). If an existing directory has the right flags (like debug/sanitizers) but the wrong target list, you can reconfigure it to keep the same config but change the `--target-list`: + ```bash + cd builds/debug + # Check the old config.log, then re-run configure with the new target-list + ../../configure <old-flags> --target-list=<new-targets> + ``` + +## Launching Builds +**Crucial**: You MUST NEVER run builds directly in the main agent context. You MUST ALWAYS launch them by spawning a sub-agent. +Pass the specific build commands, along with the required working directory, in the `task` argument. Give the subagent explicit instructions on what to verify and what to report back to you. +For example: `task: "Navigate to builds/debug and run ninja. If it fails, report the exact compiler errors."` + +## Configuring a New Build +If no suitable build directory exists, create a new one. + +1. **Create build directory**: `mkdir -p builds/test-target; cd builds/test-target` +2. **Basic Configure**: `../../configure --target-list=[list of targets]` + - Common targets: `x86_64-softmmu`, `aarch64-softmmu`, `riscv64-softmmu`, `x86_64-linux-user`. +3. **Common Options**: + - `--enable-debug-info`: Include symbols. + - `--enable-debug`: Enable assertions. +4. **Sanitizers**: + - `--enable-asan`: Address Sanitizer. + - `--enable-tsan`: Thread Sanitizer. + - `--enable-ubsan`: Undefined Behavior Sanitizer. +5. **Help**: + - `--help`: will give a comprehensive list of options + +## Building +**Important**: Always re-run the build after making changes to the source code. + +## Reporting Results +**Crucial**: After completing the build task, provide a concise summary of the results to the user. +1. **Summary**: State whether the build passed or failed. +2. **Failure Excerpts**: If the build fails, include relevant excerpts from the logs (e.g., compiler errors). + +## Debugging and Environment +- **Verbose**: `V=1` for detailed output. diff --git a/.gitignore b/.gitignore index 4ccba871d16..83bdf3df59c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ /GNUmakefile /build/ +/builds/ /.cache/ /.vscode/ *.pyc diff --git a/AGENTS.md b/AGENTS.md index a34a92244e5..29a13ca01b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,6 +31,7 @@ If unsure read the linked document for guidance. ## Agent Skills (see `.agents/skills`) You should use the following specialized skills for common tasks: - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem. +- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds). ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code. -- 2.47.3
