167 lines
5.8 KiB
Markdown
167 lines
5.8 KiB
Markdown
# 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 会自动删除该空格，不会对源文件造成任何更改，但此操作可触发索引的自动更新。
|
||
|
||
## 待办事项
|
||
|
||
- [x] 支持 Xilinx SDK 的 XSCT 接口
|
||
- [x] 支持 Xilinx Vitis 的 XSCT 接口
|
||
- [ ] 增加对 Xilinx Vitis Python API 的支持
|
||
- [ ] 完善 Xilinx 工具下 FSBL 补丁的功能
|
||
- [ ] 支持 IAR 工具链
|
||
|
||
## 贡献指南
|
||
|
||
如果您对该项目有任何改进意见或功能需求，欢迎提交 issue 或 pull request，commit 格式请参考 [Angular convention](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional).
|