基于Git和Tcl脚本的Vivado工程管理

参考文章：Version control for Vivado projects, 2014—— Jeff Johnson
  用Git做Vivado的版本控制，早在2014年就已经有人做了相关的工作。网上也有很多相关的文章介绍这个，但总感觉不是很方便。用Git做版本控制，主要就是对工程存档备份，在需要的时候方便回退版本。综合实现后的Vivado工程动辄上百兆，不方便直接用Git管理，工程中大部分都是Vivado生成的文件，所以用Tcl脚本重建工程是主流的选择。本文主要分享我的Vivado工程管理方法。

工程目录

• project_name （工程名称）
  • ip_repo （存放用户自定义IP）
  • src
    • hdl （存放用户自己写的hdl代码）
    • constrs （存放用户自己写的约束文件）
    • bd （存放生成Block Design的Tcl脚本）
  • project_name （Vivado工程）
  • build.tcl （重建Vivado工程的Tcl脚本）
  • build.bat （双击开始重建工程）
  • .gitignore

  看上面这个工程目录结构，可以看出来我这里的做法就是把所有用户生成、用户配置的文件都放到Vivado工程目录的上一层。Vivado工程目录下都是Vivado生成的文件，这样做的一个好处就是，一旦我想要回退版本，只要把这个Vivado工程文件夹删了就好了。然后git回档之后，用build.tcl重建工程。

一些准备

• Vivado Desigin Suite Tcl Command Reference Guide
• 基本的Git版本管理方法

  在Vivado的Tcl Console里，可以看到我们在图形界面上做的所有操作都是一条条Tcl命令，Vivado的Tcl命令可以参看上面的文档。我们不一定要都熟悉，在要用到的时候去查阅就行。Git版本管理的相关资料网上也很多，大概了解之后多用了自然就熟悉了。

导出创建Block Design的Tcl脚本

  首先我们要有一个Vivado工程，目录结构和前面我列的那个类似就行，所有用户编写的文件放在和Vivado工程文件夹同级的目录下。
  如果工程中有Block Design，先打开Block Design；如果没有就可以直接导出用于创建工程的Tcl脚本了。
  “File->Export->Export Block Design …”
  把文件导出到事先约定的project_name/src/bd/目录下。在Vivado工程中调用这个Tcl脚本就可以创建Block Desigin。

导出创建工程的Tcl脚本

  导出这个脚本和前一个创建Block Design的脚本没有前后依赖关系，先导出哪个都行。
  “File->Project->Write Tcl”

  这里勾选Copy sources to new project或者不勾选都可以，因为这个选项只对那些Local to Project的源文件有效。
  勾选的话，那些Local to Project的源文件都会复制一份到新的工程里。怎样算是Local to Project呢？就是那些在xxxx.srcs目录下的，在创建源文件是默认的路径。如果按照我们前面的工程目录规划，我们的工程里只有Block Desigin相关的文件是Local to Project的，所以那些文件会以import_files的方式复制到新的工程里；不勾选的话，所有Local to Project的源文件都会以add_files的方式被添加到新的工程里。不管是哪种方式，我们都不想要，因为我们要重新创建Block Design，而不是用原来的。
  Vivado就是这个地方不太人性化。最理想的情况下其实是勾选Copy sources to new project并且勾选Recreate Block Designs using Tcl，这样的话按理说就能一步到位，只用一个Tcl文件重建整个工程。但实际使用发现，它不仅会把原来的文件import一份，然后又自己生成了一份，非常不友好。
  有一个简便的方法，就是把那个“一步到位”的文件里的import Block Design相关的文件都删掉。但我不太喜欢这个做法，我觉得把创建Bloick Design相关的Tcl单独存放更加便于维护。因为如果工程结构稳定了，build.tcl这个文件基本就不需要改了，每次Block Design的更新，我们只要维护那个用来创建Block Deign的Tcl脚本就好了（重新导出build.tcl并进行修改的工作量远大于更新Block Design的Tcl）

修改build.tcl

  要修改的地方主要就是和Block Design相关的内容，不要把创建Block Design生成的bd文件、xxx_wrapper.v文件import进来就行。

创建Block Design

  将import Block Desigin 相关的命令用source Block Design的Tcl脚本来替换，如有需要的话可以用make_wrapper命令将Block Desigin打包。

# create block design
source $origin_dir/src/bd/git_vivado_demo_bd.tcl; # use your bd tcl name

# create wrapper
make_wrapper -files [get_files $design_name.bd] -top -import

origin_dir和工程创建路径

  build.tcl有一个隐患就是，如果运行的路径不在build.tcl所在目录，它就找不到源文件了，因为路径的相关位置关系错了。build.tcl中默认是将新的工程创建在运行的路径下，更好地选择应该是将新的工程创建在和build.tcl同一路径下。因此需要做下面的修改：

• 修改 origin_dir

set origin_dir "."

替换为

set origin_dir [file dirname [info script]]

• 修改create_project 的路径

create_project ${_xil_proj_name_} ./${_xil_proj_name_} -part xc7vx690tffg1927-2

替换为

create_project ${_xil_proj_name_} $origin_dir/${_xil_proj_name_} -part xc7vx690tffg1927-2

build.bat

  build.bat通过命令行的方式调用vivado重建工程，这个要求Vivado的路径添加到PATH环境变量里。也可以先打开Vivado，然后在Tcl Console中运行build.tcl。

vivado -mode batch -source build.tcl

工程示例

• 使用Git管理Vivado工程 - gitee

补充说明 20230530

  今天才看到在ug892的第五章中介绍了在Vivado2020对版本管理已经有了更好的支持，我的文章里的管理方法只适用于Vivado2019以及更早以前的版本。