From 7c838edbb74cd5fba737a9938e67a015693a4fe9 Mon Sep 17 00:00:00 2001
From: Cheng Li <>
Date: Mon, 7 Sep 2026 23:41:45 +0900
Subject: [PATCH] [docs] fix outdated and missing apt packages in QEMU Linux
 quick start

The dependency list in the QEMU (Ubuntu) quick start no longer works on
current Debian/Ubuntu releases:

- gdb-arm-none-eabi no longer exists (dropped since Debian 11 /
  Ubuntu 22.04); gdb-multiarch replaces it
- the qemu meta-package has been split up and can no longer be installed
- libncurses5-dev has been removed; libncurses-dev replaces it
- libstdc++-arm-none-eabi-newlib was missing, so linking fails with
  "cannot find -lsupc++", which does not point at the missing package
- kconfiglib was not mentioned at all, although scons --menuconfig needs
  it; python3-kconfiglib is packaged, and pip install kconfiglib is
  rejected by PEP 668 on recent releases

Merge the eleven single-package commands into one, add a table mapping
the old package names to the current ones, and note the kconfiglib
requirement where menuconfig is first used.

Verified with apt-get -s install on Debian 13.
---
 .../quick_start_qemu_linux.md                 | 33 ++++++++++++-------
 1 file changed, 22 insertions(+), 11 deletions(-)

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..d830239b66ea 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
@@ -7,19 +7,25 @@ The development of embedded software is inseparable from the development board.
 We need to type commands as following in the terminal:
 
 ```shell
-sudo apt install gcc
-sudo apt install python3
-sudo apt install python3-pip
-sudo apt install gcc-arm-none-eabi
-sudo apt install gdb-arm-none-eabi
-sudo apt install binutils-arm-none-eabi
-sudo apt install scons
-sudo apt install libncurses5-dev
-sudo apt install qemu
-sudo apt install qemu-system-arm
-sudo apt install git
+sudo apt install git gcc scons python3 python3-kconfiglib \
+    gcc-arm-none-eabi binutils-arm-none-eabi libstdc++-arm-none-eabi-newlib \
+    gdb-multiarch qemu-system-arm libncurses-dev
 ```
 
+> Note for users of older tutorials or older distributions: several package
+> names used to be different, and some no longer exist at all. If a package is
+> reported as not found, check the table below:
+>
+> | Old package name | Current package name | Reason |
+> | ---------------- | -------------------- | ------ |
+> | `gdb-arm-none-eabi` | `gdb-multiarch` | Dropped since Debian 11 / Ubuntu 22.04 |
+> | `qemu` | `qemu-system-arm` | The `qemu` meta-package has been split up; install only the ARM system emulator |
+> | `libncurses5-dev` | `libncurses-dev` | The `ncurses5` transitional package has been removed |
+>
+> `libstdc++-arm-none-eabi-newlib` is required at link time. Without it the
+> build fails with `cannot find -lsupc++`, which does not make the missing
+> package obvious.
+
 ## 2 Get RT-Thread source code
 
 Download RT-Thread Source Code : `git clone https://github.com/RT-Thread/rt-thread.git`
@@ -75,6 +81,11 @@ Type following the command under  `bsp/qemu-vexpress-a9` folder:
 scons --menuconfig
 ```
 
+`scons --menuconfig` requires `kconfiglib`. It is installed as
+`python3-kconfiglib` by the command in chapter 1. Installing it with
+`pip install kconfiglib` instead fails on recent Debian/Ubuntu releases,
+because PEP 668 marks the system Python environment as externally managed.
+
 The Env tool will be installed and initialized after using the `scons --menuconfig` command. Then it will enter the configuration interface, and you could configure the BSP:
 
 ![install env tool](figures/ubuntu-menuconfig.png)