Apache Mynewt 1.15.0 常用 CLI 命令与工具详解

目标：系统梳理 Apache Newt 1.15.0 命令行的全部常用命令与关键子命令（语法、参数、真实回显），并给出工程日常维护的注意事项，全部命令已在 Ubuntu 22.04 + Newt 1.15.0 实测通过。

一、环境信息

项目	内容
操作系统	Ubuntu 22.04.5 LTS
系统架构	x86_64
Newt	Apache Newt 1.15.0（/usr/local/bin/newt）
核心仓库	apache-mynewt-core 1.15.0
工程目录	/opt/mynewt/myproj
示例应用	apps/blinky（工程自带）与 apps/demo（本文 newt pkg new 创建）
示例目标	targets/my_blinky_sim、targets/sim_demo

Newt 是 Mynewt 的唯一官方 CLI：工程创建、包管理、目标管理、构建、烧录、调试、镜像签名全部经它完成。命令执行有个前提——必须在工程目录（含 project.yml）或其子目录内运行，否则报 unable to find project.yml 类错误。

二、命令总览

newt help 实测输出（Available Commands 节选）：

  apropos      Search manual page names and descriptions
  build        Build one or more targets
  clean        Delete build artifacts for one or more targets
  create-image Add image header to target binary
  debug        Open debugger session to target
  docs         Project documentation generation commands
  info         Show project info
  load         Load built target to board
  man          Browse the man-page for given argument
  mfg          Manufacturing flash image commands
  new          Create a new project
  pkg          Create and manage packages in the current workspace
  run          build/create-image/download/debug <target>
  size         Size of target components
  target       Commands to create, delete, configure, and query targets
  test         Executes unit tests for one or more packages

解说：1.15.0 的命令表中没有 install/upgrade 之外的仓库安装子命令——依赖安装就是 upgrade；也没有 newt targets 复数形式（实测 newt targets 报 unknown command "targets" for "newt"，正确命令是 newt target list）。日常最高频的五个命令：upgrade、build、target set、run、size。

三、工程生命周期命令

3.1 newt new —— 创建工程

export https_proxy=http://192.168.1.62:7897
newt new myproj

回显：

Downloading project skeleton from apache/mynewt-blinky...
Installing skeleton in myproj ...
Downloading project skeleton from apache/mynewt-blinky... ok
Saved new Mynewt Project to /opt/mynewt/myproj

参数说明：newt new <目录名>，从 GitHub 克隆 apache/mynewt-blinky 模板生成工程骨架（apps/blinky、targets/my_blinky_sim、unittests、repos.yml、project.yml）。需要 GitHub 访问，离线环境会失败。

3.2 newt upgrade —— 安装/升级依赖仓库

newt upgrade

回显（输出节选）：

apache-mynewt-core successfully installed version 1.15.0

解说：按 repos.yml 的版本锚点克隆/更新仓库到 repos/ 目录（首次 49 个仓库）。常用参数：newt upgrade -f 强制覆盖本地修改；newt upgrade -n 只分析不执行（dry run）。老教程的 newt install 在 1.15.0 已被移除。

3.3 newt info —— 查看工程信息

newt info

回显（输出节选）：

Repository info:
    * apache-mynewt-core: ea2b7ebf6b285a2e293c4f172cbdeae7f2b6e8f3, 1.15.0 (rc)
    * apache-mynewt-mcumgr: 1967cffc2dc9036f4709e368a6954e958efd466e, 0.7.0
    * apache-mynewt-nimble: a7a156f28954819e158b62dd613008f22f9cf73b, 1.10.0 (rc)
    * mcuboot: 9c99326b9756dbcc35b524636d99ed5f3e6cb29b, 2.1.0

解说：逐仓库给出 commit 与版本描述，是核对依赖锚点的第一命令；后接包名可看单个包信息（如 newt info apps/blinky）。

四、target 命令族详解

target 是 Mynewt 的“构建配置对象”——一个目录（targets/ 下每个目标一个目录）加一个 pkg.yml，定义 app、BSP、编译器、构建参数。1.15.0 的 newt help target 实测子命令表（节选）：

  amend       Add, change, or delete values for multi-value target variables
  cmake
  config      View or populate a target's system configuration
  copy        Copy target
  create      Create a target
  delete      Delete target
  dep         View target's dependency graph
  depviz      Output dependency graph in DOT format
  dump        Dump a target's intermediate form in JSON
  env         Print target environmental variables
  info        Show packages with global cflags
  list        List available targets
  logcfg      View a target's log configuration
  revdep      View target's reverse-dependency graph
  set         Set target configuration variable
  show        View target configuration variables
  sysdown     View a target's sysdown configuration

