Zephyr west简介

本文简要介绍zephyr west的安装和使用。

west是zephyr提供”meta-tool”,一直以来我都是使用git clone+cmake的方式进行编译，直到现在越来越多的ext module从zephyr的仓库独立出来，不得不完全切换到west上。
zephyr的官网将west叫做瑞士军刀，但从目前使用的状况来west提供下面几种功能:

1. 多仓库管理，类似于google的repo
2. Zephyr编译环境的配置： 相当于之前设置ZEPHYR BASE的环境变量等
3. 提供编译，烧写，调试功能： 相当于之前的make, make flash, make debug等
4. 提供image签名功能： 将mucboot的签名工具集成
   以上的2~3都可以认为是west提供的集成功能，通过python程序调用相关的命令，和之前的命令相比较有west tool这样一个统一的入口，其它并没有发现什么额外的好处。
   west提供了可扩展命令的添加接口，用户可以将自己的一些命令或者tool以插件的形式加入的west内。以此看来zephyr对west的打算可能是做成一个工具集。
   本文基于ubuntu18.04说明west的安装和使用。

west安装

安装

执行下面命令安装west

pip3 install --user -U west

安装完后执行下面命令可以看到west的版本信息说明已经安装完成

west -V

命令自动补全

west有一些子命令，安装后需要通过配置才能用tab建自动补全,执行下面命令生成补全脚本

west completion bash > west-completion.bash

将补全脚west-completion.bash 放到 /etc/bash_completion.d/

代码管理

初始化工作仓库

使用下面命令将初始化一个工作仓库westz

west init ~/work/project/westz

初始化完成后westz下面有zephyr的完整代码和west的配置信息

zephyrproject
├── .west
│   ├── config
│   └── west
├── zephyr
    ├── west.yml
    └── [... other files ...]

west init默认使用https://github.com/zephyrproject-rtos/zephy 作为提货单地址，可以在west init时用-m指定提货单地址,-mr指定提取的版本，例如

west init -m https://github.com/zephyrproject-rtos/zephyr --mr v1.15.0

刷新工作仓库

使用下面命令会将提货单的内的其它仓库代码都下载下来

west update

在westz目录下就会看到

.
├── modules
├── net-tools
└── zephyr

west会为除zephyr外其它所有仓库建立manifest-rev分支

其它命令

west list: 列出提货单内仓库信息,如下

zephyr         zephyr             (not set)     (not set) (cloned)
net-tools      net-tools          30b7efa827b04d2e47840716b0372737fe7d6c92 https://github.com/zephyrproject-rtos/net-tools (cloned)
tinycbor       modules/lib/tinycbor 31ae89e4b768612722620cb6cb173a0de4a19cc9 https://github.com/zephyrproject-rtos/tinycbor (cloned)
hal_qmsi       modules/hal/qmsi   9195fe6f97e4f7f25a3fc9e5a515f1b7af13762c https://github.com/zephyrproject-rtos/hal_qmsi (cloned)
esp-idf        modules/hal/esp-idf 6835bfc741bf15e98fb7971293913f770df6081f https://github.com/zephyrproject-rtos/esp-idf (cloned)
fatfs          modules/fs/fatfs   df96914dd989907f3a5de4cb95b116c2f305820d https://github.com/zephyrproject-rtos/fatfs (cloned)
hal_cypress    modules/hal/cypress a12d92816a53a521d79cefcf5c38b9dc8a4fed6e https://github.com/zephyrproject-rtos/hal_cypress (cloned)
hal_silabs     modules/hal/silabs 9151e614c23997074acd1096a3e8a9e5c255d5b9 https://github.com/zephyrproject-rtos/hal_silabs (cloned)
libmetal       modules/hal/libmetal 45e630d6152824f807d3f919958605c4626cbdff https://github.com/zephyrproject-rtos/libmetal (cloned)
mcumgr         modules/lib/mcumgr 84934959d2d1722a23b7e7e200191ae4a6f96168 https://github.com/zephyrproject-rtos/mcumgr (cloned)
nffs           modules/fs/nffs    bc62a2fa9d98ddb5d633c932ea199bc68e10f194 https://github.com/zephyrproject-rtos/nffs (cloned)
open-amp       modules/lib/open-amp 893b2a57e629cccb81282cec04b0385f3d49d871 https://github.com/zephyrproject-rtos/open-amp (cloned)
segger         modules/debug/segger 6fcf61606d6012d2c44129edc033f59331e268bc https://github.com/zephyrproject-rtos/segger (cloned)

west manifest –freeze [-o outfile]: 冻结当前各仓库信息，可以用该命令创建”定版”的提货单
west diff [PROJECT …]: 相当于在对各个仓库执行git diff
west status [PROJECT …]: 相当于在对各仓库执行git status
west forall -c COMMAND [PROJECT …]: 对各仓库执行shel命令，没实际用过，详见官方文档
west selfupdate: 更新west自己

