project generator 简单使用

1 progen 资源

• 0）简介：progen（project-generator，项目生成器）是 ARM 编写的，基于 Python 的，让我们的项目跨工具的神器。所谓跨工具，类比一下 Java 的跨平台，即代码编写完成后，可以生成为基于 uVision、IAR、Makefile（cmake）等编译工具的项目。

• 1）官网：

  • progen: https://pypi.org/project/project-generator/
  • progendef: https://github.com/project-generator/project_generator_definitions

• 2）官方示例：

  • https://github.com/project-generator/project_generator_frdm_boards_example
  • https://github.com/project-generator/project_generator_mbed_examples

• 3）本例：

  • 学习 B 站 UP 主 “江协科技” STM32 视频（https://jiangxiekeji.com/）
  • 基于光子物联的 STM32G431CBT6 开发板
  • ll 库代码：https://gitee.com/luyaocf/demo-jxtech_stm32g4_ll.git

2 使用简介

• 1）progen 的几个组件：

  • （1）Record：基于 YAML 语法的配置文件，有 3 种：

    • 项目列表文件 projects.yaml，声明配置项、模块、项目等
    • 项目定义文件，即主工程文件，其中定义工程名称，开发板，等
    • 模块文件，定义模块的头文件与源文件

  • （2）Tool：泛指嵌入式开发工具，如 uVision、IAR、CoIDE、Makefile（gcc/armcc/cmake）等等

  • （3）Target：泛指 mcu。其内部指定 MCU 的 RAM、ROM、CPU 内核、SFD、烧录算法等令牌。progen 根据 target 生成指定 tool 的工程文件，如 Keil5 的 .uvprojx、IAR 的 .ewp 等

• 2）progen 的几个命令：

  • （1）init：将当前项目初始化为 progen 项目。当你已经有一个 uVision5 项目时，可以在其根目录直接使用该命令，将该项目变成一个 progen 项目。然而就像 PCB 中的自动布线一样，可以使用但不要完全使用，因为我们想要的不是 progen <-> uVision，而是 progen -> uVision、IAR、CMake 等等

  • （2）generate：生成指定 Tool 的项目。当我们有一个 progen 项目时，可使用该命令生成基于 Tool 的任何工程

  • （3）clean：清理生成的项目。

  • （4）list：列出当前 progen 支持的 targets（MCU）, tools（IDE 或 toolchain） 或工程

  • （5）build：构建指定工程。

2.1 安装

• 1）安装 Python

• 2）安装 progen

  pip install project-generator
  

2.2 添加 target（可选）

• 1）progen 安装完成后，在目录 %PYTHON_HOME%\Lib\site-packages\project_generator_definitions\mcu 下，按照厂商列出了 progen 支持的所有 mcu target。但总有些不常用的 mcu 尚未支持，需要我们手动创建 target。比如我这里使用的 STM32G431CBT6 芯片，progen 尚未支持。

• 2）幸运的是我们不用手动编写 target 配置文件，progen 提供了 progendef 命令来帮我们自动生成添加 target 的配置文件：

  • （1）使用 STM32CubeMX 生成一个基于 STM32G431CBT6 的 uVision5 项目，如 STM32G431CBT6.uvprojx。（当然，其它厂商的 mcu 只要提供了基于 Keil uVision5 的项目都可以。事实上，progen 还支持基于 IAR 项目的生成。）

  • （2）找到 STM32G431CBT6.uvprojx 所在目录，在命令行中执行以下命令：

     progendef create -m stm32g431cbtx -t uvision5 -f STM32G431CBT6.uvprojx
    

  • （3）将生成的 stm32g431cbtx.yaml 文件复制到
    %PYTHON_HOME%\Lib\site-packages\project_generator_definitions\mcu\st\ 目录下，然后我们在生成 uVision5 项目时即可引用到它。

2.3 替换 CMake 模板（可选）

• 1）progen 中使用的 cmake 版本为 3.6，而 STM32CubeMX 生成的代码中 cmake 版本最新为 3.27（于 2024.3.8），所以这里更新一下 progen 的 cmake 模板。

