embedded-autobuild

embedded-autobuild 是一个实用脚本库，旨在简化从源码构建目标 IDE 工程的流程。该脚本库通过 JSON 文件管理工程配置，并使用 IDE 的命令行接口快速实现项目的重建与管理，减少手动配置的繁琐步骤。

特性

• 使用 JSON 文件保存硬件设计、应用程序配置、BSP 设置等项目配置。
• 支持多个 IDE 工具链，便于多平台开发或切换开发环境。
• 支持自动化构建，确保在多次迭代开发中保持一致性。

支持的开发工具

本项目目前支持以下 Xilinx 工具链版本：

• Xilinx SDK 版本：2017.1 ~ 2019.2
• Xilinx Vitis 版本：2019.2 ~ 2023.1
• Xilinx Vitis Classic 版本：2023.2 及以上

工程配置

在使用脚本前，请参考以下文档配置对应平台：

• Xilinx 平台配置指南

项目结构

• platform/ - 包含各平台构建工具脚本
• generic_variables.mk - 使用 make 工具构建时的基本变量声明
• generic.mk - 提供若干实用构建目标
• template.mk - 基于 make 的构建模板
• template.bat - 基于 Windows 批处理文件的构建模板

快速开始

1. 将项目添加为 submodule

   在目标项目的根目录下运行以下命令，将 embedded-autobuild 项目作为 scripts 文件夹的子模块：

   git submodule add https://git.gatsby.icu/gatsby/embedded-autobuild.git scripts
   

2. 初始化并更新子模块

   如果已经有子模块配置，请使用以下命令初始化并更新子模块：

   git submodule update --init --recursive
   

   若需更新子模块，使用以下命令：

   git submodule update --remote
   

3. 添加配置文件

   将对应平台的配置模板文件拷贝到工程根目录：

   cp ./scripts/platform/<your_platform>/template.json ./config.json
   

   请参照对应平台配置说明，根据实际需要修改配置文件。

4. 添加构建脚本

   1. 如果使用 make 进行工程构建，可以基于 template.mk 编写自己的 Makefile：

      cp ./scripts/template.mk Makefile
      

      其内容如下，只需指定 PLATFORM 和 CONFIG_FILE 即可。默认在当前工作路径的 build 文件夹下构建工程：

      include scripts/generic_variables.mk
      
      PLATFORM := <your_platform> # eg. xilinx
      CONFIG_FILE := <config_file> #eg. $(PROJECT)/config.json
      
      include scripts/generic.mk
      

      你还可以根据需求追加更多自定义构建目标。默认的构建目标如下：

      • all: 构建并编译配置文件中所有的工程
      • project: 仅构建工程
      • build: 编译所有已配置工程
      • sdkopen: 打开对应开发工具
      • clean: 清除当前编译结果
      • reset: 删除所有已构建工程

   2. 对于 Windows 系统，还支持通过批处理文件或 PowerShell 脚本实现自动化构建。可基于 template.bat 编写自己的批处理脚本：

      cp ./scripts/template.bat make.bat
      

      该模板内容如下，需指定以下参数：

      • platform: 使用的平台
      • pltform_ver: 平台工具版本
      • work_dir: 工作目录（即构建工程存储的目录）
      • config: 配置文件
      • tools_dir: 平台工具脚本目录

      @echo off
      set "platform=xilinx"
      set "pltform_ver=2019.1"
      set "work_dir=%~dp0build"
      set "config=%~dp0config.json"
      set "tools_dir=%~dp0scripts\platform\%platform%"
      
      REM Set up environment
      call "%tools_dir%\setenv.bat" "%pltform_ver%"
      if "%ERRORLEVEL%" neq "0" (
          echo Error: Failed to initialize environment.
          pause >nul
          exit /b 1
      )
      
      REM Build project
      call "%tools_dir%\build.bat" "%config%" "%work_dir%"
      if "%ERRORLEVEL%" neq "0" (
          echo Error: Failed to build project.
          pause >nul
          exit /b 1
      )
      
      REM Launch SDK
      call "%tools_dir%\launch.bat" "%pltform_ver%" "%work_dir%"
      if "%ERRORLEVEL%" neq "0" (
          echo Error: Failed to launch SDK.
          pause >nul
          exit /b 1
      )
      
      exit /b 0
      

      其中 %~dp0 表示当前 .bat 文件所在目录。上述模板配置假设配置文件和相关工具脚本与 .bat 在同一目录，并在该目录下的 build 文件夹中创建工程。该脚本实现了自动创建工程并完成相关配置最后加载对应 IDE 的功能。

常见问题

1. 在 Xilinx Vitis 中打开构建的工程后，点击符号时可能无法跳转，并且在 IDE 左下角会显示如下错误信息：

   Could not find symbol 'XXXX' in index
   

   这是因为源文件在导入时被直接链接或复制到了工程目录中，未触发 C++ Indexer 更新索引。此外，新版本的 Vitis 没有直接的命令或 UI 选项来重建或更新索引。最简单的解决方法是随意打开一个源文件，在任意行末输入一个空格并保存。IDE 会自动删除该空格，不会对源文件造成任何更改，但此操作可触发索引的自动更新。

待办事项

• 支持 Xilinx SDK 的 XSCT 接口
• 支持 Xilinx Vitis 的 XSCT 接口
• 增加对 Xilinx Vitis Python API 的支持
• 完善 Xilinx 工具下 FSBL 补丁的功能
• 支持 IAR 工具链

贡献指南

如果您对该项目有任何改进意见或功能需求，欢迎提交 issue 或 pull request，commit 格式请参考 Angular convention.