.. _develop_getting_started:

搭建开发环境并运行第一个应用
############################################################

本页依据 :doc:`/maintenance` 中记录的 Zephyr ``main`` 快照更新。

先准备主机工具，再创建 Python 虚拟环境与 west 工作区，最后安装 SDK 并构建应用。
本页以 Ubuntu 24.04 LTS 或更新版本为主；Windows 步骤见 :doc:`windows`。

版本要求
========

本次核对的官方入门指南列出的最低版本为：

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - 工具
     - 最低版本
   * - Python
     - 3.12
   * - CMake
     - 3.20.5
   * - Devicetree compiler（dtc）
     - 1.4.6

这些是 Zephyr 开发环境要求；仅构建本中文资料站的依赖见 :doc:`write_doc`。

Ubuntu 主机工具
===============

在终端安装依赖：

.. code-block:: bash

   sudo apt update
   sudo apt install --no-install-recommends git cmake ninja-build gperf \
     ccache dfu-util device-tree-compiler wget python3-dev python3-venv python3-tk \
     xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1
   cmake --version
   python3 --version
   dtc --version

AArch64 主机的软件仓库可能没有 ``gcc-multilib``、``g++-multilib``，应移除这两项。
其他发行版请参照官方 Linux 安装说明选择软件包。

创建工作区
==========

以下命令用于新工作区 ``~/zephyrproject``，需能够访问 GitHub 和 Python 包源：

.. code-block:: bash

   python3 -m venv ~/zephyrproject/.venv
   source ~/zephyrproject/.venv/bin/activate
   python -m pip install west
   west init -m https://github.com/zephyrproject-rtos/zephyr --mr main ~/zephyrproject
   cd ~/zephyrproject
   west update
   west packages pip --install
   west zephyr-export
   cd zephyr
   west sdk install

每次打开新终端，先激活同一个虚拟环境。``west packages pip --install`` 从工作区收集
所需 Python 包；安装过程中 west 自身也可能被升级或降级。
``west sdk install`` 根据当前 Zephyr 版本选择 SDK。可用选项见
``west sdk install --help``，需要时仅安装目标架构工具链。

上述 ``--mr main`` 获取运行命令时的开发分支。要复现本次文档基线，把 ``main`` 换成
``02d743889396e724d53be61e4fe34c484c1d5a97``；使用发布版时换成对应标签，
同时选择该版本官方文档。不要在已有工作区重复运行 ``west init``，升级步骤见
:doc:`west/basic`。

没有开发板时使用 QEMU
======================

在 ``~/zephyrproject/zephyr`` 中，可以直接使用 QEMU 模拟 32 位 Cortex-M3 或 64 位
Cortex-A53 目标板：

.. code-block:: bash

   # 32 位 ARMv7-M 模拟目标
   west build -p always -b qemu_cortex_m3 samples/hello_world
   west build -t run

   # 64 位 ARMv8-A 模拟目标（调用 qemu-system-aarch64）
   west build -p always -b qemu_cortex_a53 samples/hello_world
   west build -t run

终端会显示启动横幅与 ``Hello World! qemu_cortex_a53`` 输出。QEMU 通常可先按 ``Ctrl+A``
松开后再按 ``X`` 退出。首次构建或切换目标板时使用 ``-p always`` 清理指定构建目录的旧产物，
后续相同目标可用 ``west build`` 进行增量构建。这里的清理只应针对构建输出目录。

想要基于 ``qemu_cortex_a53`` 从零编写包含日志、Shell、GPIO 中断、多线程消息队列和 NVS 存储的
完整工程，可在阅读完 :doc:`application` 后进入 :doc:`/tutorial/index`。

在硬件上运行
============

查看所用板卡的官方页面，取得准确的 board target，并确认烧录工具和调试探针要求：

.. code-block:: bash

   west boards
   west build -p always -b nrf52840dk/nrf52840 samples/basic/blinky
   west flash

此例目标是 nRF52840 DK；使用其他开发板时替换目标。多核目标可能还需要 CPU cluster，
例如 ``nrf5340dk/nrf5340/cpuapp``。Blinky 需要板级定义的 LED；没有相应 LED 的板卡可以
构建 ``samples/hello_world``。Linux 主机还可能需要调试探针的 udev 规则。

macOS
=====

当前上游入门文档注明不支持 x86-64 macOS。受支持主机可按官方步骤安装 Homebrew 依赖：

.. code-block:: bash

   brew install cmake ninja gperf python3 python-tk ccache qemu dtc libmagic wget openocd

随后使用本页的虚拟环境、west 工作区与 SDK 流程，先确认 ``python3 --version``
满足最低要求；Homebrew 的路径设置按安装器输出配置。

排查顺序
========

#. ``python --version`` 和 ``python -m pip --version`` 是否来自预期虚拟环境。
#. ``west topdir`` 是否指向当前工作区，``west list`` 是否显示完整的所需模块。
#. 切换版本后是否重新执行 ``west update`` 和依赖安装。
#. 开发板名称是否符合当前硬件模型，是否使用了该目标自己的构建目录。
#. SDK 是否与当前源码要求匹配，烧录 runner 是否已安装且能访问调试探针。

上游依据
========

* `官方文档：develop/getting_started/index <https://docs.zephyrproject.org/latest/develop/getting_started/index.html>`_
* `官方文档：develop/toolchains/zephyr_sdk <https://docs.zephyrproject.org/latest/develop/toolchains/zephyr_sdk.html>`_