Ubuntu2404 下搭建 Zephyr 开发环境

1. 系统要求

• 操作系统：Ubuntu2404（64位）
• 磁盘空间：至少 8GB 可用空间（Zephyr 及其工具链较大）

2. 安装必要工具

 2.1 安装系统依赖

# 更新软件源并安装基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y --no-install-recommends git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget \
  python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
  make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

2.2 验证主要依赖项版本

cmake --version
python3 --version
dtc --version

cmake version 3.22.1
CMake suite maintained and supported by Kitware (kitware.com/cmake).
Python 3.10.12
Version: DTC 1.6.1

2.3 获取Zephyr和安装Python依赖项

2.3.1 安装Python venv安装包

sudo apt install -y python3-venv

2.3.2 创建Python 虚拟环境

# 创建虚拟环境
python3 -m venv ~/workspace/zephyr-venv

2.3.3 激活虚拟环境

source ~/workspace/zephyr-venv/bin/activate

2.3.4 安装west

# 使用国内镜像源速度快
pip install west -i https://pypi.mirrors.ustc.edu.cn/simple/

2.3.5 获取 Zephyr 源码

# 初始化 Zephyr 项目
west init ~/workspace/zephyr-project
cd ~/workspace/zephyr-project
west update

# west update主要下载submodules github源码