• 2）首先尝试在项目中指定 cmake 模板，发现无法生效。最终发现：

  • （1）首先找到 %PYTHON_HOME%\Lib\site-packages\project_generator\templates 目录
  • （2）备份 cmakelist_gccarm.tmpl 文件
  • （3）将本项目 records/tools/cmakelist_gccarm.tmpl 文件替换该文件

• 3）对比过后，新版本的 cmake 编译速度提升了，配置内容清晰，生成的目标文件减少，使用确实更加方便。

2.4 创建 progen 项目

• 1）ARM 官方的 DAPLink 项目是基于 progen 应用的一个项目，我们可以参考它来使用。

• 2）我们可以先使用 STM32CubeMX 生成 uVision5 项目和 CMake 项目，然后分别在两个项目的根目录执行 progen init 命令来分别生成 progen 项目，最后提取其中的配置文件并组装成我们需要的项目。

• 3）配置完成后，便可以通过以下命令来生成项目了：

  progen generate -t cmake -v -p jxtech031_blink      # 生成 CMake 项目
  progen generate -t uvision5 -v -p jxtech031_blink   # 生成 uVision5 项目
  

• 4）项目根目录下提供了一个 generate.bat 批处理脚本，用来自动生成项目：

  -----------------------------------------------------------------------------------
         project generator
  -----------------------------------------------------------------------------------
   code    project                       code      project
  [031] jxtech031_blink                 [091] jxtech091_usart
  [032] jxtech032_waterlight            [092] jxtech092_usart_recv
  [033] jxtech033_buzzer                [093] jxtech093_usart_hex
  [034] jxtech034_keyled                [094] jxtech094_usart_txt
  [035] jxtech035_ldr                   [101] jxtech101_i2c_mpu6050
  [041] jxtech041_oled                  [102] jxtech102_i2c_mpu6050
  [051] jxtech051_exti                  [103] jxtech103_i2c_24cxx
  [061] jxtech061_timer_it              [111] jxtech111_spi_w25qxx
  [062] jxtech062_timer_externalclk     [112] jxtech112_spi_w25qxx
  [063] jxtech063_timer_pwmled          [113] jxtech113_spi_tftlcd
  [064] jxtech064_timer_pwmservo        [121] jxtech121_bkp
  [065] jxtech065_timer_pwmmotor        [122] jxtech122_rtc
  [066] jxtech066_timer_inputcapture1   [131] jxtech131_systemclk
  [067] jxtech067_timer_inputcapture2   [132] jxtech132_mode_sleep
  [068] jxtech068_timer_encoderspeed    [133] jxtech133_mode_stop
  [071] jxtech071_adc_singlechannel     [134] jxtech134_mode_standby
  [072] jxtech072_adc_multichannel      [135] jxtech135_mode_shutdown
  [080] jxtech080_memory                [141] jxtech141_iwdg
  [081] jxtech081_dma                   [142] jxtech142_wwdg
  [082] jxtech082_dma_adc               [151] jxtech151_flash
  
  [1] generate all     [2] clean all    [0] exit
  
  Input the code:
  

  • 要生成多个工程时，可以输入多个编号，以空格分隔。

3 总结

• 1）使用 progen 带来的几点好处：

  • （1）跨工具。对于一个代码仓库的协作开发来说，无疑是极大的方便，它可以满足习惯于不同开发工具的协作者。

  • （2）破除木桶效应。如果你还在纠结 Keil 的丑界面，CLion 基于 OpenOCD 的基本调试，ARM GCC 的编译效率，那么 progen 值得拥有。它可以让我们可以使用 Keil uVision 方便的调试功能 + CLion 的代码提示功能 + ARMCLANG 强大的代码编译能力。

  • （3）减少代码量。当我们学习一个教程时，往往会按照章节创建对应的项目，无疑会产生非常多的冗余源文件，比如 STM32 的 HAL 库文件。使用 progen 可以在 projects.yaml 定义所有的项目，然后将 HAL 库文件声明为模块并复用它。

• 2）不建议使用的情况：

  • 单个项目。如果只有单个项目，即使需要跨工具开发，使用 STM32CubeMX 会比使用 progen 更有性价比。