4.1 target create / set / show

newt target create sim_demo
newt target set sim_demo app=apps/demo bsp=@apache-mynewt-core/hw/bsp/native build_profile=debug
newt target show sim_demo

回显：

Target targets/sim_demo created.
Target targets/sim_demo successfully set to: app=apps/demo
Target targets/sim_demo successfully set to: bsp=@apache-mynewt-core/hw/bsp/native
Target targets/sim_demo successfully set to: build_profile=debug
targets/sim_demo
    app=apps/demo
    bsp=@apache-mynewt-core/hw/bsp/native
    build_profile=debug

变量逐项说明：app 指定应用包路径；bsp 指定板级支持包（@ 表示引用仓库内包，native 是宿主模拟器 BSP）；build_profile 取 debug/optimized；其他常用变量还有 syscfg（命令行级配置覆盖）、sdk、compiler 等（newt target set sim_demo 不带参数可列出全部可设变量）。

工程模板自带的 sim 目标（配置了 syscfg 覆盖后）：

newt target show my_blinky_sim

回显：

targets/my_blinky_sim
    app=apps/blinky
    bsp=@apache-mynewt-core/hw/bsp/native
    build_profile=debug
    syscfg=BLINKY_PRINT_LED_STATE=1:LED_BLINK_PIN=7

解说：syscfg= 键值对是命令行级 syscfg 覆盖，等价于在 targets/my_blinky_sim/syscfg.yml 写入，多值用冒号分隔。

4.2 target list / copy / delete

newt target list
newt target copy sim_demo sim_demo2
newt target delete sim_demo2

回显：

targets/my_blinky_sim
targets/sim_demo
Target successfully copied to: targets/sim_demo2
Target successfully deleted.

解说：list 与 show 等价（两者输出一致）；copy 可快速克隆一个变体目标（比如同应用换 BSP）；delete 删除 targets/ 下对应目录。

4.3 target dep —— 依赖图

newt target dep my_blinky_sim

回显（输出节选）：

Resolving dependencies for target my_blinky_sim
<apache-mynewt-core@1.15.0> <hw/bsp/native> <libc/baselibc> ...

解说：列出目标解析后的完整包闭包与解析原因，排查“某个包为什么被打进来”时用它；depviz 可导出 DOT 格式关系图。

4.4 target config —— 查看生效的 syscfg

newt target config my_blinky_sim

回显（输出节选）：

Target config successfully populated from syscfg.yml!

解说：该命令把目标的所有 syscfg 设置（应用、BSP、目标三层合并结果）生成/刷新到 targets/<名>/generated/ 下供查阅；查看具体值时读该目录下的头文件或用 grep 检索（如 grep -rn LED_BLINK_PIN targets/my_blinky_sim/generated）。

五、构建与运行命令

5.1 newt build

newt build my_blinky_sim

回显（输出节选）：

Building target targets/my_blinky_sim
Compiling apps/blinky/src/main.c ...
Linking /opt/mynewt/myproj/bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf
Target successfully built: targets/my_blinky_sim

解说：可一次传多个目标名空格分隔并行构建；增量构建基于时间戳，改动的文件重编。产物固定在 bin/targets/<名>/ 下。

5.2 newt run / debug / load

newt run my_blinky_sim
newt debug my_blinky_sim

回显（run 实测进入 gdb）：

(gdb)

解说：对 sim/native 目标，run = build + gdb 启动（在 gdb 提示符输入 run 开始执行，Ctrl-C 退出）；对真机目标，run = build + create-image + load + debug。load 单独执行“下载到板卡”动作，依赖 BSP 的下载脚本与硬件连接。

5.3 newt size

newt size my_blinky_sim

回显：

Error: 'newt size' not supported for sim targets.

解说：size 按段统计各包 Flash/RAM 占用，是固件体积优化的核心命令，但模拟器目标不支持（实测报错）。对真机目标（如 stm32 BSP）执行时输出 Flash/RAM 两列表格。sim 目标要看体积可直接 arm-none-eabi-size-式的宿主工具（host gcc 时用 size 命令）分析 ELF。

5.4 newt clean

newt clean my_blinky_sim

回显：

Cleaning target my_blinky_sim

解说：删除该目标的构建产物；不带目标名执行 newt clean all 清全部。syscfg 层级变化导致的编译诡异问题时，clean + build 是标准复位动作。

六、包管理命令

6.1 newt pkg new —— 创建包

newt pkg new apps/demo --type app

回显：

Download package template for package type "app".
Package pkgName is apps/demo

解说：--type 支持 app/bsp/lib/sdk/test 等包类型；生成的 apps/demo 含 pkg.yml 与 src/。app 类型包的 pkg.yml 声明 pkg.deps（依赖的库/BSP），newt build 据此做闭包解析。

