From e1d3b34ac5bd45d71af40dcd91904ffb0b4e08d6 Mon Sep 17 00:00:00 2001 From: Cheng Li Date: Mon, 7 Sep 2026 23:42:55 +0900 Subject: [PATCH] [docs] point QEMU Linux quick start at qemu-nographic.sh The quick start only ever mentions ./qemu.sh, and its file table omits the qemu-nographic scripts entirely. qemu.sh passes -serial stdio without -nographic, so QEMU opens a GTK window for the emulated CLCD. On a headless machine or over SSH it stops at "gtk initialization failed", with nothing in the guide explaining what to do next, even though the BSP already ships qemu-nographic.sh for exactly this case. Add both nographic scripts to the file table and document them where the project is first run. --- .../quick_start_qemu/quick_start_qemu_linux.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md b/documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md index 1945e4a333d8..eade5c94e931 100644 --- a/documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md +++ b/documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md @@ -141,6 +141,8 @@ The main files and directories of `qemu-vexpress-a9` BSP are described as follow | drivers | The underlying driver provided by RT-Thread | | qemu.bat | Script files running on Windows platform | | qemu.sh | Script files running on Linux platform | +| qemu-nographic.bat | Script files running on Windows platform, without a graphical window | +| qemu-nographic.sh | Script files running on Linux platform, without a graphical window | | qemu-dbg.bat | Debugging script files on Windows platform | | qemu-dbg.sh | Debugging script files on Linux platform | | README.md | Description document of BSP | @@ -160,6 +162,16 @@ After compiling, type `./qemu.sh` to start the virtual machine and BSP project. ![run the project](figures/ubuntu-qume-sh.png) +`qemu.sh` opens a graphical window for the emulated CLCD display, so it +needs a desktop session. Over SSH, or on a machine without a display, it +fails with an error such as `gtk initialization failed`. Use +`./qemu-nographic.sh` instead, which runs the same BSP with the console +on the terminal: + +```shell +./qemu-nographic.sh +``` + ### 5.3 Run the Finsh Console RT-Thread supports Finsh, and users can use command operations in command line mode.