(zephyr-venv) Weston@PC:~/workspace/zephyr-project$ west update
=== updating acpica (modules/lib/acpica):
HEAD is now at 8d24867bc Merge pull request #5 from dcpleung/kernel/mm_z_phys_map_unmap_rename
=== updating cmsis (modules/hal/cmsis):
HEAD is now at d1b8b20 Backport CMSIS_6#102 to CMSIS 5.9.0
=== updating cmsis-dsp (modules/lib/cmsis-dsp):
HEAD is now at d80a49b2 do not generate warnings when scalar functions are used with MVE
=== updating cmsis-nn (modules/lib/cmsis-nn):
HEAD is now at e9328d6 manifest: zephyr module file
=== updating cmsis_6 (modules/lib/cmsis_6):
HEAD is now at 783317a3 TZ applications can be secure-only (#204)
=== updating edtt (tools/edtt):
HEAD is now at b9ca3c7 Fix for for python >= 3.11
=== updating fatfs (modules/fs/fatfs):
HEAD is now at 16245c7 fs: Update driver to version 0.15a
=== updating hal_adi (modules/hal/adi):
HEAD is now at 8f33130 fix(Other): Add 'static inline' keywords to Zephyr Timer Wrapper functions (#1379)
=== updating hal_altera (modules/hal/altera):
HEAD is now at 4fe4df9 uart: do not build hal uart driver
=== updating hal_ambiq (modules/hal/ambiq):
HEAD is now at 9da9656 add back missing files for apollo3 and apollo4
=== updating hal_atmel (modules/hal/atmel):
HEAD is now at ca7e4c6 sam3x: spi: missing adc macro
=== updating hal_bouffalolab (modules/hal/bouffalolab):
HEAD is now at c6c44b8 pinctrl: pinconfig: Add autogen
=== updating hal_espressif (modules/hal/espressif):
HEAD is now at e794f935ff zephyr: port: Heap adapter
=== updating hal_ethos_u (modules/hal/ethos_u):
HEAD is now at 50ddffc Cache optimizations
=== updating hal_gigadevice (modules/hal/gigadevice):
HEAD is now at 2994b7d README.md: add pllmf and pack exception for gd32a50x
=== updating hal_infineon (modules/hal/infineon):
HEAD is now at d7b8432 Update CYW20829 BLE FW blobs
=== updating hal_intel (modules/hal/intel):
HEAD is now at 0447cd2 Update pm_regs.h
=== updating hal_microchip (modules/hal/microchip):
HEAD is now at 15ca197 hal: microchip: mec5: Fix bugs in EC subsystem debug enable
=== updating hal_nordic (modules/hal/nordic):
HEAD is now at a5a2277 nrfx: drivers: rramc: Declare functions as unused
=== updating hal_nuvoton (modules/hal/nuvoton):
HEAD is now at be1042d hal:nuvoton:m55m1: support emac
=== updating hal_nxp (modules/hal/nxp):
HEAD is now at 5e5a498e mcux: wifi: nxp: support override TX power limit file
=== updating hal_openisa (modules/hal/openisa):
HEAD is now at eabd530 fix-double-promotion in fsl_xcvr_trim
=== updating hal_quicklogic (modules/hal/quicklogic):
HEAD is now at bad8944 HAL: eoss3_dev: add missing `__cplusplus` handling
=== updating hal_renesas (modules/hal/renesas):
HEAD is now at 9d68ee7 portable: rp_crc: add runtime reconfigure for CRC
=== updating hal_rpi_pico (modules/hal/rpi_pico):
HEAD is now at 7b57b24 Merge pull request #8 from ajf58/merge-2.1.0
=== updating hal_silabs (modules/hal/silabs):
HEAD is now at 40a0237 wiseconnect: Use static allocation for threads
=== updating hal_st (modules/hal/st):
HEAD is now at 9f81b44 sensor/stmemsc: Align stmemsc i/f to v2.9.1
=== updating hal_stm32 (modules/hal/stm32):
HEAD is now at 6e4716f8 dts: st: update pinctrls related to dcmipp pins
=== updating hal_tdk (modules/hal/tdk):
HEAD is now at 6727477 Merge pull request #8 from tdk-invn-oss/main
=== updating hal_telink (modules/hal/telink):
HEAD is now at 4226c7f drivers: Disable BLE support
=== updating hal_ti (modules/hal/ti):
HEAD is now at 258652a simplelink_lpf3: Add README.md
=== updating hal_wch (modules/hal/wch):
HEAD is now at 1de9d3e Add hal_wch based on the 'ch32v003fun' project
=== updating hal_wurthelektronik (modules/hal/wurthelektronik):
HEAD is now at e3e2797 Remove preprocessor warnings for not enabling float
=== updating hal_xtensa (modules/hal/xtensa):
HEAD is now at b38620c zephyr: Add SoC overlay for i.MXRT700 HiFi1 DSP
=== updating hostap (modules/lib/hostap):
HEAD is now at 8412f4b23 [noup] zephyr: remove zephyr wpas monitor socket pair
=== updating liblc3 (modules/lib/liblc3):
HEAD is now at 48bbd3e Rename lc3 python package to lc3py, and bump version to 1.1.2
=== updating libmctp (modules/lib/libmctp):
HEAD is now at b97860e build MCTP zephyr library only when CONFIG_MCTP is enabled
=== updating libmetal (modules/hal/libmetal):
HEAD is now at 14f5195 lib: update libmetal to SHA 9a21915a5f8f
=== updating littlefs (modules/fs/littlefs):
HEAD is now at ed0531d Merge pull request #15 from Jappie3/zephyr
=== updating loramac-node (modules/lib/loramac-node):
HEAD is now at fb00b383 zephyr: configure FragDecoder using Kconfig
=== updating lvgl (modules/lib/gui/lvgl):
HEAD is now at 1ed1ddd88 docs(Alif): add docs for Alif chip vendor (#7622)
=== updating mbedtls (modules/crypto/mbedtls):
HEAD is now at 5f8899343 Merge pull request #70 from tomi-font/bump_to_3.6.3
=== updating mcuboot (bootloader/mcuboot):
HEAD is now at 81315483 Revert "zephyr: arm: Update reading the flash image reset vector"
=== updating mipi-sys-t (modules/debug/mipi-sys-t):
HEAD is now at 33e5c23 Fix for warning of potential error using = instead of ==
=== updating net-tools (tools/net-tools):
HEAD is now at 986bfeb Replace native_posix with native_sim
=== updating nrf_hw_models (modules/bsim_hw_models/nrf_hw_models):
HEAD is now at d5b95fd grtc hal replacement: Fix bug in nrf_grtc_int_group_enable/disable()
=== updating nrf_wifi (modules/lib/nrf_wifi):
HEAD is now at d89b42a Remove recovery code for radio test
=== updating open-amp (modules/lib/open-amp):
HEAD is now at f7f4d08 lib: update open-amp lib  to SHA 9a21915a5f8f
=== updating openthread (modules/lib/openthread):
HEAD is now at 3ae741f95 [instance] fix index computation in multi-instances context (#11099)
=== updating percepio (modules/debug/percepio):
HEAD is now at 49e6dc2 Merge branch 'main' into zephyr
=== updating picolibc (modules/lib/picolibc):
HEAD is now at 82d62ed1a zephyr: Disable LTO when building the library
=== updating segger (modules/debug/segger):
HEAD is now at cf56b1d readme: Add readme
=== updating tinycrypt (modules/crypto/tinycrypt):
HEAD is now at 1012a3e Fix warnings reported by UBSAN
=== updating trusted-firmware-a (modules/tee/tf-a/trusted-firmware-a):
HEAD is now at 713ffbf96 Merge pull request #4 from ceolin/v2.10.4
=== updating trusted-firmware-m (modules/tee/tf-m/trusted-firmware-m):
HEAD is now at e2288c13e Merge pull request #130 from tomi-font/bump_to_2.1.2
=== updating uoscore-uedhoc (modules/lib/uoscore-uedhoc):
HEAD is now at 54abc10 Merge pull request #5 from rlubos/upmerge-02-2025
=== updating zcbor (modules/lib/zcbor):
HEAD is now at 9b07780 Update version to 0.9.1

2.3.6 导入 Zephyr 环境变量

west zephyr-export

2.3.7  安装west python依赖包

# 使用国外镜像源比较慢
west packages pip --install

注意：永久切换pip使用国内镜像源

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

pip config list

# 恢复默认配置

pip config unset global.index-url
pip config unset global.trusted-host

常见镜像源地址

3. 安装 Zephyr SDK

# 导出环境变量
echo "export ZEPHYR_BASE=~/workspace/zephyr-project/zephyr" >> ~/.bashrc
source ~/.bashrc

# 下载并安装 SDK
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/zephyr-sdk-0.17.0_linux-x86_64.tar.xz
# 解压并安装
tar xvf zephyr-sdk-0.17.0_linux-x86_64.tar.xz
cd zephyr-sdk-0.17.0
./setup.sh

Zephyr SDK 0.17.0 Setup

** NOTE **
You only need to run this script once after extracting the Zephyr SDK
distribution bundle archive.

Install host tools [y/n]? y
Register Zephyr SDK CMake package [y/n]? y

Installing host tools ...

Registering Zephyr SDK CMake package ...
Zephyr-sdk (/home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/cmake)
has been added to the user package registry in:
~/.cmake/packages/Zephyr-sdk


All done.
Press any key to exit ...

设置环境变量

echo "export ZEPHYR_TOOLCHAIN_VARIANT=zephyr" >> ~/.bashrc
echo "export ZEPHYR_SDK_INSTALL_DIR=$HOME/workspace/zephyr-sdk/zephyr-sdk-0.17.0" >> ~/.bashrc
source ~/.bashrc

4. 验证安装

(1) 检查环境

west --version
cmake --version
ninja --version
python --version

# 所有命令应正常输出版本号
West version: v1.3.0
cmake version 3.22.1
1.10.2.git.kitware.jobserver-1
Python 3.10.12

(2) 编译示例项目

cd ~/workspace/zephyr-project/zephyr
west build -b blackpill_f401cc samples/hello_world

(zephyr-venv) polaris@PC:~/workspace/zephyr-project/zephyr$ west build -b blackpill_f401cc samples/hello_world
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /home/polaris/workspace/zephyr-project/zephyr/samples/hello_world
-- CMake version: 3.22.1
-- Found Python3: /home/polaris/workspace/zephyr-venv/bin/python3 (found suitable version "3.10.12", minimum required is "3.10") found components: Interpreter 
-- Cache files will be written to: /home/polaris/.cache/zephyr
-- Zephyr version: 4.1.99 (/home/polaris/workspace/zephyr-project/zephyr)
-- Found west (found suitable version "1.3.0", minimum required is "0.14.0")
-- Board: blackpill_f401cc, qualifiers: stm32f401xc
-- Found host-tools: zephyr 0.17.0 (/home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0)
-- Found toolchain: zephyr 0.17.0 (/home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0)
-- Found Dtc: /home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/sysroots/x86_64-pokysdk-linux/usr/bin/dtc (found suitable version "1.6.0", minimum required is "1.4.6") 
-- Found BOARD.dts: /home/polaris/workspace/zephyr-project/zephyr/boards/weact/blackpill_f401cc/blackpill_f401cc.dts
-- Generated zephyr.dts: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.dts
-- Generated pickled edt: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/edt.pickle
-- Generated devicetree_generated.h: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/include/generated/zephyr/devicetree_generated.h
-- Including generated dts.cmake file: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/dts.cmake
Parsing /home/polaris/workspace/zephyr-project/zephyr/Kconfig
Loaded configuration '/home/polaris/workspace/zephyr-project/zephyr/boards/weact/blackpill_f401cc/blackpill_f401cc_defconfig'
Merged configuration '/home/polaris/workspace/zephyr-project/zephyr/samples/hello_world/prj.conf'
Configuration saved to '/home/polaris/workspace/zephyr-project/zephyr/build/zephyr/.config'
Kconfig header saved to '/home/polaris/workspace/zephyr-project/zephyr/build/zephyr/include/generated/zephyr/autoconf.h'
-- Found GnuLd: /home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/arm-zephyr-eabi/arm-zephyr-eabi/bin/ld.bfd (found version "2.38") 
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- The ASM compiler identification is GNU
-- Found assembler: /home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
-- Using ccache: /usr/bin/ccache
-- Found gen_kobject_list: /home/polaris/workspace/zephyr-project/zephyr/scripts/build/gen_kobject_list.py
-- Configuring done
-- Generating done
-- Build files have been written to: /home/polaris/workspace/zephyr-project/zephyr/build
-- west build: building application
[1/140] Preparing syscall dependency handling

[3/140] Generating include/generated/zephyr/version.h
-- Zephyr version: 4.1.99 (/home/polaris/workspace/zephyr-project/zephyr), build: v4.1.0-3774-gc35bb0de8023
[140/140] Linking C executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       15996 B       256 KB      6.10%
             RAM:        4544 B        64 KB      6.93%
        IDT_LIST:          0 GB        32 KB      0.00%
Generating files from /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.elf for board: blackpill_f401cc

• -b blackpill_f401cc：指定 Black Pill STM32F401CC 开发板
• 首次编译会下载工具链和依赖，耗时较长。

(3) 烧录与调试

west flash --runner blackmagicprobe
west debug --runner blackmagicprobe
west attach --runner blackmagicprobe

# 使用blackmagicprobe烧录固件
west flash --runner blackmagicprobe
-- west flash: rebuilding
ninja: no work to do.
-- west flash: using runner blackmagicprobe
-- runners.blackmagicprobe: using GDB serial: /dev/ttyACM0
Remote debugging using /dev/ttyACM0
Target voltage: 2.45V
Available Targets:
No. Att Driver
 1      STM32F411 M4
Attaching to Remote target
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
0x08001ac8 in ?? ()
Loading section rom_start, size 0x194 lma 0x8000000
Loading section text, size 0x3448 lma 0x8000194
Loading section .ARM.exidx, size 0x8 lma 0x80035dc
Loading section initlevel, size 0x80 lma 0x80035e4
Loading section device_area, size 0x180 lma 0x8003664
Loading section sw_isr_table, size 0x2a8 lma 0x80037e4
Loading section gpio_driver_api_area, size 0x24 lma 0x8003a8c
Loading section reset_driver_api_area, size 0x10 lma 0x8003ab0
Loading section clock_control_driver_api_area, size 0x1c lma 0x8003ac0
Loading section uart_driver_api_area, size 0x4c lma 0x8003adc
Loading section rodata, size 0x2ec lma 0x8003b28
Loading section datas, size 0x4c lma 0x8003e14
Loading section device_states, size 0x18 lma 0x8003e60
Loading section .last_section, size 0x4 lma 0x8003e78
Start address 0x0800087c, load size 15996
Transfer rate: 29 KB/sec, 592 bytes/write.
[Inferior 1 (Remote target) killed]

# 使用blackmagicprobe在线调试固件
west debug --runner blackmagicprobe
-- west debug: rebuilding
ninja: no work to do.
-- west debug: using runner blackmagicprobe
-- runners.blackmagicprobe: using GDB serial: /dev/ttyACM0
GNU gdb (Zephyr SDK 0.17.0) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=arm-zephyr-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://github.com/zephyrproject-rtos/sdk-ng/issues>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word".
Remote debugging using /dev/ttyACM0
Target voltage: 2.48V
Available Targets:
No. Att Driver
 1      STM32F411 M4
Attaching to Remote target
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
0x08002b48 in ?? ()
Reading symbols from /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.elf...
Loading section rom_start, size 0x194 lma 0x8000000
Loading section text, size 0x3448 lma 0x8000194
Loading section .ARM.exidx, size 0x8 lma 0x80035dc
Loading section initlevel, size 0x80 lma 0x80035e4
Loading section device_area, size 0x180 lma 0x8003664
Loading section sw_isr_table, size 0x2a8 lma 0x80037e4
Loading section gpio_driver_api_area, size 0x24 lma 0x8003a8c
Loading section reset_driver_api_area, size 0x10 lma 0x8003ab0
Loading section clock_control_driver_api_area, size 0x1c lma 0x8003ac0
Loading section uart_driver_api_area, size 0x4c lma 0x8003adc
Loading section rodata, size 0x2ec lma 0x8003b28
Loading section datas, size 0x4c lma 0x8003e14
Loading section device_states, size 0x18 lma 0x8003e60
Loading section .last_section, size 0x4 lma 0x8003e78
Start address 0x0800087c, load size 15996
Transfer rate: 30 KB/sec, 592 bytes/write.
(gdb) 


# 使用blackmagicprobe接入调试
west attach --runner blackmagicprobe
-- west attach: rebuilding
ninja: no work to do.
-- west attach: using runner blackmagicprobe
-- runners.blackmagicprobe: using GDB serial: /dev/ttyACM0
GNU gdb (Zephyr SDK 0.17.0) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=arm-zephyr-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://github.com/zephyrproject-rtos/sdk-ng/issues>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word".
Remote debugging using /dev/ttyACM0
Target voltage: 2.39V
Available Targets:
No. Att Driver
 1      STM32F411 M4
Attaching to Remote target
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
0x08002b48 in ?? ()
Reading symbols from /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.elf...
(gdb) 

如果看到 Hello World! zephyr 输出，说明环境搭建成功！

问题： 解决github https下载失败超时问题

git config --local url."git@github.com:".insteadOf "https://github.com/"

这样会将所有 https://github.com/ 开头的 URL 自动替换为 SSH 协议