6.2 newt pkg 的其他子命令

newt pkg -h 可见 dump/repos/link 等子命令；最常用就是 new。仓库级包管理在 repos.yml 中声明，无需 pkg 子命令参与。

七、辅助命令

7.1 newt test —— 单元测试

newt test unittests/all

解说：对工程模板自带的 unittests/all 执行主机端单元测试（同样基于 sim/native BSP 编译为可执行文件后运行），返回码 0 即全部通过；常用于 CI 门禁。

7.2 newt create-image —— 生成签名镜像

newt create-image my_blinky_sim 1.0.0

解说：为构建产物添加 mcuboot 兼容的镜像头并支持签名参数（--key 或 target 变量 syscfg 中配钥），真机 OTA 场景必备；sim 目标无意义，真机目标实测需要先 build。

7.3 newt vals / man / docs

newt vals bsp

解说：vals 列出某类变量的全部可选值（如全部 BSP 列表）；man/man-build 浏览生成手册；docs 生成工程文档，均为低频命令，遇到参数拿不准时 newt help <命令> 最快。

八、注意事项

工程目录内执行：所有命令在 project.yml 所在目录或子目录运行；在任意位置跑会报错。实测在工程外执行 newt build 报 unable to load project.yml 类错误。
代理环境变量：newt new 与 newt upgrade 都走 git HTTPS，离线/受限网络先 export https_proxy；Go 侧构建则用 GOPROXY。
install 已成历史：1.15.0 只有 upgrade，网上老命令照抄会报 unknown command。
target show 与 target list 等价，复数形式的 newt targets 不存在。
sim 目标没有 size：体积统计只对真机目标有意义。
build_profile 影响 newt run：debug 档完整调试符号，optimized 档优化等级高；切换 profile 后建议 clean 再 build。

九、常见问题（FAQ）

Q1：newt help 能看单命令帮助吗？ A：可以，newt help <命令> 或 newt <命令> -h。例如 newt help target 输出全部 18 个 target 子命令说明（本文第四章实录）。

Q2：newt build 提示找不到 app 或 bsp？ A：确认 target set 的 app/bsp 路径拼写；bsp 前缀 @ 表示仓库内路径（@apache-mynewt-core/hw/bsp/native），少了 @ 会被当作工程内路径解析失败。

Q3：newt upgrade 后本地对 repos/ 内代码的修改丢了？ A：upgrade 会把仓库恢复到锚点状态。本地改动请 fork 或用 patch 文件管理；紧急恢复可用 newt upgrade -f 强制重置。

Q4：如何列出所有可用 BSP？ A：newt vals bsp；或直接看 repos/apache-mynewt-core/hw/bsp/ 目录名。选 BSP 时注意其 CPU 架构与编译器配置匹配。

Q5：newt run 想跳过 gdb 直接跑 sim？ A：直接执行产物：bin/targets/<名>/app/<应用>/<应用>.elf。加 --uart0 <字符设备> 可把控制台指到指定设备（实测 FIFO 不行，必须 pty，见实战篇）。

Q6：size 命令对 sim 目标为何报错？ A：sim 目标编译为宿主 Linux 程序，Flash/RAM 段无意义，newt 直接拒绝（实测报 not supported for sim targets）。真机目标才输出表格。

Q7：一个工程能放多少个 target？ A：targets/ 下每个目录一个，数量无限制。实测工程内 my_blinky_sim 与 sim_demo 并存互不影响；但 build 不带参数时会构建全部 target。

Q8：newt 命令报 unable to load project.yml？ A：当前目录不在工程内。cd 到工程根目录（含 project.yml）或其子目录再执行。

Q9：如何看某 target 的 syscfg 合并结果？ A：newt target config <目标> 生成 generated/ 下的合并配置，再用 grep 检索具体宏（例如 LED_BLINK_PIN 在 generated/include 下的头文件中）。

Q10：有没有离线可用 newt new 的办法？ A：先用一次在线 newt new 生成工程模板，之后把模板目录留存拷贝即可离线创建；newt 本体二进制也是独立的，拷贝 /usr/local/bin/newt 到新机器即可用（前提 Go 工具链仅为构建 newt 所需，运行期不需要）。

十、参考链接

Newt 官方手册：https://mynewt.apache.org/latest/newt/index.html
Mynewt 快速开始：https://mynewt.apache.org/latest/os/get_started/get_started.html
newt 源码仓库：https://github.com/apache/mynewt-newt
Mynewt 1.15.0 发行页：https://dlcdn.apache.org/mynewt/apache-mynewt-1.15.0/