提货单简介

west init使用的提货单就是zephyr/west.yml截取一段进行说明

west:
  url: https://github.com/zephyrproject-rtos/west
  revision: v0.5.7

manifest:
  defaults:
    remote: upstream

  remotes:
    - name: upstream
      url-base: https://github.com/zephyrproject-rtos

  projects:
    - name: net-tools
      revision: 30b7efa827b04d2e47840716b0372737fe7d6c92
    - name: tinycbor
      path: modules/lib/tinycbor
      revision: 31ae89e4b768612722620cb6cb173a0de4a19cc9
    - name: hal_qmsi
      revision: 9195fe6f97e4f7f25a3fc9e5a515f1b7af13762c
      path: modules/hal/qmsi
    - name: mcumgr
      revision: 84934959d2d1722a23b7e7e200191ae4a6f96168
      path: modules/lib/mcumgr      
  self:
    path: zephyr
    west-commands: scripts/west-commands.yml

一个west提货单是由west和manifest两个section组成

west section

west section的 url和revision分别指明要下载使用的west远程地址和版本

manifest section

manifest section指明要下载各代码仓库的名称，路径，版本。
manifest有四个sub-section: default, remotes, projects, self。
其中remotes和projects是强制必须要的，remote指定远端地址, projects指定仓库地址和版本，以上面mcumgr为例，west下载时会已remotes的url-base+projects mcumgr的name结合为https://github.com/zephyrproject-rtos/mcumgr 下载版本为84934959d2d1722a23b7e7e200191ae4a6f96168的代码到modules/lib/mcumgr下
manifest可以在remotes里面指定多个url-base, 在projects中被不同的project引用，例如：

manifest:
  # [...]
  remotes:
    - name: remote1
      url-base: https://example.com/base1
    - name: remote2
      url-base: https://example.com/base2
  projects:
    - name: proj1
      remote: remote1
      path: extra/project-1
    - name: proj2
      remote: remote1
      revision: v1.3
    - name: proj3
      remote: remote2
      revision: abcde413a111

上面示例下载三个仓库的代码
proj1: https://example.com/base1/proj1
proj2: https://example.com/base1/proj2 v1.3
proj3: https://example.com/base2/proj3 abcde413a111
下载完后的组织形式是

.
├── extra
│   └── project-1
├── proj2
└── proj3

提交代码到github

使用west后各仓库都被head分离manifest-rev，如果我们有代码修改，如何贡献到github的远端仓库呢？这里以mcumgr为例说明

1. fork https://github.com/zephyrproject-rtos/mcumgr

2. 进入到west下载的mcumgr目录

   cd ~/work/project/westz/modules/lib/mcumgr

3. 将origin修改为upstream

   git remote rename origin upstream

4. 将fork地址修改为origin

   git remote add origin https://github.com/lgl88911/zephyr

5. 使用git remote -v如果看到下面信息说明已经修改成功

   origin	https://github.com/lgl88911/mcumgr (fetch)
   origin	https://github.com/lgl88911/mcumgr (push)
   upstream	https://github.com/zephyrproject-rtos/mcumgr (fetch)
   upstream	https://github.com/zephyrproject-rtos/mcumgr (push)

6. 基于origin建立分支修，修改代码，push到远端，提交PR.这里是一般的github的流程，不再做详述。

命令功能

west提供build,flash,debug,debugserver，达到cmake, make, make flash, make debug, make debugserver相同的功能，由于并没有发现能有更多的好处，可以通过”west help” 和”west help”查看使用方法
这里简单介绍一下常用的：

编译代码

west build -b nrf52_mother -d apps/basetest/build/ -s apps/basetest/ -- -G'Unix Makefiles' -DBOARD_ROOT=/home/frank/work/project/nrf52_moderate

等同于

cd apps/basetest
mkdir build
cd build
cmake -DBOARD=nrf52_mother -DBOARD_ROOT=/home/frank/work/project/nrf52_moderate ..
make -j

烧写&调试

west flash
west debug
west debugserver

等同于

make flash
make debug
make debugserver

信息查看

west build -t rom_report
west build -t ram_report

等同于

make rom_report
make ram_report

查看支援的板子

west boards

未找到等同命令，但如果cmake -DBOARD=XXX 的板子未发现的话，会直接提示支援那些板子

west扩展命令

west可以让用户按照规定的模式自己加入扩展命令，这部分目前无需求，有兴趣的同学可以参考https://docs.zephyrproject.org/latest/guides/west/extensions.html

参考

https://docs.zephyrproject.org/latest/guides/west/index.html
https://docs.zephyrproject.org/latest/contribute/index.html