# 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/xilinx/HOWTO.md)

## 项目结构

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

## 快速开始

1. **将项目添加为 `submodule`**

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

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

2. **初始化并更新子模块**

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

    ```shell
    git submodule update --init --recursive
    ```

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

    ```shell
    git submodule update --remote
    ```

3. **添加配置文件**

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

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

    **请参照对应平台[配置说明](#工程配置)，根据实际需要修改配置文件**。

4. **添加构建脚本**

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

        ```shell
        cp ./scripts/template.mk Makefile
        ```

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

        ```makefile
        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`](./template.bat) 编写自己的批处理脚本：

       ```shell
       cp ./scripts/template.bat make.bat
       ```

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

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

       ```bat
       @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 左下角会显示如下错误信息：

    ```plaintext
    Could not find symbol 'XXXX' in index
    ```

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

2. 在 Windows 上运行 `.bat` 构建脚本时可能会出现以下错误：

    ```plaintext
    Failed to create file symbolic link using mklink: 你没有足够的权限执行此操作。
    ```

    这是因为 `tcl` 在 Windows 上只能为文件夹创建符号链接，无法直接为文件创建链接。为文件创建符号链接需要使用 `mklink` 命令，该命令要求管理员权限。解决方法是以管理员身份运行 `.bat` 脚本。

## 待办事项

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

## 贡献指南

如果您对该项目有任何改进意见或功能需求，欢迎提交 issue 或 pull request，commit 格式请参考 [Angular convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit).